追踪

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

导出循环生命周期

在受支持的服务器运行时中，trace 会按固定间隔导出。在某些运行时中，包括 Cloudflare Workers，自动导出循环不可用，即使追踪本身仍然启用。在这些环境中，你应该在请求生命周期中调用 getGlobalTraceProvider().forceFlush()，以便在运行时被销毁之前导出队列中的 trace。

此建议不适用于浏览器，因为浏览器默认禁用追踪。

例如，在 Cloudflare Worker 中，你应该将代码包裹在 try/catch/finally 块中，并将 forceFlush() 与 waitUntil 结合使用，以确保 trace 在 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

Trace 表示一次”工作流”的端到端操作。它们由 Span 组成。Trace 具有以下属性：
- workflow_name：逻辑工作流或应用。例如”代码生成”或”客户服务”。
- trace_id：trace 的唯一 ID。如果你没有传入，则会自动生成。必须采用 trace_<32_alphanumeric> 格式。
- group_id：可选的组 ID，用于关联同一对话中的多个 trace。例如，你可以使用聊天线程 ID。
- disabled：如果为 True，则不会记录该 trace。
- metadata：trace 的可选元数据。
Span 表示具有开始和结束时间的操作。Span 包含：
- started_at 和 ended_at 时间戳。
- trace_id，表示其所属的 trace。
- parent_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 配置名称和其他属性。

此外，你可以设置自定义追踪处理器，将 trace 推送到其他目的地（作为替代目的地或次要目的地）。

语音智能体追踪

如果你将 RealtimeAgent 和 RealtimeSession 与默认的 OpenAI Realtime API 一起使用，则追踪会自动在 Realtime API 侧进行，除非你在 RealtimeSession 上使用 tracingDisabled: true 或使用 OPENAI_AGENTS_DISABLE_TRACING 环境变量将其禁用。

更多详情请参阅语音智能体概述。

更高层级的 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 的创建

你可以使用 withTrace() 函数创建 trace。或者，你也可以使用 getGlobalTraceProvider().createTrace() 手动创建新的 trace，并将其传入 withTrace()。

当前 trace 通过 Node.js AsyncLocalStorage 或相应环境的 polyfill 进行跟踪。这意味着它可以自动处理并发。

Span 的创建

你可以使用各类 create*Span()（例如 createGenerationSpan()、createFunctionSpan() 等）方法来创建 span。通常，你不需要手动创建 span。可使用 createCustomSpan() 函数来跟踪自定义 span 信息。

Span 会自动成为当前 trace 的一部分，并嵌套在最近的当前 span 下；当前 span 通过 Node.js AsyncLocalStorage 或相应环境的 polyfill 进行跟踪。

敏感数据

某些 span 可能会捕获潜在的敏感数据。

createGenerationSpan() 会存储 LLM 生成的输入/输出，createFunctionSpan() 会存储函数调用的输入/输出。这些可能包含敏感数据，因此你可以通过 RunConfig.traceIncludeSensitiveData 禁用对此类数据的捕获。

OpenAI 追踪导出器

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

如果你需要自定义摄取行为，请自行实例化 OpenAITracingExporter，并使用 setTraceProcessors(...) 或 addTraceProcessor(...) 安装它。该导出器支持 apiKey、endpoint、organization、project、maxRetries、baseDelay 和 maxDelay。

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

自定义追踪处理器

追踪的高层架构如下：

初始化时，我们会创建一个全局 TraceProvider，它负责创建 trace，并且可以通过 getGlobalTraceProvider() 访问。
我们会使用 BatchTraceProcessor 配置 TraceProvider，它会将 trace/span 批量发送到 OpenAITracingExporter，后者会将 span 和 trace 批量导出到 OpenAI 后端。

如果要自定义此默认设置，例如将 trace 发送到其他或额外的后端，或修改导出器行为，你有两个选择：

addTraceProcessor() 允许你添加一个额外的追踪处理器，它会在 trace 和 span 就绪时接收它们。这样，除了将 trace 发送到 OpenAI 后端之外，你还可以进行自己的处理。
setTraceProcessors() 允许你用自己的追踪处理器替换默认处理器。这意味着除非你包含一个会将 trace 发送到 OpenAI 后端的 TracingProcessor，否则 trace 不会被发送到 OpenAI 后端。

追踪