追踪
Agents SDK 内置了追踪功能,在智能体运行期间收集全面的事件记录:LLM 生成、工具调用、交接、护栏,甚至自定义事件。使用 Traces 仪表盘,你可以在开发和生产环境中调试、可视化并监控工作流。
导出循环生命周期
Section titled “导出循环生命周期”在大多数环境中,追踪会按固定时间间隔自动导出。在浏览器或 Cloudflare Workers 中,该功能默认禁用。若排队的追踪过多,仍会导出,但不会定期导出。你应使用 getGlobalTraceProvider().forceFlush()
将导出追踪作为代码生命周期的一部分手动触发。
例如,在 Cloudflare Worker 中,应将代码包裹在 try/catch/finally
中,并结合 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(String(error), { status: 500 }); } finally { // make sure to flush any remaining traces before exiting ctx.waitUntil(getGlobalTraceProvider().forceFlush()); } },};
Trace 与 Span
Section titled “Trace 与 Span”- Traces 表示单个端到端“工作流”的一次运行。它们由多个 Span 组成。Trace 具有以下属性:
workflow_name
:逻辑上的工作流或应用。例如“Code generation”或“Customer service”。trace_id
:Trace 的唯一 ID。如果未传入会自动生成。必须符合格式trace_<32_alphanumeric>
。group_id
:可选的分组 ID,用于把同一会话中的多个 Trace 关联起来。例如你可以使用一个聊天线程 ID。disabled
:若为 True,则不会记录该 Trace。metadata
:Trace 的可选元数据。
- Spans 表示有开始和结束时间的操作。Span 具有:
started_at
和ended_at
时间戳。trace_id
,表示其所属的 Traceparent_id
,指向该 Span 的父 Span(如果有)span_data
,关于该 Span 的信息。例如,AgentSpanData
包含关于智能体的信息,GenerationSpanData
包含关于 LLM 生成的信息,等等。
默认情况下,SDK 会追踪以下内容:
- 整个
run()
或Runner.run()
都被包裹在一个Trace
中。 - 每次智能体运行都会被包裹在
AgentSpan
中 - LLM 生成被包裹在
GenerationSpan
中 - 每次函数工具调用被包裹在
FunctionSpan
中 - 护栏被包裹在
GuardrailSpan
中 - 交接被包裹在
HandoffSpan
中
默认的 Trace 名称是 “Agent workflow”。你可以通过 withTrace
设置该名称,或者通过 RunConfig.workflowName
配置名称和其他属性。
此外,你可以设置自定义追踪处理器,将追踪推送到其他目的地(作为替代或次要目的地)。
语音智能体追踪
Section titled “语音智能体追踪”如果你在使用 RealtimeAgent
和 RealtimeSession
,且使用默认的 OpenAI Realtime API,则追踪会在 Realtime API 端自动进行,除非你在 RealtimeSession
上使用 tracingDisabled: true
禁用,或设置 OPENAI_AGENTS_DISABLE_TRACING
环境变量。
查看语音智能体概述了解更多详情。
更高层级的 Trace
Section titled “更高层级的 Trace”有时,你可能希望多次调用 run()
都属于同一个 Trace。可以通过用 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()
包裹,因此各自的运行会归属到同一个整体 Trace,而不是创建两个 Trace。
创建 Trace
Section titled “创建 Trace”你可以使用 withTrace()
函数创建一个 Trace。或者,你也可以使用 getGlobalTraceProvider().createTrace()
手动创建一个新的 Trace,并将其传入 withTrace()
。
当前 Trace 通过 Node.js AsyncLocalStorage
或相应环境的 polyfill 进行跟踪。这意味着它能自动适配并发。
创建 Span
Section titled “创建 Span”你可以使用各种 create*Span()
(如 createGenerationSpan()
、createFunctionSpan()
等)方法创建一个 Span。通常你不需要手动创建 Span。提供了 createCustomSpan()
函数用于追踪自定义 Span 信息。
Span 会自动归属于当前 Trace,并嵌套在最近的当前 Span 之下;该状态通过 Node.js AsyncLocalStorage
或相应环境的 polyfill 跟踪。
某些 Span 可能会捕获潜在的敏感数据。
createGenerationSpan()
会存储 LLM 生成的输入/输出,而 createFunctionSpan()
会存储函数调用的输入/输出。这些可能包含敏感数据,因此你可以通过 RunConfig.traceIncludeSensitiveData
禁用对这些数据的捕获。
自定义追踪处理器
Section titled “自定义追踪处理器”追踪的高层架构如下:
- 在初始化时,我们会创建一个全局的
TraceProvider
,负责创建追踪,并可通过getGlobalTraceProvider()
访问。 - 我们用一个
BatchTraceProcessor
配置该TraceProvider
,它会将追踪/Span 批量发送给OpenAITracingExporter
,后者会将它们批量导出到 OpenAI 后端。
若要自定义该默认设置,将追踪发送到替代或额外的后端,或修改导出器行为,有两种方式:
addTraceProcessor()
允许添加一个“额外的”追踪处理器,它会在追踪和 Span 就绪时接收它们。这样你可以在将追踪发送到 OpenAI 后端之外,执行自定义处理。setTraceProcessors()
允许你“替换”默认处理器为自定义处理器。这意味着除非你包含一个将数据发送到 OpenAI 后端的TracingProcessor
,否则追踪不会发送到 OpenAI 后端。