dotfiles/dot_claude/skills/agents-sdk/references/observability.md

Observability

Fetch https://developers.cloudflare.com/agents/api-reference/observability/ for complete documentation.

Agents emit structured events via Node.js diagnostics_channel. Subscribe in development or forward via Tail Workers in production.

Subscribe to Events

import { subscribe } from "agents/observability";

subscribe("agents:rpc", (event) => {
  console.log(`RPC call: ${event.payload.method}`);
});

subscribe("agents:state", (event) => {
  console.log(`State change on ${event.agent}`);
});

Available Channels

Channel	Events
agents:state	State changes
agents:rpc	@callable invocations
agents:message	WebSocket messages
agents:schedule	Schedule triggers
agents:lifecycle	Agent start, connect, disconnect
agents:workflow	Workflow progress, completion, errors
agents:mcp	MCP server connections, tool calls
agents:email	Email received

Per-Agent Override

export class MyAgent extends Agent<Env, State> {
  observability = undefined; // disable for this agent
}

Production: Tail Workers

In production, events appear as diagnosticsChannelEvents on the Tail Worker event object. Attach a Tail Worker to your agent's Worker to forward events to your observability platform.