> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/agent-orchestrator/llms.txt
> Use this file to discover all available pages before exploring further.

# Auto-Reactions

> Configure automated responses to CI failures, review comments, and PR approvals

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:

<Steps>
  <Step title="Event detected">
    The orchestrator detects a CI failure, review comment, approval, etc.
  </Step>

  <Step title="Check reaction config">
    Looks up the reaction configuration for that event type
  </Step>

  <Step title="Execute action">
    If `auto: true`, performs the configured action automatically
  </Step>

  <Step title="Escalate if needed">
    If thresholds are exceeded, notifies human instead
  </Step>
</Steps>

**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:

```yaml theme={null}
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

<CodeGroup>
  ```yaml Aggressive (3 retries) theme={null}
  reactions:
    ci-failed:
      auto: true
      action: send-to-agent
      retries: 3
      escalateAfter: 3
  ```

  ```yaml Conservative (1 retry) theme={null}
  reactions:
    ci-failed:
      auto: true
      action: send-to-agent
      retries: 1
      escalateAfter: 1
  ```

  ```yaml Manual only theme={null}
  reactions:
    ci-failed:
      auto: false
      action: notify
      priority: urgent
  ```
</CodeGroup>

### 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:

```yaml theme={null}
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

<Info>
  **Time formats for `escalateAfter`:**

  * `10m` — 10 minutes
  * `1h` — 1 hour
  * `2` — 2 retry attempts (for CI failures)
  * `30m` — 30 minutes
</Info>

### 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:

```yaml theme={null}
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)

<Warning>
  **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.
</Warning>

### Conservative Auto-Merge

Notify instead of auto-merging:

```yaml theme={null}
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:

```yaml theme={null}
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

<Tabs>
  <Tab title="Quick timeout (5m)">
    ```yaml theme={null}
    reactions:
      agent-stuck:
        threshold: 5m
        action: notify
        priority: urgent
    ```

    Good for fast-moving workflows where agents should respond quickly.
  </Tab>

  <Tab title="Patient timeout (30m)">
    ```yaml theme={null}
    reactions:
      agent-stuck:
        threshold: 30m
        action: notify
        priority: warning
    ```

    Better for complex tasks where agents may need time to think.
  </Tab>
</Tabs>

## Per-Project Overrides

Override global reactions for specific projects:

```yaml theme={null}
# 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:

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
notificationRouting:
  urgent: [desktop, slack, webhook]
  action: [desktop, slack]
  warning: [slack]
  info: []
```

## Example Configurations

### Aggressive Automation (Auto-Merge Enabled)

```yaml theme={null}
# 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)

```yaml theme={null}
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)

```yaml theme={null}
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:

<Steps>
  <Step title="Spawn a test session">
    ```bash theme={null}
    ao spawn my-app test-reactions
    ```
  </Step>

  <Step title="Create a PR with failing tests">
    Let the agent create a PR, or manually push code with test failures
  </Step>

  <Step title="Watch reaction trigger">
    Check if the agent receives the CI failure message:

    ```bash theme={null}
    ao open my-app-1  # Attach to see the message
    ```
  </Step>

  <Step title="Verify notification routing">
    Check that notifications arrive in configured channels (Slack, desktop)
  </Step>
</Steps>

## Troubleshooting

### Reactions Not Triggering

**Check:**

1. **Reaction is enabled**
   ```yaml theme={null}
   reactions:
     ci-failed:
       auto: true  # Must be true
   ```

2. **SCM plugin is configured**
   ```yaml theme={null}
   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**
   ```bash theme={null}
   ao status  # Check activity state
   ```

2. **Agent can receive input**
   ```bash theme={null}
   ao send my-app-1 "test message"
   ```

3. **Review event log**
   ```bash theme={null}
   tail -f ~/.agent-orchestrator/events.jsonl
   ```

### Escalation Not Working

**Check time format:**

```yaml theme={null}
# Correct
escalateAfter: 30m

# Incorrect
escalateAfter: "30 minutes"  # Won't parse
```

**Check retry count:**

```yaml theme={null}
ci-failed:
  retries: 2
  escalateAfter: 2  # Escalates after 2 failures
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Custom Workflows" icon="workflow" href="/guides/custom-workflows">
    Create advanced automation with CI/CD integration
  </Card>

  <Card title="Multi-Project Setup" icon="folder-tree" href="/guides/multi-project">
    Manage reactions across multiple repositories
  </Card>
</CardGroup>