Skip to main content
Reactions are event handlers that run automatically when specific conditions occur. They handle routine tasks like forwarding CI failures to agents, so you only get notified when human judgment is needed.

​
How Reactions Work

When an event occurs:
1

Event detected

The orchestrator detects a CI failure, review comment, approval, etc.
2

Check reaction config

Looks up the reaction configuration for that event type
3

Execute action

If auto: true, performs the configured action automatically
4

Escalate if needed

If thresholds are exceeded, notifies human instead
Key principle: Push, not pull. Reactions handle routine issues automatically, and only notify you when escalation is needed.

​
CI Failure Handling

Automatically send CI failures to agents for fixing: 
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 2
    escalateAfter: 2
Behavior:
  1. CI fails on a PR
  2. Orchestrator extracts failure logs
  3. Sends logs + fix instructions to the agent
  4. Agent fixes the issue and pushes
  5. CI runs again
  6. If it fails escalateAfter times, you get a notification
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3
    escalateAfter: 3

​
What Agents Receive

When CI fails, the agent gets: 
CI failed on your PR. Please fix the following errors:

TypeError: Cannot read property 'id' of undefined
  at validateUser (src/auth.ts:42:10)
  at processRequest (src/server.ts:120:5)

Failed tests:
  ✗ should validate user input (test/auth.test.ts:15)
  ✗ should handle missing user (test/auth.test.ts:28)

Please:
1. Fix the null reference error
2. Ensure all tests pass
3. Push your changes

​
Review Comment Handling

Automatically forward review comments to agents: 
reactions:
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 30m  # Escalate if not resolved in 30 minutes
Behavior:
  1. Reviewer requests changes on PR
  2. Orchestrator extracts review comments
  3. Sends comments to agent
  4. Agent addresses the feedback
  5. If unresolved after escalateAfter, you get notified
Time formats for escalateAfter:
  • 10m — 10 minutes
  • 1h — 1 hour
  • 2 — 2 retry attempts (for CI failures)
  • 30m — 30 minutes

​
Example Review Comment Message

Reviewers requested changes on your PR:

@reviewer1 commented on src/auth.ts:42:
> This null check is insufficient. What if the user object exists
> but doesn't have an id property?
>
> Consider using optional chaining: user?.id

@reviewer2 commented on src/server.ts:120:
> Missing error handling for the async call. Should wrap in try/catch.

Please address these comments and push your changes.

​
Auto-Merge Configuration

Automatically merge approved PRs with passing CI: 
reactions:
  approved-and-green:
    auto: true
    action: auto-merge
    priority: action
Behavior:
  1. PR is approved by reviewers
  2. All CI checks pass
  3. Orchestrator merges the PR automatically
  4. Session is cleaned up
  5. You get a notification (priority: action)
Only enable auto-merge if:
  • ✅ You have comprehensive CI/CD tests
  • ✅ You require code review approval
  • ✅ You trust your agents to write correct code
  • ✅ You’re not working on critical systems (finance, healthcare)
Start with auto: false and enable after building confidence.

​
Conservative Auto-Merge

Notify instead of auto-merging: 
reactions:
  approved-and-green:
    auto: false  # Don't auto-merge
    action: notify
    priority: action  # Send notification when ready
You’ll get notified when PRs are ready to merge, but you merge manually.

​
Agent Stuck Detection

Detect and notify when agents are inactive: 
reactions:
  agent-stuck:
    threshold: 10m  # Consider stuck after 10 minutes of inactivity
    action: notify
    priority: urgent
Behavior:
  1. Agent has no activity for threshold duration
  2. Orchestrator marks session as stuck
  3. You get an urgent notification
  4. You can investigate and intervene
reactions:
  agent-stuck:
    threshold: 5m
    action: notify
    priority: urgent
Good for fast-moving workflows where agents should respond quickly.

​
Per-Project Overrides

Override global reactions for specific projects: 
# Global defaults
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 2
  approved-and-green:
    auto: false
    action: notify

projects:
  # Critical project — no auto-merge
  backend:
    reactions:
      approved-and-green:
        auto: false
        action: notify
        priority: action
  
  # Experimental project — aggressive automation
  experiments:
    reactions:
      ci-failed:
        auto: true
        retries: 5  # More retries
      approved-and-green:
        auto: true  # Enable auto-merge
        action: auto-merge

​
Notification Routing

Route notifications by priority: 
notificationRouting:
  urgent: [desktop, slack]     # Agent stuck, needs input, errored
  action: [desktop, slack]     # PR ready to merge
  warning: [slack]             # Auto-fix failed
  info: [slack]                # Summary, all done
Priorities:
  • urgent: Requires immediate attention (agent stuck, errored)
  • action: Requires action but not urgent (PR ready to merge)
  • warning: Something went wrong (auto-fix failed after retries)
  • info: FYI notifications (task completed, summary)

​
Notification Channels

Configure multiple notifiers: 
notifiers:
  slack:
    plugin: slack
    webhook: ${SLACK_WEBHOOK_URL}
    channel: "#agent-updates"
  
  webhook:
    plugin: webhook
    url: https://your-service.com/webhook
    method: POST
Then route by priority: 
notificationRouting:
  urgent: [desktop, slack, webhook]
  action: [desktop, slack]
  warning: [slack]
  info: []

​
Example Configurations

​
Aggressive Automation (Auto-Merge Enabled)

# examples/auto-merge.yaml
reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 3
  
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 1h
  
  approved-and-green:
    auto: true
    action: auto-merge
  
  agent-stuck:
    threshold: 10m
    action: notify
    priority: urgent
Use case: High-trust environment, comprehensive tests, experienced agents

​
Conservative (Manual Review)

reactions:
  ci-failed:
    auto: true
    action: send-to-agent
    retries: 1
    escalateAfter: 1
  
  changes-requested:
    auto: true
    action: send-to-agent
    escalateAfter: 15m
  
  approved-and-green:
    auto: false  # Manual merge only
    action: notify
    priority: action
  
  agent-stuck:
    threshold: 5m
    action: notify
    priority: urgent
Use case: New to agent orchestration, building trust, critical systems

​
Notification-Only (No Automation)

reactions:
  ci-failed:
    auto: false
    action: notify
    priority: urgent
  
  changes-requested:
    auto: false
    action: notify
    priority: action
  
  approved-and-green:
    auto: false
    action: notify
    priority: action
Use case: Manual control, agents are learning, testing the system

​
Testing Reactions

Test your reaction configuration:
1

Spawn a test session

ao spawn my-app test-reactions
2

Create a PR with failing tests

Let the agent create a PR, or manually push code with test failures
3

Watch reaction trigger

Check if the agent receives the CI failure message:
ao open my-app-1  # Attach to see the message
4

Verify notification routing

Check that notifications arrive in configured channels (Slack, desktop)

​
Troubleshooting

​
Reactions Not Triggering

Check:
  1. Reaction is enabled 
    reactions:
  ci-failed:
    auto: true  # Must be true
  2. SCM plugin is configured 
    projects:
  my-app:
    tracker:
      plugin: github  # Must match your platform
  3. Webhooks are set up (for real-time events) GitHub webhooks are optional but recommended for immediate reactions.

​
Agent Not Receiving Messages

Check:
  1. Session is alive 
    ao status  # Check activity state
  2. Agent can receive input 
    ao send my-app-1 "test message"
  3. Review event log 
    tail -f ~/.agent-orchestrator/events.jsonl

​
Escalation Not Working

Check time format: 
# Correct
escalateAfter: 30m

# Incorrect
escalateAfter: "30 minutes"  # Won't parse
Check retry count: 
ci-failed:
  retries: 2
  escalateAfter: 2  # Escalates after 2 failures

​
Next Steps

Custom Workflows

Create advanced automation with CI/CD integration

Multi-Project Setup

Manage reactions across multiple repositories

Build docs developers (and LLMs) love

Get started for freeTalk to us