Quickstart

Add the Agent Observability Protocol (AOP) to any autonomous agent in under five minutes.

1. Start the collector

The collector receives events from your agent, stores them, and serves the dashboard. It runs entirely on your machine — no account, no cloud, no data leaving your environment.

npx @useaop/collector start

2. Install the SDK

npm install @useaop/sdk
# or
pnpm add @useaop/sdk

3. Add two lines to your agent

import { AOPClient } from '@useaop/sdk'

const aop = new AOPClient({ agentId: 'my-agent' })

4. Instrument your agent

async function runMyAgent(goal: string) {
  const aop = new AOPClient({ agentId: 'my-agent' })

  await aop.sessionStarted({ goal })
  await aop.thought('Planning my approach', { confidence: 'high' })

  const callId = await aop.toolStart('web_search', { query: goal })
  const results = await mySearchTool(goal)
  await aop.toolEnd('web_search', true, `Found ${results.length} results`, 420, {
    toolCallId: callId,
  })

  await aop.sessionEnded('completed', { outcome_summary: 'Task complete' })
}
AOP is fire-and-forget. The SDK never throws, never blocks your agent, and never causes your agent to fail if the collector is down. Observability is always zero-impact.

5. Run your agent

With the collector running in one terminal, run your agent in another. Switch to your browser at localhost:4317 — the session appears immediately and events stream in live.

Troubleshooting

Events not appearing?

Verify the collector is running and the SDK is pointed at the correct endpoint. You can check collector health directly:

curl http://localhost:4317/health

If the health endpoint does not respond, the collector is not running. Restart it with npx @useaop/collector start. If the health check succeeds but events still do not appear, confirm the endpoint option in your AOPClient matches the collector URL.

Port already in use?

Since v0.3.0, the collector automatically detects and kills existing instances listening on the same port before starting. If you are on an older version, stop the previous process manually or upgrade to the latest collector.

Next steps