可观测性

Agent 会为每一次重要操作发出结构化事件 —— RPC 调用、状态变更、调度执行、工作流状态切换、MCP 连接等等。这些事件被发布到 diagnostics channel,并默认静默(没有人监听时零开销)。

事件结构

每个事件都包含以下字段:

TypeScript

{

  type: "rpc",                        // what happened

  agent: "MyAgent",                   // which agent class emitted it

  name: "user-123",                   // which agent instance (Durable Object name)

  payload: { method: "getWeather" },  // details

  timestamp: 1758005142787            // when (ms since epoch)

}

agent 和 name 用于标识事件来源 —— agent 是类名,name 是 Durable Object 实例名。

通道

事件根据类型被路由到八个具名通道:

订阅事件

类型化的 subscribe 帮助函数

agents/observability 提供的 subscribe() 函数可以以类型安全的方式访问指定通道上的事件:

• JavaScript
• TypeScript

JavaScript

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();

Explain Code

TypeScript

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();

Explain Code

回调函数有完整的类型提示 —— event 会被收窄为该通道里实际会出现的事件类型。

直接使用 diagnostics_channel

你也可以直接使用 Node.js API 进行订阅:

• JavaScript
• TypeScript

JavaScript

import { subscribe } from "node:diagnostics_channel";


subscribe("agents:schedule", (event) => {

  console.log(event);

});

TypeScript

import { subscribe } from "node:diagnostics_channel";


subscribe("agents:schedule", (event) => {

  console.log(event);

});

Tail Workers(生产环境)

在生产环境中,所有 diagnostics channel 上的消息都会自动转发到 Tail Workers。Agent 内部不需要写任何订阅代码 —— 只要附加一个 Tail Worker,然后通过 event.diagnosticsChannelEvents 访问事件:

• JavaScript
• TypeScript

JavaScript

export default {

  async tail(events) {

    for (const event of events) {

      for (const msg of event.diagnosticsChannelEvents) {

        // msg.channel is "agents:rpc", "agents:workflow", etc.

        // msg.message is the typed event payload

        console.log(msg.timestamp, msg.channel, msg.message);

      }

    }

  },

};

Explain Code

TypeScript

export default {

  async tail(events) {

    for (const event of events) {

      for (const msg of event.diagnosticsChannelEvents) {

        // msg.channel is "agents:rpc", "agents:workflow", etc.

        // msg.message is the typed event payload

        console.log(msg.timestamp, msg.channel, msg.message);

      }

    }

  },

};

Explain Code

这让你能在生产环境获得结构化、可过滤的可观测性,同时不会给 Agent 的热路径带来任何额外开销。

自定义可观测性

你可以通过提供自己的 Observability 接口来覆盖默认实现:

• JavaScript
• TypeScript

JavaScript

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;

}

Explain Code

TypeScript

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;

}

Explain Code

把 observability 设置为 undefined 可以关闭所有事件发送:

• JavaScript
• TypeScript

JavaScript

import { Agent } from "agents";


class MyAgent extends Agent {

  observability = undefined;

}

TypeScript

import { Agent } from "agents";


class MyAgent extends Agent {

  override observability = undefined;

}

事件参考

RPC 事件

State 事件

Message 与 tool 事件(AIChatAgent)

这些事件由 @cloudflare/ai-chat 的 AIChatAgent 发出,用于跟踪聊天消息的生命周期,包括客户端工具的交互。

Schedule 与 queue 事件

Lifecycle 事件

Workflow 事件

MCP 事件

Email 事件

下一步

Configuration wrangler.jsonc 设置与部署。

Tail Workers 把 diagnostics channel 事件转发到 Tail Worker,实现生产环境监控。

Agents API Agents SDK 的完整 API 参考。