追踪

会话 将智能体的对话和工作保存在一起。一个会话可以包含多个 轮次，每个轮次都是一个工作周期。 追踪记录 展示一个轮次内的各个步骤：模型响应、工具调用，以及委派给其他智能体的工作。

追踪仪表板展示智能体执行了哪些工作，包括每个步骤记录的输入、输出、耗时和状态。

如需通过 API 获取会话状态、实时事件、已保存的输出和用量，请先阅读可观测性。

新会话默认启用追踪功能。您可以在仪表板中查看追踪记录，也可以通过 API 导出。

打开追踪记录

1. 打开日志 → 智能体，然后选择您运行智能体的项目。
2. 使用 搜索日志查找您的会话。使用 添加筛选条件 按模型、状态或日期筛选。
3. 选择会话，打开其时间线和轮次列表。
4. 展开一个轮次，然后在时间线或事件列表中选择一个步骤，查看其详情。

会话摘要显示会话的状态、模型、开始时间、最后活动时间、轮次数和已记录的 Token 用量。

解读追踪记录

先查看会话，再逐步深入到具体轮次：

1. 会话： 日志 → 智能体中的每个条目都是一个会话。打开会话即可查看其时间线和轮次列表。例如，用户可以先询问订单情况，然后在同一个会话中继续追问。
2. 轮次： 展开一个轮次，即可查看该工作周期内执行的工作。一个轮次可以包含多个模型响应和工具调用。轮次结束后发送的后续消息会在同一个会话中开始新的轮次。
3. 轮次内的步骤： 追踪记录将模型响应和工具调用归到执行它们的根智能体或子智能体下。每个记录的步骤称为一个 追踪片段。

选择一个追踪片段，查看其状态、耗时、开始和结束时间，以及记录的数据：

Agent

智能体追踪片段汇集了 根智能体 或 子智能体执行的工作。子智能体是受委派处理部分任务的另一个智能体。模型响应和工具调用会显示在执行它们的智能体下。

详情面板显示以下内容：

• 智能体类型： 根智能体（root）或子智能体（subagent）。
• Agent： 智能体的 ID、名称、模型和指令（如有记录）。
• 用量： 该智能体已记录的 Token 数量。这些数量仅涵盖智能体本身，不包括其子智能体。
• 耗时 和 结果状态： 记录的工作耗费了多长时间，以及工作是已完成、失败还是未完成。

生成

生成追踪片段汇集了已记录的模型输入和输出。每个轮次可以包含多次生成。

在模型推理过程中，模型读取输入并产生响应。该响应可以请求调用工具。工具返回结果后，模型可以在新的一次生成中产生另一个响应。

• 输入： 与该响应相关的已记录输入，例如用户消息或工具结果。
• 输出： 模型产生的已记录条目，例如回答文本或工具调用。
• 模型： 生成该响应所用的模型（如有记录）。

工具

工具追踪片段描述一次工具调用及其记录的结果。

工具追踪片段包括对您的函数以及 MCP（模型上下文协议） 服务器上工具的调用。网页搜索和命令执行也可以显示为工具追踪片段。

• 调用： 工具请求，包括工具名称和参数（如有）。
• 结果： 工具返回的已记录响应（如有）。
• 结果状态 和 错误： 已记录的结果和错误详情（如有）。

对于 MCP 工具调用， 调用 包含服务器标签（server_label）、工具名称（name）和参数（arguments）。响应和错误（如有）也会记录在其中，分别对应 output 和 error。单独的 结果 面板可能为空，因为 MCP 响应保存在 调用中。

时间与状态

时间线显示各步骤的顺序，以及哪些步骤在时间上重叠。 放大 可以更详细地展示耗时较短的步骤。 适配时间线 可以展示整个会话。

每个追踪片段都显示其耗时和结果状态。失败的追踪片段还可能包含已记录的错误详情。

智能体追踪片段的耗时包括其子步骤。步骤可以在时间上重叠：两个子智能体同时运行 10 秒，实际经过的时间约为 10 秒。

Token 用量

会话摘要中的 Token 显示会话用量。智能体追踪片段中的 用量 显示该智能体已记录的 Token 数量。

用量数据可能在轮次结束后才到达。值为空白或 null 表示数量未知，并不表示智能体使用了零个 Token。随着更多用量数据到达，数量可能发生变化，这些数量并非最终账单。

追踪记录何时可用

追踪记录在轮次结束后生成。智能体的回答可能先于追踪记录或 Token 用量显示。

智能体仍在工作时，实时会话事件会显示进度。

导出会话追踪记录

下载会话追踪记录，以便在其他追踪工具中查看。端点 GET /v1/agents/sessions/{session_id}/traces 返回一页包含 OpenTelemetry Protocol（OTLP）JSON 的追踪记录。

设置 OPENAI_API_KEY，并将 sess_123 替换为您的会话 ID。此示例使用 cURL 和 jq 将一页数据保存为 traces.otlp.json：

1
2
3
4
5
6curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions/sess_123/traces?limit=20&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: agents=v1" \
  --output trace-page.json && \
jq '{resourceSpans: [.data[].otlp.resourceSpans[]]}' trace-page.json > traces.otlp.json

该命令将这一页的追踪记录合并为一个 OTLP 载荷。请使用追踪服务提供商的身份验证方式，将载荷发送到该提供商的 OTLP/HTTP 端点。

要导出整个会话，请检查 trace-page.json。当 has_more 为 true 时，将 last_id 作为 after 的值请求下一页，并保持 order 不变。每次获取下一页之前，先保存或上传当前页，重复此操作，直到 has_more 为 false。

导出内容仅包含每次请求时已可用的追踪记录。要导出历史记录，请等待会话中的各个轮次结束，并留出时间让追踪记录生成。导出操作不会启用后续追踪记录的自动传送。

导出智能体的追踪记录

要导出某个智能体多个会话中的追踪记录，请先使用 agent_id 筛选条件列出会话。将 agent_123 替换为您的智能体 ID：

1
2
3
4curl --fail-with-body \
  "https://api.openai.com/v1/agents/sessions?agent_id=agent_123&limit=100&order=asc" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: agents=v1"

1. 对于 data 中的每个会话，使用其 id，按照上述方法导出该会话每一页的追踪记录。
2. 当会话列表中出现 has_more: true 时，将该列表的 last_id 作为 after 的值传入，以获取下一页。保持 agent_id 和 order 不变。
3. 重复此操作，直到会话列表中出现 has_more: false。

该筛选条件匹配会话的根智能体。请分别维护会话列表的游标和每个会话的追踪记录游标。

示例：包含两个子智能体的一个轮次

此示例基于一个已记录的会话。根智能体调用 MCP 工具，同时两个子智能体分别运行命令和获取文档。下文简化了子智能体的名称；数量和耗时均来自已记录的追踪数据。

会话与轮次

会话顶部显示 1 个轮次、 10 次工具调用和 252,468 个 Token。会话状态为 空闲， 第 1 轮 的状态为 已完成 ，耗时 1 分 37 秒。

展开该轮次即可看到根智能体及其子步骤。追踪记录包含 3 个智能体追踪片段 （根智能体和两个子智能体）、 11 个生成追踪片段和 10 个工具追踪片段。

此树状图将重复的生成和工具调用分组展示。它展示父子关系；时间线则展示各步骤的运行时间。

Session: Idle
└── Turn 1: Completed                              1m 37s
    └── Root agent                                1m 37s
        ├── 6 generations
        ├── 2 tools: spawn_agent_call
        ├── Subagent A                               24s
        │   ├── 2 generations
        │   └── Tool: command_execution               2s
        ├── Subagent B                               21s
        │   ├── 3 generations
        │   ├── 2 tools: notion.fetch              2s each
        │   └── Tool: send_input_call                 0ms
        ├── Tool: demo_capability_probe              87ms
        └── 3 tools: wait_for_agents_call

模型工作与任务委派

根智能体的第一个 生成 记录在 输入中包含用户消息。其 输出 包含消息和两个 spawn_agent_call 条目。这些调用也会显示为 工具 追踪片段，而由此创建的子智能体则显示为根智能体下的 Agent 追踪片段。

子智能体 A 有自己的生成记录和一次 command_execution 工具调用。子智能体 B 有三个生成记录、两次 notion.fetch MCP 调用和一次 send_input_call 调用。它们的模型响应和工具分别归属于各自的子智能体追踪片段。

根智能体还有三个 wait_for_agents_call 工具追踪片段。它的最后一个生成记录包含一条消息，记录的耗时为 6 秒。

一次 MCP 工具调用

根智能体的 demo_capability_probe 追踪片段是一个已完成的 工具 追踪片段，耗时为 87 毫秒。它的 工具类型 为 mcp_call。

调用 面板包含以下字段：

123456{
  "type": "mcp_call",
  "server_label": "demo_local",
  "name": "demo_capability_probe",
  "status": "completed"
}

此摘录展示了所记录调用的一部分。同一面板还包含该调用的 arguments，以及 output 中的 MCP 响应。单独的 结果 面板显示为 null。该追踪片段的 父追踪片段 指向根智能体。

子智能体 B 的两个 notion.fetch 追踪片段具有相同的结构：工具类型为 mcp_call，MCP 响应位于 调用中，父级为该子智能体。

此会话中的时间与用量

两个子智能体的追踪片段在时间线上有重叠。子智能体 A 耗时 24 秒 ，子智能体 B 耗时 21 秒，两者都位于根智能体时长为 1 分 37 秒 的追踪片段内。仪表板对这些显示的时长进行了四舍五入。

每个智能体追踪片段的 用量 面板显示该智能体自身记录的 Token 数：

在此记录的会话中，三个智能体的 Token 总数相加，等于会话页眉显示的 252,468 个 Token 。