Observability Rewrite with Diagnostics Channels

The SDK replaces the previous custom Observability.emit() interface with structured events published to diagnostics channels — silent by default with zero overhead when not actively consumed. Events are routed to seven named channels (agents:state, agents:rpc, agents:message, agents:schedule, agents:lifecycle, agents:workflow, agents:mcp), each carrying typed events with metadata including type, payload, and timestamp.

Developers can subscribe to specific channels using the type-safe subscribe() helper from agents/observability:

import { subscribe } from "agents/observability";

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

unsub(); // cleanup

In production, all diagnostics channel messages are automatically forwarded to Tail Workers without requiring subscription code, enabling centralized observability at scale.

Preventing Durable Object Eviction

Long-running operations (streaming LLM responses, external API waits, multi-step computations) can cause Durable Objects to be evicted after 70-140 seconds of inactivity. The new keepAlive() method creates a 30-second heartbeat schedule that resets the inactivity timer:

const dispose = await this.keepAlive();
try {
  const result = await longRunningComputation();
  await sendResults(result);
} finally {
  dispose();
}

Alternatively, keepAliveWhile() wraps an async function with automatic heartbeat lifecycle:

const result = await this.keepAliveWhile(async () => {
  return await longRunningComputation();
});

Key points: multiple concurrent keepAlive() calls are independent; AIChatAgent automatically uses keepAlive() during streaming responses; heartbeats appear in getSchedules() if needed for inspection.

Guaranteed MCP Tool Availability

AIChatAgent now waits for MCP server connections to settle before invoking onChatMessage, ensuring this.mcp.getAITools() returns the full tool set after hibernation when connections are restored in the background. Default timeout is 10 seconds, but can be customized or disabled:

export class ChatAgent extends AIChatAgent {
  waitForMcpConnections = { timeout: 10_000 }; // default
  // waitForMcpConnections = true;  // wait forever
  // waitForMcpConnections = false; // disable
}

This eliminates race conditions where tools might be unavailable during the initial message handling.