Event Types

All 11 event types in the Agent Observability Protocol (AOP) v1.0 taxonomy, grouped by tier.

Every AOP event shares a common envelope (spec, session_id, agent_id, sequence, timestamp, type) and carries a tier-specific payload.

Event lifecycle

Instrumentation patterns

Follow these patterns when instrumenting your agent to produce clear, useful traces:

• Emit cognition.thought before each action — record the reasoning that led to the action so the trace explains why, not just what.
• Bracket tool calls with operation.tool_start / tool_end — emit tool_start immediately before calling a tool and tool_end immediately after it returns.
• Send session.heartbeat regularly — for long-running agents, emit a heartbeat every 30 seconds or after each significant step so the dashboard knows the agent is still alive.
• Use cognition.decision for explicit choices — when the agent considers multiple options and picks one, record the decision and the alternatives that were rejected.
• Use cognition.uncertainty for low confidence — when the agent has low confidence or encounters ambiguity, flag it so reviewers can spot risky moments.
• Use cognition.goal for objective changes — when the agent sets, updates, or abandons its active objective, emit a goal event to keep the trace navigable.

Tier 1 — Lifecycle

Report the agent's existence and operational status. Every conforming agent must emit at least session.started and session.ended.

session.started

Emitted once at the beginning of a session.

payload: {
  goal?: string           // The agent's primary objective
  agent_version?: string  // Semantic version of the agent
  metadata?: object       // Arbitrary key-value context
}

session.heartbeat

Periodic signal indicating the agent is still alive. Useful for detecting hangs or crashes.

payload: {
  status: 'running' | 'idle' | 'waiting'
  metadata?: object
}

session.ended

Emitted once when the session terminates, whether by success, failure, or cancellation.

payload: {
  outcome: 'completed' | 'failed' | 'cancelled' | 'timeout'
  outcome_summary?: string
  error_message?: string
  metadata?: object
}

Tier 2 — Cognition

Capture the agent's internal reasoning. These events explain why the agent acts, not just what it does.

cognition.thought

A free-form reasoning step — the agent thinking out loud.

payload: {
  content: string                          // The thought text
  confidence?: 'high' | 'medium' | 'low'  // Self-assessed confidence
  metadata?: object
}

cognition.goal

Records when the agent sets, updates, or completes a sub-goal.

payload: {
  goal: string
  status: 'set' | 'in_progress' | 'completed' | 'abandoned'
  parent_goal?: string
  metadata?: object
}

cognition.decision

Captures a deliberate choice between alternatives.

payload: {
  decision: string         // What was decided
  alternatives?: string[]  // Options that were considered
  reasoning?: string       // Why this alternative was chosen
  metadata?: object
}

cognition.uncertainty

Signals that the agent is unsure about something — useful for flagging moments that may need human review.

payload: {
  content: string                          // What the agent is uncertain about
  confidence?: 'high' | 'medium' | 'low'  // How uncertain
  metadata?: object
}

Tier 3 — Operations

Record the agent's actions in the external world — tool invocations, API calls, memory access, and spawning child agents.

operation.tool_start

Marks the beginning of a tool invocation. Pair with tool_end using tool_call_id.

payload: {
  tool_name: string       // Name of the tool being called
  tool_call_id: string    // Unique ID to correlate with tool_end
  input?: object          // Arguments passed to the tool
  metadata?: object
}

operation.tool_end

Marks the completion of a tool invocation.

payload: {
  tool_name: string
  tool_call_id: string
  success: boolean
  result_summary?: string
  duration_ms?: number
  metadata?: object
}

operation.agent_spawn

Records the creation of a child agent session, linking parent and child in the session tree.

payload: {
  child_session_id: string
  child_agent_id: string
  goal?: string            // The child agent's objective
  metadata?: object
}

operation.memory

Tracks reads and writes to the agent's memory or knowledge store.

payload: {
  operation: 'read' | 'write' | 'delete'
  key?: string
  summary?: string
  metadata?: object
}

operation.external_call

Records an outbound HTTP or API call that is not a tool invocation.

payload: {
  method: string       // HTTP method
  url: string          // Target URL
  status_code?: number
  duration_ms?: number
  metadata?: object
}

Cost tracking

AOP supports cost tracking through developer-supplied values in event payloads:

• token_spend_delta — include this in operation.tool_end metadata to record the number of tokens consumed by that specific tool call.
• total_cost_usd — include this in session.ended metadata to record the total estimated cost of the session.

These values are not auto-calculated by the collector. Your agent code is responsible for computing and supplying them. The dashboard displays token_spend_delta in the session metrics bar and total_cost_usd on session cards, giving you a clear picture of per-session and per-tool spend.

Related

• Protocol specification — envelope format and design principles
• Transport — how events are delivered to the collector
• SDK reference — typed methods for emitting each event