@useaop/sdk

Official TypeScript SDK for the Agent Observability Protocol.

Install

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

Quick Start

import { AOPClient } from '@useaop/sdk'

const aop = new AOPClient({
  agentId: 'my-research-agent',
  // endpoint defaults to http://localhost:4317
})

// Start a session
await aop.sessionStarted({
  goal: 'Research the top 5 AI observability tools',
  llm: 'claude-sonnet-4-6',
})

// Emit a thought
await aop.thought('Starting with a broad search to identify main players', {
  confidence: 'high',
  nextIntent: 'web_search',
})

// Record a tool call
const callId = await aop.toolStart('web_search', { query: 'AI observability tools 2026' })
// ... run the tool ...
await aop.toolEnd('web_search', true, 'Found 10 results', 420, { toolCallId: callId, tokenSpendDelta: 340 })

// End the session
await aop.sessionEnded('completed', {
  outcome_summary: 'Produced research report with 5 tools compared',
  total_cost_usd: 0.34,
})

Configuration

const aop = new AOPClient({
  agentId: 'my-agent',           // required — identifies this agent type
  endpoint: 'http://localhost:4317', // optional — collector URL
  sessionId: 'sess_custom_id',   // optional — auto-generated if not provided
  parentSessionId: 'sess_parent', // optional — for child agents
  agentVersion: '1.0.0',         // optional — your agent's version
  timeout: 500,                  // optional — ms before giving up on emit
})

Multi-Agent Usage

const parent = new AOPClient({ agentId: 'orchestrator' })
await parent.sessionStarted({ goal: 'Complex multi-step research task' })

// Spawn a child — returns a pre-configured child AOPClient
const child = await parent.agentSpawn('researcher-agent', 'Research AI tools', {
  reason: 'Specialised research task',
})

await child.sessionStarted({ goal: 'Research AI tools' })
// child automatically has parent_session_id set

API Reference

Lifecycle

• sessionStarted(payload) — start a session
• heartbeat(status?, tokenSpend?, currentGoal?) — periodic status update
• sessionEnded(status, options?) — end a session

Cognition

• thought(reasoning, options?) — emit reasoning
• goal(goal, previousGoal?, options?) — set or change goal
• decision(options, chosen, reasoning) — record a decision
• uncertainty(description, severity, actionTaken) — flag uncertainty

Operations

• toolStart(tool, input, options?) — before a tool call
• toolEnd(tool, success, summary, latencyMs, options?) — after a tool call
• agentSpawn(childAgentId, goal, options?) — spawn a child agent
• memory(action, key, summary, sizeBytes?) — memory access
• externalCall(service, method, endpoint, success, latencyMs, statusCode?) — API call

Low-level

• emit(type, payload) — emit any event type directly

License

MIT