追踪
Agents SDK 内置了追踪功能,可全面记录智能体运行期间的事件:LLM 生成、工具调用、交接、护栏,甚至自定义事件。借助追踪控制面板,您可以在开发和生产环境中调试、可视化和监控工作流。
导出循环生命周期
Section titled “导出循环生命周期”在受支持的服务器运行时中,追踪会定期导出。在某些运行时(包括 Cloudflare Workers)中,虽然追踪本身仍然启用,但自动导出循环不可用。在这些环境中,您应在请求生命周期内调用 getGlobalTraceProvider().forceFlush(),以便在运行时被销毁之前导出队列中的追踪。
此建议不适用于浏览器,因为浏览器中的追踪默认禁用。
例如,在 Cloudflare Worker 中,您应将代码放入 try/catch/finally 块中,并将 forceFlush() 与 waitUntil 配合使用,确保在 worker 退出之前导出追踪。
import { getGlobalTraceProvider } from '@openai/agents';
export default { async fetch(request, env, ctx): Promise<Response> { try { // your agent code here return new Response(`success`); } catch (error) { console.error(error); return new Response('Internal Server Error', { status: 500 }); } finally { // make sure to flush any remaining traces before exiting ctx.waitUntil(getGlobalTraceProvider().forceFlush()); } },};- 追踪表示一个”工作流”的单次端到端操作,由多个跨度组成。追踪具有以下属性:
workflow_name:逻辑工作流或应用的名称。例如”代码生成”或”客户服务”。trace_id:追踪的唯一 ID。如果未提供,则自动生成。格式必须为trace_<32_alphanumeric>。group_id:可选的分组 ID,用于关联同一对话中的多个追踪。例如,您可以使用聊天线程 ID。disabled:如果为 True,则不会记录该追踪。metadata:追踪的可选元数据。
- 跨度表示具有开始和结束时间的操作。跨度包含:
started_at和ended_at时间戳。trace_id,表示其所属的追踪parent_id,指向此跨度的父跨度(如果有)span_data,包含跨度的相关信息。例如,AgentSpanData包含智能体的相关信息,GenerationSpanData包含 LLM 生成的相关信息,等等。
默认情况下,SDK 会追踪以下内容:
- 整个
run()或Runner.run()包含在一个Trace中。 - 每次顶层 runner 调用包含在一个
TaskSpan中。 - 每次智能体运行包含在一个
AgentSpan中。 - 智能体循环的每次迭代包含在一个
TurnSpan中。 - LLM 生成包含在一个
GenerationSpan中。 - 每次函数工具调用包含在一个
FunctionSpan中。 - 护栏包含在一个
GuardrailSpan中。 - 交接包含在一个
HandoffSpan中。
默认层级结构为 TaskSpan → AgentSpan → TurnSpan,模型和工具操作嵌套在轮次之下。任务跨度汇总该次调用的请求和 token 用量。每个轮次跨度记录轮次编号、智能体名称,以及输入、输出、缓存输入和缓存写入的 token 数量。
任务跨度和轮次跨度默认启用。在 Runner 或单次运行中设置 tracing: { includeTaskAndTurnSpans: false },即可省略这一额外的层级结构。单次运行的追踪选项会覆盖 runner 级别的设置。
默认情况下,追踪名称为”Agent workflow”。您可以在使用 withTrace 时设置此名称,也可以通过 RunConfig.workflowName 配置名称和其他属性。
此外,您可以设置自定义追踪处理器,将追踪推送到其他目标位置(作为替代目标或附加目标)。
语音智能体追踪
Section titled “语音智能体追踪”如果您将 RealtimeAgent 和 RealtimeSession 与默认的 OpenAI Realtime API 配合使用,追踪会在 Realtime API 端自动进行,除非您在 RealtimeSession 上使用 tracingDisabled: true 或通过 OPENAI_AGENTS_DISABLE_TRACING 环境变量将其禁用。
更多详情,请参阅语音智能体概述。
有时,您可能希望将多次 run() 调用纳入同一个追踪。您可以将整个代码放入 withTrace() 中来实现。
import { Agent, run, withTrace } from '@openai/agents';
const agent = new Agent({ name: 'Joke generator', instructions: 'Tell funny jokes.',});
await withTrace('Joke workflow', async () => { const result = await run(agent, 'Tell me a joke'); const secondResult = await run( agent, `Rate this joke: ${result.finalOutput}`, ); console.log(`Joke: ${result.finalOutput}`); console.log(`Rating: ${secondResult.finalOutput}`);});- 由于两次
run调用都包含在一个withTrace()中,因此各次运行会成为整体追踪的一部分,而不是创建两个追踪。
您可以使用 withTrace() 函数创建追踪。也可以使用 getGlobalTraceProvider().createTrace() 手动创建新追踪,并将其传入 withTrace()。
当前追踪通过 Node.js AsyncLocalStorage 或相应环境的 polyfill 进行跟踪。这意味着它能够自动支持并发。
您可以使用各种 create*Span() 方法创建跨度,例如 createTaskSpan()、createTurnSpan()、createGenerationSpan() 和 createFunctionSpan()。相应的辅助函数(例如 withTaskSpan() 和 withTurnSpan())会为回调创建跨度并管理其生命周期。通常,您不需要手动创建跨度。您可以使用 createCustomSpan() 函数跟踪自定义跨度信息。
跨度会自动归属于当前追踪,并嵌套在最近的当前跨度之下。当前跨度通过 Node.js AsyncLocalStorage 或相应环境的 polyfill 进行跟踪。
某些跨度可能会捕获潜在的敏感数据。
createGenerationSpan() 会存储 LLM 生成的输入和输出,createFunctionSpan() 会存储函数调用的输入和输出。这些内容可能包含敏感数据,因此您可以通过 RunConfig.traceIncludeSensitiveData 禁用此类数据的捕获。
OpenAI 追踪导出器
Section titled “OpenAI 追踪导出器”在受支持的服务器运行时中,默认追踪配置已会将数据导出到 OpenAI。如果追踪导出需要使用与 OPENAI_API_KEY 不同的凭据,请使用 setTracingExportApiKey()。
如果您需要自定义数据接收行为,请自行实例化 OpenAITracingExporter,并通过 setTraceProcessors(...) 或 addTraceProcessor(...) 安装。该导出器支持 apiKey、endpoint、organization、project、maxRetries、baseDelay 和 maxDelay。
如果您替换了默认处理器,之后又想恢复使用带批处理器的默认 OpenAI 导出器,请调用 setDefaultOpenAITracingExporter()。
自定义追踪处理器
Section titled “自定义追踪处理器”追踪的高层架构如下:
- 初始化时,我们会创建一个全局的
TraceProvider,它负责创建追踪,可通过getGlobalTraceProvider()访问。 - 我们为
TraceProvider配置一个BatchTraceProcessor,它会将追踪和跨度批量发送到OpenAITracingExporter,再由导出器将跨度和追踪批量导出到 OpenAI 后端。
要自定义此默认配置,将追踪发送到其他后端或附加后端,或修改导出器的行为,您有两种选择:
addTraceProcessor()允许您添加一个额外的追踪处理器,在追踪和跨度就绪时接收它们。这样,除了将追踪发送到 OpenAI 后端,您还可以进行自己的处理。setTraceProcessors()允许您用自己的追踪处理器替换默认处理器。这意味着,除非您包含一个负责发送数据到 OpenAI 后端的TracingProcessor,否则追踪不会发送到 OpenAI 后端。