Getting Started

The Autonomous Incident Agent (AIA) is an intelligent system that automatically detects application failures via OpenTelemetry, analyzes them using AI, and creates GitHub Pull Requests with fix suggestions and manual remediation steps.

#One-Line Start

If you have already configured your environment, you can start the full AIA stack with a single command:

Terminal
bun run dev

This will launch all services, including the Agent, Router, Autopsy, State, Git, Dashboard, and sample application.

#Core Concepts

Understanding AIA requires identifying its main stages of operation.

1. Detection (Agent + Router)

The lifecycle begins when your application emits error traces via OpenTelemetry to the Agent service (port 4318). The Router service processes these traces, applies deduplication (based on trace ID), and identifies distinct incidents.

2. Analysis (Autopsy)

Once an incident is detected, the Autopsy service uses AI (You.com API) to:

  • Analyze the stack trace and error context
  • Identify the root cause
  • Generate a code patch (git diff format)
  • Create detailed fix instructions
  • Provide manual remediation steps

3. Storage & State (State Service)

The State service (PostgreSQL/Neon) stores:

  • Incident metadata
  • Autopsy results
  • PR creation status
  • Historical incident data

4. Git Integration (Git Service)

The Git service:

  1. Clones your GitHub repository
  2. Creates a new branch (aia/incident-{id})
  3. Attempts to apply the AI-generated patch
  4. Commits changes (or saves failed patch as patch_failed_*.diff)
  5. Pushes to GitHub
  6. Creates a Pull Request with:
    • AI-generated fix prompt
    • Manual step-by-step instructions
    • Patch file (if application failed)
    • Full error context

5. Dashboard

The Dashboard (port 3000) provides:

  • Real-time incident monitoring
  • Autopsy results viewer
  • AI fix prompt (copy-to-clipboard)
  • Manual remediation steps
  • Link to GitHub PR

#Quick Setup

Clone & Install

Terminal
git clone https://github.com/your-org/autonomous-incident-agent cd autonomous-incident-agent bun install

Configure Environment

Create a .env file in the project root:

Terminal
YOU_API_KEY=ydc_your_key_here GITHUB_TOKEN=ghp_your_token_here DATABASE_URL=postgresql://user:pass@host/db

Configure GitHub Integration

Create aia.config.local.yaml (gitignored):

Terminal
github: owner: "your-github-username" repo: "your-repo-name" base_branch: "main"

Start Services

Terminal
bun run dev

This starts all services:

  • Agent (OTEL receiver): http://localhost:4318
  • Dashboard: http://localhost:3000
  • Router: http://localhost:3001
  • Autopsy: http://localhost:3002
  • State: http://localhost:3003
  • Git: http://localhost:3004
  • Web: http://localhost:3006
  • Docs: http://localhost:3007
  • Sample App: http://localhost:3008

#Test the System

Trigger a test incident using the sample app:

Terminal
curl -X POST http://localhost:3008/trigger \ -H "Content-Type: application/json" \ -d '{"action":"cause_error"}'

Then:

  1. Check the dashboard at http://localhost:3000
  2. View the autopsy results
  3. Check your GitHub repository for a new PR

#Next Steps

Installation