Skip to main content
Reactions are the core automation mechanism in Agent Orchestrator. They define how the system responds to events like CI failures, review comments, and agent state changes—automatically handling routine issues without human intervention.

​
Reaction System Overview

When an event occurs (e.g., CI fails, review requested), the orchestrator:
1

Check Reaction Config

Looks up the reaction configuration for the event type
2

Auto-Handle

If auto: true, performs the configured action automatically
3

Escalate

If retries exhausted or timeout reached, escalates to human notification
Push, not pull. The human never needs to check on agents—the orchestrator notifies when judgment is required. Source: packages/core/src/lifecycle-manager.ts:422-498

​
Built-in Reactions

Agent Orchestrator includes 8 built-in reactions with sensible defaults:

​
ci-failed

Triggered when CI checks fail on a PR. 
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    message: "CI is failing on your PR. Run `gh pr checks` to see the failures, fix them, and push."
    retries: 2
    escalateAfter: 2  # Escalate to human after 2 failures
​
auto
boolean
default:"true"
Enable automatic handling
​
action
enum
default:"send-to-agent"
What to do when CI fails:
  • send-to-agent — Send failure info to agent to fix
  • notify — Immediately notify human
​
retries
number
default:"2"
How many times to let the agent retry before escalating
​
escalateAfter
number
Escalate to human after this many failures

​
changes-requested

Triggered when a reviewer requests changes. 
reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    message: "There are review comments on your PR. Check with `gh pr view --comments` and `gh api` for inline comments. Address each one, push fixes, and reply."
    escalateAfter: 30m  # Escalate if not resolved in 30 minutes
​
escalateAfter
string
Time-based escalation. Supports: 10m, 1h, 30m
The agent automatically fetches review comments and attempts to address them. Only escalates to human if it can’t resolve within the time limit.

​
bugbot-comments

Triggered when automated review tools (linters, security scanners) leave comments. 
reactions:
  bugbot-comments:
    auto: true
    action: send-to-agent
    message: "Automated review comments found on your PR. Fix the issues flagged by the bot."
    escalateAfter: 30m
Detects bot comments from common tools:
  • GitHub Actions annotations
  • ESLint reporters
  • Security scanners
  • Coverage reporters

​
merge-conflicts

Triggered when the PR branch has merge conflicts with the base branch. 
reactions:
  merge-conflicts:
    auto: true
    action: send-to-agent
    message: "Your branch has merge conflicts. Rebase on the default branch and resolve them."
    escalateAfter: 15m
The agent will attempt to rebase and resolve conflicts. Complex conflicts may require human intervention.

​
approved-and-green

Triggered when PR is approved by reviewers AND CI passes. 
reactions:
  approved-and-green:
    auto: false  # Disabled by default — requires explicit opt-in
    action: notify
    priority: action
    message: "PR is ready to merge"
Auto-merge is disabled by default for safety. Enable only if you have:
  • Comprehensive CI/CD tests
  • Required code review approval
  • High confidence in agent code quality
To enable auto-merge: 
reactions:
  approved-and-green:
    auto: true  # Enable auto-merge
    action: auto-merge  # Change action from notify to auto-merge
See Auto-Merge Configuration below for details.

​
agent-stuck

Triggered when agent shows no activity for a duration. 
reactions:
  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 10m  # Consider stuck after 10 minutes idle
​
threshold
string
default:"10m"
Duration of inactivity before considering agent “stuck”
Sends urgent notification to human to investigate.

​
agent-needs-input

Triggered when agent asks a question or hits a permission prompt. 
reactions:
  agent-needs-input:
    auto: true
    action: notify
    priority: urgent
Examples:
  • “Should I proceed with this refactoring?”
  • Permission prompt for file operations
  • Confirmation needed for destructive changes

​
agent-exited

Triggered when agent process exits unexpectedly. 
reactions:
  agent-exited:
    auto: true
    action: notify
    priority: urgent
Causes:
  • Agent crashed
  • Out of memory
  • Unhandled error
  • Manual termination

​
all-complete

Triggered when all spawned agents finish their work. 
reactions:
  all-complete:
    auto: true
    action: notify
    priority: info
    includeSummary: true
​
includeSummary
boolean
default:"true"
Include summary of all sessions in the notification
Source: packages/core/src/config.ts:215-278

​
Reaction Configuration Schema

All reactions support these fields:
​
auto
boolean
required
Enable automatic handling. If false, the reaction is disabled.
​
action
enum
required
What action to take:
  • send-to-agent — Send message to agent to handle
  • notify — Send notification to human
  • auto-merge — Automatically merge the PR (only for approved-and-green)
​
message
string
Custom message to send to agent (for send-to-agent action) or human (for notify action).
​
priority
enum
Notification priority level:
  • urgent — Critical issues requiring immediate attention
  • action — Action required but not urgent
  • warning — Something to be aware of
  • info — Informational only
Controls which notifiers receive the message (see Notification Routing).
​
retries
number
How many times to retry send-to-agent before escalating to human.
​
escalateAfter
number | string
Escalation condition:
  • Number: Escalate after this many failures (e.g., 2 = after 2 failed attempts)
  • String: Escalate after this duration (e.g., 30m, 1h)
​
threshold
string
Duration threshold for time-based triggers (e.g., agent-stuck).Examples: 10m, 30m, 1h
​
includeSummary
boolean
Include summary of all sessions in the notification (for all-complete).
Source: packages/core/src/types.ts:763-788

​
Global Reaction Configuration

Define default reaction behavior for all projects: 
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3  # More aggressive retry
    escalateAfter: 3
  
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 1h  # Give agent more time
  
  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 15m  # More lenient stuck detection

​
Per-Project Reaction Overrides

Override global reactions for specific projects: 
# Global defaults
reactions:
  approved-and-green:
    auto: false  # Auto-merge disabled globally
    action: notify

projects:
  # Trusted project: enable auto-merge
  frontend:
    repo: org/frontend
    path: ~/frontend
    reactions:
      approved-and-green:
        auto: true  # Override: enable auto-merge for this project
        action: auto-merge
  
  # High-risk project: more conservative
  payment-service:
    repo: org/payment-service
    path: ~/payment-service
    reactions:
      ci-failed:
        auto: false  # Override: disable auto-fix, always notify human
        action: notify
        priority: urgent
Per-project reactions merge with global reactions. You only need to specify the fields you want to override.

​
Auto-Merge Configuration

Auto-merge is the most aggressive automation option. Use with caution.

​
Requirements for Auto-Merge

Before enabling auto-merge, ensure:
1

Comprehensive CI

Your CI pipeline includes:
  • Unit tests
  • Integration tests
  • Linting
  • Type checking
  • Security scanning
2

Required Approvals

GitHub branch protection requires:
  • At least one approval
  • Passing CI checks
  • Up-to-date branch
3

Agent Trust

You’ve validated agent quality on several PRs manually first.

​
Enable Auto-Merge Globally

reactions:
  approved-and-green:
    auto: true
    action: auto-merge
    priority: info  # Notify after merge completes

​
Enable Auto-Merge per Project

projects:
  my-app:
    repo: org/my-app
    path: ~/my-app
    reactions:
      approved-and-green:
        auto: true
        action: auto-merge

​
Disable Auto-Merge (Default)

reactions:
  approved-and-green:
    auto: false  # Disabled (default)
    action: notify
    priority: action
    message: "PR is ready to merge"
With auto-merge disabled, you’ll receive an “action” priority notification when PRs are ready, and merge them manually. Source: examples/auto-merge.yaml

​
Escalation Rules

Escalation determines when to notify a human after automatic handling fails.

​
Retry-Based Escalation

Escalate after a number of failed attempts: 
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3
    escalateAfter: 3  # Notify human after 3 failed fix attempts
Flow:
  1. CI fails → agent attempts fix #1
  2. Still failing → agent attempts fix #2
  3. Still failing → agent attempts fix #3
  4. Still failing → escalate to human (urgent notification)

​
Time-Based Escalation

Escalate after a duration: 
reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m  # Notify human if unresolved in 30 minutes
Flow:
  1. Review comments received → agent starts addressing
  2. Timer starts (30 minutes)
  3. If agent resolves within 30m → no escalation
  4. If unresolved after 30m → escalate to human (urgent notification)

​
Mixed Escalation

Combine both approaches: 
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 5
    escalateAfter: 1h  # Escalate after 5 failures OR 1 hour, whichever comes first

​
Custom Reaction Messages

Override default messages: 
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    message: |
      CI checks are failing. Please:
      1. Run `gh pr checks` to see failures
      2. Run tests locally: `pnpm test`
      3. Fix the issues and push
      4. Verify CI passes
    retries: 2
Custom messages for notifications: 
reactions:
  approved-and-green:
    auto: false
    action: notify
    priority: action
    message: "🎉 PR approved and CI green! Ready to merge: {{prUrl}}"
Messages support template variables like {{prUrl}}, {{sessionId}}, {{projectId}}.

​
Disabling Reactions

Disable a reaction by setting auto: false: 
reactions:
  changes-requested:
    auto: false  # Disable automatic handling
    action: notify  # Always notify human immediately
    priority: action
When disabled, the orchestrator immediately notifies humans instead of attempting automatic handling.

​
Testing Reactions

Test your reaction configuration: 
# Spawn an agent on a test issue
ao spawn my-app TEST-123

# Watch the dashboard
ao status

# Trigger events manually:
# - Push a failing commit (to trigger ci-failed)
# - Request changes on the PR (to trigger changes-requested)
# - Approve the PR (to trigger approved-and-green)
Monitor logs to see reaction behavior: 
# Check orchestrator logs
tail -f ~/.agent-orchestrator/logs/orchestrator.log

​
Complete Example

A production-ready reaction configuration: 
reactions:
  # Auto-fix CI failures with retries
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3
    escalateAfter: 3
  
  # Auto-address review comments with timeout
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 45m
  
  # Auto-fix bot comments
  bugbot-comments:
    auto: true
    action: send-to-agent
    escalateAfter: 30m
  
  # Auto-resolve merge conflicts
  merge-conflicts:
    auto: true
    action: send-to-agent
    escalateAfter: 20m
  
  # Notify when ready (auto-merge disabled for safety)
  approved-and-green:
    auto: false
    action: notify
    priority: action
    message: "PR ready to merge"
  
  # Notify when agent is stuck
  agent-stuck:
    auto: true
    action: notify
    priority: urgent
    threshold: 12m
  
  # Urgent notification when agent needs input
  agent-needs-input:
    auto: true
    action: notify
    priority: urgent
  
  # Urgent notification on agent crash
  agent-exited:
    auto: true
    action: notify
    priority: urgent
  
  # Summary when all done
  all-complete:
    auto: true
    action: notify
    priority: info
    includeSummary: true

​
Next Steps

Notifications

Configure how reactions notify you via Slack, Discord, etc.

Projects

Set up per-project reaction overrides

Build docs developers (and LLMs) love

Get started for freeTalk to us