194 lines
6.4 KiB
Plaintext
194 lines
6.4 KiB
Plaintext
---
|
|
title: Reactions
|
|
description: Configure what AO does when CI fails, reviews arrive, agents get stuck, or PRs become ready.
|
|
---
|
|
|
|
Reactions are AO's automatic responses to session events. They decide whether AO should message an agent, notify a human, or mark a PR as ready for a merge action.
|
|
|
|
You do not need to configure reactions to start. AO ships with defaults for CI failures, review comments, merge conflicts, stuck agents, input prompts, and completed sessions.
|
|
|
|
## Common Recipes
|
|
|
|
### Watch Without Auto-Recovery
|
|
|
|
Use this while onboarding AO to a sensitive repo. You still see notifications, but AO stops sending recovery prompts to agents automatically.
|
|
|
|
```yaml title="agent-orchestrator.yaml"
|
|
reactions:
|
|
ci-failed:
|
|
auto: false
|
|
changes-requested:
|
|
auto: false
|
|
bugbot-comments:
|
|
auto: false
|
|
merge-conflicts:
|
|
auto: false
|
|
```
|
|
|
|
### Give CI Recovery More Attempts
|
|
|
|
```yaml title="agent-orchestrator.yaml"
|
|
reactions:
|
|
ci-failed:
|
|
retries: 3
|
|
message: |
|
|
CI is failing. Read the failing check logs, reproduce locally when possible,
|
|
fix the smallest cause, and push the correction.
|
|
```
|
|
|
|
### Escalate Stuck Agents Faster
|
|
|
|
```yaml title="agent-orchestrator.yaml"
|
|
reactions:
|
|
agent-stuck:
|
|
priority: urgent
|
|
threshold: "7m"
|
|
```
|
|
|
|
### Notify On Merge-Ready PRs
|
|
|
|
`approved-and-green` does not merge by default. It notifies you that the PR is ready.
|
|
|
|
```yaml title="agent-orchestrator.yaml"
|
|
reactions:
|
|
approved-and-green:
|
|
auto: false
|
|
action: notify
|
|
priority: action
|
|
```
|
|
|
|
<Callout type="warning">
|
|
`auto-merge` is currently an intent flag, not a bypass. AO does not ignore branch protection, reviews, or failing checks.
|
|
</Callout>
|
|
|
|
## Default Reactions
|
|
|
|
| Key | When it fires | Default action | Notes |
|
|
|-----|---------------|----------------|-------|
|
|
| `ci-failed` | CI check fails | `send-to-agent` | Sends the agent a recovery prompt |
|
|
| `changes-requested` | Human requests changes | `send-to-agent` | Sends review feedback to the agent |
|
|
| `bugbot-comments` | Known automation leaves actionable feedback | `send-to-agent` | Keeps bot feedback separate from human reviews |
|
|
| `merge-conflicts` | PR has conflicts | `send-to-agent` | Asks the agent to resolve conflicts |
|
|
| `approved-and-green` | PR is approved and checks pass | `notify` | Does not merge unless future SCM support enables it |
|
|
| `agent-stuck` | Agent has been inactive past threshold | `notify` | Urgent by default |
|
|
| `agent-needs-input` | Agent is waiting for human input | `notify` | Urgent by default |
|
|
| `agent-exited` | Session exits unexpectedly or is killed | `notify` | Urgent by default |
|
|
| `all-complete` | Session finishes cleanly | `notify` | Includes summary by default |
|
|
| `agent-idle` | Reserved | `send-to-agent` | Defined for future idle handling |
|
|
|
|
## Action Types
|
|
|
|
| Action | Meaning |
|
|
|--------|---------|
|
|
| `send-to-agent` | Sends `message` into the running agent session |
|
|
| `notify` | Routes an event to configured notifiers |
|
|
| `auto-merge` | Reserved merge intent; currently routes like a notification |
|
|
|
|
`send-to-agent` is the autonomous recovery path. `notify` is the human awareness path.
|
|
|
|
## Config Fields
|
|
|
|
Each reaction accepts:
|
|
|
|
| Field | Type | Purpose |
|
|
|-------|------|---------|
|
|
| `auto` | `boolean` | Whether AO should perform the automated action |
|
|
| `action` | `send-to-agent` \| `notify` \| `auto-merge` | What AO does when the reaction fires |
|
|
| `message` | `string` | Message sent to the agent or included in notification text |
|
|
| `priority` | `urgent` \| `action` \| `warning` \| `info` | Notification routing priority |
|
|
| `retries` | `number` | Max repeated agent messages before escalation |
|
|
| `escalateAfter` | `number` or duration string | Escalate after attempts or time, whichever applies |
|
|
| `threshold` | duration string | Used by stuck/idle style reactions |
|
|
| `includeSummary` | `boolean` | Include session summary in the notification |
|
|
|
|
Example:
|
|
|
|
```yaml
|
|
reactions:
|
|
changes-requested:
|
|
action: send-to-agent
|
|
retries: 2
|
|
escalateAfter: "30m"
|
|
message: |
|
|
Reviewers requested changes. Read the unresolved comments,
|
|
make the requested fixes, and push an update.
|
|
```
|
|
|
|
## Notification Routing
|
|
|
|
Reaction `priority` maps to `notificationRouting` in the global config:
|
|
|
|
```yaml title="~/.agent-orchestrator/config.yaml"
|
|
notificationRouting:
|
|
urgent: [desktop, composio]
|
|
action: [desktop]
|
|
warning: [composio]
|
|
info: [composio]
|
|
```
|
|
|
|
Named notifier instances are configured separately:
|
|
|
|
```yaml title="~/.agent-orchestrator/config.yaml"
|
|
notifiers:
|
|
desktop:
|
|
plugin: desktop
|
|
slack:
|
|
plugin: slack
|
|
webhookUrl: ${SLACK_WEBHOOK_URL}
|
|
```
|
|
|
|
## Per-Project Overrides
|
|
|
|
Put reaction overrides in a local project config to affect only that project:
|
|
|
|
```yaml title="agent-orchestrator.yaml"
|
|
reactions:
|
|
ci-failed:
|
|
retries: 4
|
|
approved-and-green:
|
|
priority: info
|
|
```
|
|
|
|
Project values override global values for the same reaction key.
|
|
|
|
## CI Failure Flow
|
|
|
|
CI failure handling happens in two passes:
|
|
|
|
1. AO sends the configured `ci-failed.message` when the session first enters a failed-CI state.
|
|
2. On the next poll, AO sends a structured follow-up with the failing check names, statuses, and URLs.
|
|
|
|
The second message does not consume the `ci-failed` retry budget. It exists so the agent gets both the instruction and the specific failing checks.
|
|
|
|
## Review Backlog Throttle
|
|
|
|
AO throttles review-comment lookups to avoid hammering GitHub or GitLab. Pending human comments and known automation comments are fetched at most once every two minutes per session.
|
|
|
|
Force a check when you need one immediately:
|
|
|
|
```bash
|
|
ao review-check <session-id>
|
|
```
|
|
|
|
## Event Reference
|
|
|
|
| Event | Reaction |
|
|
|-------|----------|
|
|
| `ci.failing` | `ci-failed` |
|
|
| `review.changes_requested` | `changes-requested` |
|
|
| `automated_review.found` | `bugbot-comments` |
|
|
| `merge.conflicts` | `merge-conflicts` |
|
|
| `merge.ready` | `approved-and-green` |
|
|
| `session.stuck` | `agent-stuck` |
|
|
| `session.needs_input` | `agent-needs-input` |
|
|
| `session.killed` | `agent-exited` |
|
|
| `summary.all_complete` | `all-complete` |
|
|
|
|
## Next Steps
|
|
|
|
<Cards>
|
|
<Card title="Projects" href="/docs/configuration/projects" description="Apply reaction overrides to one project." />
|
|
<Card title="Webhook notifier" href="/docs/plugins/notifiers/webhook" description="Send AO events to any HTTPS endpoint." />
|
|
<Card title="Configuration" href="/docs/configuration" description="Understand global registry vs local project config." />
|
|
</Cards>
|