Diagnostics channels

The Lifecycle and its capabilities publish structured events to diagnostics channels for significant operations, such as RPC calls, schedule execution, job queue warnings, and MCP connections. The Agent class publishes more events for state changes, chat, workflows, and email. Publishing has no overhead when nobody is listening.

Events work the same on any Durable Object that installs the Lifecycle and on the Agent class.

Every event has these fields:

{
  type: "rpc",                        // what happened
  source: "websockets",               // which capability emitted it
  agent: "MyAgent",                   // which Durable Object class emitted it
  name: "user-123",                   // which instance (Durable Object name)
  payload: { method: "getWeather" },  // details
  timestamp: 1758005142787            // when (ms since epoch)
}

• agent is the Durable Object class name and name is the instance name.
• source is the ID of the capability that emitted the event, or lifecycle for events from the Lifecycle job queue. It is set on events that a Lifecycle publishes directly. Events emitted through the Agent class's observability property do not have a source.

Each event goes to one channel, chosen by the prefix of its type:

agents:lifecycle is the fallback channel. An event whose type matches none of the prefixes above, such as an event from your own capability, lands there.

The subscribe() function from agents/observability provides type-safe access to events on a specific channel:

import { subscribe } from "agents/observability";

const unsub = subscribe("rpc", (event) => {
	if (event.type === "rpc") {
		console.log(`RPC call: ${event.payload.method}`);
	}
	if (event.type === "rpc:error") {
		console.error(
			`RPC failed: ${event.payload.method} — ${event.payload.error}`,
		);
	}
});

// Clean up when done
unsub();

import { subscribe } from "agents/observability";

const unsub = subscribe("rpc", (event) => {
	if (event.type === "rpc") {
		console.log(`RPC call: ${event.payload.method}`);
	}
	if (event.type === "rpc:error") {
		console.error(
			`RPC failed: ${event.payload.method} — ${event.payload.error}`,
		);
	}
});

// Clean up when done
unsub();

The callback is typed: event is narrowed to the event types in the event reference for that channel. Events from your own capabilities are not part of those types. Read them with the raw API.

The typed helper uses camelCase keys, so agent-tool events are subscribe("agentTool", ...). Raw diagnostics channel subscribers use the emitted channel name, agents:agent_tool.

You can also subscribe directly using the Node.js API:

import { subscribe } from "node:diagnostics_channel";

subscribe("agents:schedule", (event) => {
	console.log(event);
});

import { subscribe } from "node:diagnostics_channel";

subscribe("agents:schedule", (event) => {
	console.log(event);
});

A capability that extends LifecycleCapability publishes events with this.lifecycle.events.emit(type, payload). The Lifecycle adds the source, agent, name, and timestamp fields and routes the event by its type prefix. A type with an unknown prefix lands on agents:lifecycle:

import { DurableObject } from "cloudflare:workers";
import { Lifecycle, LifecycleCapability } from "agents/lifecycle";

class Orders extends LifecycleCapability {
	constructor() {
		super("orders");
	}

	place(orderId) {
		// Unknown prefix, so this lands on agents:lifecycle
		this.lifecycle.events.emit("order:placed", { orderId });
	}
}

export class Shop extends DurableObject {
	orders = new Orders();
	lifecycle = Lifecycle.install(this).use(this.orders);
}

import { DurableObject } from "cloudflare:workers";
import { Lifecycle, LifecycleCapability } from "agents/lifecycle";

class Orders extends LifecycleCapability {
	constructor() {
		super("orders");
	}

	place(orderId: string) {
		// Unknown prefix, so this lands on agents:lifecycle
		this.lifecycle.events.emit("order:placed", { orderId });
	}
}

export class Shop extends DurableObject<Env> {
	readonly orders = new Orders();
	readonly lifecycle = Lifecycle.install(this).use(this.orders);
}

Read these events by type on the raw channel:

import { subscribe } from "node:diagnostics_channel";

subscribe("agents:lifecycle", (message) => {
	const event = message;
	if (event.type === "order:placed") {
		console.log(event.source, event.payload);
	}
});

import { subscribe } from "node:diagnostics_channel";

subscribe("agents:lifecycle", (message) => {
	const event = message as { type: string; source?: string; payload: unknown };
	if (event.type === "order:placed") {
		console.log(event.source, event.payload);
	}
});

Events are best effort. Events emitted while the Lifecycle is starting are held and published once startup finishes, and dropped if startup fails. Refer to Build a capability for the rest of the capability API.

In production, all diagnostics channel messages are automatically forwarded to Tail Workers. No subscription code is needed in the agent itself. Attach a Tail Worker and read events from event.diagnosticsChannelEvents:

export default {
	async tail(events) {
		for (const event of events) {
			for (const msg of event.diagnosticsChannelEvents) {
				// msg.channel is "agents:rpc", "agents:lifecycle", etc.
				// msg.message is the event
				console.log(msg.timestamp, msg.channel, msg.message);
			}
		}
	},
};

export default {
	async tail(events) {
		for (const event of events) {
			for (const msg of event.diagnosticsChannelEvents) {
				// msg.channel is "agents:rpc", "agents:lifecycle", etc.
				// msg.message is the event
				console.log(msg.timestamp, msg.channel, msg.message);
			}
		}
	},
};

This gives you structured, filterable observability in production with no overhead in the agent hot path.

The Agent class sends its events through an observability property. The default implementation, genericObservability from agents/observability, publishes each event to the channels above. A Durable Object that installs the Lifecycle directly has no observability property. Its events always go to the channels, and you filter them in the subscriber.

To replace the default on an Agent, provide your own Observability implementation:

import { Agent } from "agents";

const myObservability = {
	emit(event) {
		// Send to your logging service, filter events, etc.
		if (event.type === "rpc:error") {
			console.error(event.payload.method, event.payload.error);
		}
	},
};

class MyAgent extends Agent {
	observability = myObservability;
}

import { Agent } from "agents";
import type { Observability } from "agents/observability";

const myObservability: Observability = {
	emit(event) {
		// Send to your logging service, filter events, etc.
		if (event.type === "rpc:error") {
			console.error(event.payload.method, event.payload.error);
		}
	},
};

class MyAgent extends Agent {
	override observability = myObservability;
}

Set observability to undefined to disable all event emission:

import { Agent } from "agents";

class MyAgent extends Agent {
	observability = undefined;
}

import { Agent } from "agents";

class MyAgent extends Agent {
	override observability = undefined;
}

These events track chat message lifecycle, client-side tool interactions, and Think durable submissions.

recoveryKind is "retry" when recovery replays an unanswered user turn and "continue" when it continues a partial assistant turn.

These events come from the Agent class:

These events come from the Lifecycle job queue, on any Durable Object that installs the Lifecycle. Their source is lifecycle: