追踪

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

导出循环生命周期

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

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

例如，在 Cloudflare Worker 中，您应该将代码包裹在 try/catch/finally 代码块中，并将 forceFlush() 与 waitUntil 配合使用，以确保在 worker 退出前导出 Trace。

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() 访问。
我们会为 TraceProvider 配置一个 BatchTraceProcessor，它会将 Trace/Span 批量发送到 OpenAITracingExporter，后者会将这些 Span 和 Trace 批量导出到 OpenAI 后端。

如果要自定义此默认设置，将 Trace 发送到替代或额外的后端，或修改导出器行为，您有两个选择：

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

追踪