追踪

Agent 追踪帮助你了解 Agent 在每一轮中做了什么，包括模型调用、工具运行与审批请求。使用 traces 调查意外行为、查找慢操作，并审阅 token 用量。

Agent 活动会与 fetch 调用、KV 读取和 D1 查询等运行时事件一同出现在 Workers traces 中。

在 Wrangler 配置中启用追踪：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "observability": {
    "traces": {
      "enabled": true
    }
  }
}

[observability.traces]
enabled = true

打开 Cloudflare 仪表板中的 Agents 选项卡 ↗，查看已追踪的 Agent 与子 Agent。概览显示每个 Agent 的模型、会话数、运行次数与总 token 用量。

会话是由一轮或多轮组成的对话。一轮是对 Agent 的一次请求及其响应。

选择一个 Agent 以查看其 traces。每条 trace 包含持续时间、token 分解与状态。

有两种方式跟踪 Agent 做了什么：Session replay（会话回放） 与 Trace（追踪）。

会话重放会展示各轮次中记录的对话，包括消息、推理、工具调用和子代理活动。显示内容取决于你的负载记录设置。

Trace 是一轮中所执行操作的瀑布图。它显示每个操作何时开始、耗时多久，以及由哪个操作调用。

每一轮都会产生由 span 组成的 trace，每个计时操作对应一个 span：

invoke_agent {agent class}
├── chat {model}
└── execute_tool {tool}
    └── tool_approval {tool}

invoke_agent span 覆盖整一轮。模型调用、工具运行与审批作为嵌套 span 出现。子 Agent 工作出现在调用它的操作之下。

Agent span 使用三个字段标识仪表板中显示的工作：

• Agent name 标识逻辑 Agent 实现。使用共享名称，例如 booking-agent。
• Agent ID 标识稳定的 Agent 实例或资源，例如 booking-agent-production。
• Conversation ID 标识当前对话或会话。

不要从请求、对话或用户标识符派生 Agent name。这会在仪表板中产生过多不同的 Agent 名称。

消息和工具负载可能包含个人身份信息。只记录适合存储的负载。每种集成控制负载记录的方式各不相同，请在相应的框架设置部分进行配置。

Think 与 wrapAISDK() 使用 storeMessages 在 chat span 上记录输入与输出消息。它们使用 storeTools 在 execute_tool span 上记录参数与结果。

追踪与载荷控制取决于集成。Think 与 Flue 会自动为轮次做插桩。直接的 AI SDK 调用与自定义执行框架需要额外设置。

Lifecycle本身不会创建代理 span。在直接安装 Lifecycle 的 Durable Object 上，请使用 wrapAISDK() 或 Workers 自定义 span API跟踪模型调用。

Think 会自动检测代理并发出标准 span 结构。无需额外配置跟踪。

Think 默认不存储消息或工具载荷。要记录它们，请在 Agent 类上覆盖这些属性：

import { Think } from "@cloudflare/think";

export class MyAgent extends Think {
	storeMessages = true;
	storeTools = true;
}

import { Think } from "@cloudflare/think";

export class MyAgent extends Think<Env> {
	override storeMessages = true;
	override storeTools = true;
}

Flue v2+ ↗也会自动检测代理并发出标准 span 结构。无需额外配置跟踪。

Flue 默认存储消息、系统指令、工具定义、参数与结果。要停止记录它们，将 content 设为 false：

import { instrument } from "@flue/runtime";
import { createCloudflareTracing } from "@flue/runtime/cloudflare";

instrument(createCloudflareTracing({ content: false }));

import { instrument } from "@flue/runtime";
import { createCloudflareTracing } from "@flue/runtime/cloudflare";

instrument(createCloudflareTracing({ content: false }));

对于直接的 AI SDK ↗ 调用，包装命名空间一次：

import * as ai from "ai";
import { wrapAISDK } from "agents/observability/ai";

const tracedAI = wrapAISDK(ai);

import * as ai from "ai";
import { wrapAISDK } from "agents/observability/ai";

const tracedAI = wrapAISDK(ai);

wrapAISDK() 支持 AI SDK v6 与 v7。它为 generateText、streamText、generateObject 与 streamObject 做插桩，在模型与工具工作开始之前创建 invoke_agent 父 span。

与 Think 不同，直接调用 AI SDK 时没有可用于推断控制面板身份的 Agent 实例。请在每次调用中提供代理身份字段。

仅包含可安全存储的上下文。不要包含凭据、token、用户输入或其他密钥。

使用原生 AI SDK v7 telemetry 字段提供身份。你可以包含额外的标量上下文（例如租户或路由），使 traces 更易于查询：

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	runtimeContext: {
		agentId: "booking-agent-production",
		conversationId: "conversation-123",
		tenantId: "tenant-42",
	},
	telemetry: {
		functionId: "booking-agent",
		includeRuntimeContext: {
			agentId: true,
			conversationId: true,
			tenantId: true,
		},
	},
});

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	runtimeContext: {
		agentId: "booking-agent-production",
		conversationId: "conversation-123",
		tenantId: "tenant-42",
	},
	telemetry: {
		functionId: "booking-agent",
		includeRuntimeContext: {
			agentId: true,
			conversationId: true,
			tenantId: true,
		},
	},
});

这会将 functionId、agentId 与 conversationId 映射到 gen_ai.agent.name、gen_ai.agent.id 与 gen_ai.conversation.id。其他包含的标量值使用 cloudflare.agents.runtime_context.* 命名空间。

AI SDK v6 使用 experimental_telemetry.metadata 提供相同的身份与额外 span 数据：

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	experimental_telemetry: {
		functionId: "booking-agent",
		metadata: {
			agentId: "booking-agent-production",
			conversationId: "conversation-123",
			tenantId: "tenant-42",
		},
	},
});

await tracedAI.generateText({
	model,
	prompt: "Find an available appointment",
	experimental_telemetry: {
		functionId: "booking-agent",
		metadata: {
			agentId: "booking-agent-production",
			conversationId: "conversation-123",
			tenantId: "tenant-42",
		},
	},
});

额外的标量 metadata 使用 cloudflare.agents.metadata.* 命名空间。

wrapAISDK() 默认不存储消息或工具载荷。要在 AI SDK v6 或 v7 中记录它们，包装命名空间时传入存储选项：

import * as ai from "ai";
import { wrapAISDK } from "agents/observability/ai";

const tracedAI = wrapAISDK(ai, {
	storeMessages: true,
	storeTools: true,
});

import * as ai from "ai";
import { wrapAISDK } from "agents/observability/ai";

const tracedAI = wrapAISDK(ai, {
	storeMessages: true,
	storeTools: true,
});

若你的 Agent 未使用当前支持的框架，请用 Workers 自定义 span API 做插桩。为每一轮创建 invoke_agent span，模型调用使用 chat span，工具运行使用 execute_tool span，审批使用 tool_approval span。

span 名称、属性与实现示例请参阅 OpenTelemetry GenAI 参考实现 ↗。将这些示例适配到 Workers 自定义 span API。

将这些属性同时添加到 invoke_agent 与 chat span，以便 Agents 仪表板能将遥测与 Agent 及对话关联：

对于自定义 span，请手动添加载荷属性。在模型 span 上使用 gen_ai.input.messages、gen_ai.output.messages 与 gen_ai.system_instructions。在工具 span 上使用 gen_ai.tool.call.arguments 与 gen_ai.tool.call.result。自定义 span API 接受标量属性值，因此用 JSON.stringify() 序列化结构化载荷。只要该调用被采样，这些值就会被记录。仅添加可安全存储的载荷。

span 属性遵循 OpenTelemetry Generative AI 语义约定 ↗，因此任何读取 OpenTelemetry 数据的工具都可以消费它们。要将 traces 发送到外部目的地，请在 Workers Observability 中配置 OpenTelemetry 导出。

Agent traces 使用 Workers tracing，并遵循 Workers Observability 定价。

Agents 视图显示你的 Agent 操作。完整 Worker trace 可能包含来自 SDK 内部以及其他 Worker 级操作的额外 span。要检查完整 trace，选择 View in Observability（在可观测性中查看）。

自 2026 年 12 月 1 日起，Agent traces 会计入账户级摄入与存储用量，遵循 Cloudflare Observability 定价。traces 保留七天。

• 将 Agent traces 用于调试与可观测性。traces 不是完整或无损的对话记录。
• 载荷数据受 span 大小限制约束。长消息、推理、工具参数与结果可能被截断。这些限制可能会变化。
• 会话回放不显示图像。