追踪

Agents SDK 内置了追踪功能，可收集智能体运行期间发生的完整事件记录：LLM 生成、工具调用、交接、护栏，甚至包括发生的自定义事件。借助追踪控制面板，您可以在开发和生产环境中调试、可视化并监控工作流。

导出循环生命周期

在受支持的服务器运行时中，追踪会定期导出。在包括 Cloudflare Workers 在内的某些运行时中，尽管追踪本身仍处于启用状态，但自动导出循环不可用。在这些环境中，您应当在请求生命周期内调用 getGlobalTraceProvider().forceFlush()，以便在运行时被销毁前导出排队中的追踪。

此指导不适用于浏览器，因为浏览器中的追踪默认处于禁用状态。

例如，在 Cloudflare Worker 中，您应当将代码封装在 try/catch/finally 块中，并结合 waitUntil 使用 forceFlush()，以确保在 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());
    }
  },
};

追踪与跨度

追踪表示一次端到端的”工作流”操作，由多个跨度组成。追踪具有以下属性：
- 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 中。
每次顶层运行器调用都封装在一个 TaskSpan 中。
每次智能体运行都封装在一个 AgentSpan 中。
智能体循环的每次迭代都封装在一个 TurnSpan 中。
LLM 生成封装在 GenerationSpan 中。
每次函数工具调用都封装在一个 FunctionSpan 中。
护栏封装在 GuardrailSpan 中。
交接封装在 HandoffSpan 中。

默认层次结构为 TaskSpan → AgentSpan → TurnSpan，模型和工具工作嵌套在轮次之下。任务跨度会汇总该次调用的请求和 token 使用情况。每个轮次跨度都会记录轮次编号、智能体名称，以及输入、输出、缓存输入和缓存写入的 token 数量。

任务跨度和轮次跨度默认启用。在 Runner 或单次运行中设置 tracing: { includeTaskAndTurnSpans: false }，可省略这一附加层次结构。单次运行的追踪选项会覆盖运行器级别的设置。

默认情况下，追踪名为”Agent workflow”。使用 withTrace 时可以设置此名称，也可以通过 RunConfig.workflowName 配置名称及其他属性。

此外，您还可以设置自定义追踪处理器，将追踪推送到其他目标（作为替代目标或辅助目标）。

实时智能体追踪

如果您通过默认的 OpenAI Realtime API 使用 RealtimeAgent 和 RealtimeSession，追踪会自动在 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 追踪导出器

在受支持的服务器运行时中，默认追踪设置已会将数据导出到 OpenAI。当追踪导出需要使用不同于 OPENAI_API_KEY 的凭据时，请使用 setTracingExportApiKey()。

如果您需要自定义数据接收行为，请自行实例化 OpenAITracingExporter，并使用 setTraceProcessors(...) 或 addTraceProcessor(...) 进行配置。该导出器支持 apiKey、endpoint、organization、project、maxRetries、baseDelay 和 maxDelay。

如果您替换了默认处理器，之后希望恢复使用批处理器的默认 OpenAI 导出器，请调用 setDefaultOpenAITracingExporter()。

自定义追踪处理器

追踪功能的高层架构如下：

初始化时，我们会创建一个全局 TraceProvider，它负责创建追踪，并且可以通过 getGlobalTraceProvider() 访问。
我们为 TraceProvider 配置了一个 BatchTraceProcessor，它会将追踪和跨度分批发送到 OpenAITracingExporter，后者会将跨度和追踪分批导出到 OpenAI 后端。

要自定义这一默认设置、将追踪发送到其他或额外的后端，或者修改导出器行为，您有两种选择：

addTraceProcessor() 允许您添加一个额外的追踪处理器，该处理器会在追踪和跨度准备就绪时接收它们。这样，除了将追踪发送到 OpenAI 后端之外，您还可以执行自己的处理。
setTraceProcessors() 允许您使用自己的追踪处理器替换默认处理器。这意味着，除非您包含一个负责发送数据的 TracingProcessor，否则追踪不会发送到 OpenAI 后端。

追踪