追踪

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

导出循环生命周期

在大多数环境中，追踪会以固定间隔自动导出。在浏览器或 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());
    }
  },
};

追踪与 span

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

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

语音智能体追踪

如果你在使用 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 进行跟踪。这意味着它能自动适配并发场景。

创建 span

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

Span 会自动加入当前追踪，并嵌套在最近的当前 span 之下；当前 span 通过 Node.js AsyncLocalStorage 或对应环境 polyfill 进行跟踪。

敏感数据

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

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，以批量将追踪/span 发送到 OpenAITracingExporter，它会将 span 与追踪批量导出到 OpenAI 后端。

若要自定义此默认设置、将追踪发送到替代或额外的后端，或修改导出器行为，你有两种选择：

addTraceProcessor() 允许添加一个“额外”的追踪处理器，用于在追踪与 span 就绪时接收它们。这样你可以在将追踪发送到 OpenAI 后端之外，执行你自己的处理。
setTraceProcessors() 允许用你自己的追踪处理器“替换”默认处理器。除非你包含一个会执行该操作的 TracingProcessor，否则追踪将不会发送到 OpenAI 后端。