追踪

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

注意

追踪默认启用。你可以通过两种方式禁用追踪：

1. 通过设置环境变量 OPENAI_AGENTS_DISABLE_TRACING=1 全局禁用追踪
2. 将 RunConfig.tracingDisabled 设置为 true，为单次运行禁用追踪

对于在 OpenAI 的 APIs 下采用 Zero Data Retention (ZDR) 策略的组织，追踪不可用。

导出循环的生命周期

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

• 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，表示其所属的 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 配置名称和其他属性。

此外，你可以设置custom trace processors，将追踪推送到其他目的地（作为替代或附加目的地）。

语音智能体追踪

如果你使用 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}`);
});

1. 因为两次对 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 之下；该状态通过 Node.js AsyncLocalStorage 或相应环境的 polyfill 跟踪。

敏感数据

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

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

自定义追踪处理器

追踪的高层架构如下：

• 初始化时，我们创建了一个全局的 TraceProvider，负责创建 Trace，并可通过 getGlobalTraceProvider() 访问。
• 我们为 TraceProvider 配置了一个 BatchTraceProcessor，它会将 Trace/Span 批量发送给 OpenAITracingExporter，由后者将 Span 和 Trace 批量导出到 OpenAI 后端。

若要自定义上述默认设置，以将追踪发送到其他或附加的后端，或修改导出器行为，你有两种选择：

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

外部追踪处理器列表

• AgentOps
• Keywords AI