OpenAI 追踪

会话聚合智能体对话和工作，可有多个轮次，每轮是一轮工作循环。追踪（trace）展示某一轮中的模型响应、工具调用及委派工作。

追踪控制台显示各步骤记录的输入、输出、时长和状态。API中的状态、实时事件、保存输出及用量，从可观测性入手。

新会话默认启用追踪，可在控制台检查或通过API导出。

打开追踪

1. 打开 Logs → Agents，选择运行项目。
2. 用 Search logs 查会话，Add filter 按模型、状态或日期筛选。
3. 选择会话，打开时间线与轮次列表。
4. 展开轮次，选时间线或事件列表中的步骤查看细节。

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

阅读追踪

1. 会话：Logs → Agents每个条目是一条会话，打开后可见时间线和轮次。用户可先问订单，再在同会话追问。
2. 轮次：展开查看此工作循环，一轮可含多个模型响应和工具调用。轮次完成后再发消息会开始新轮次。
3. 轮内步骤：模型和工具归属执行它们的主智能体或子智能体；每个记录步骤称为跨度（span）。

选span可查看状态、时长、起止时间及记录数据：

智能体

Agent span聚合主智能体或被委派子智能体的工作，模型响应和工具调用归于实际执行者。详情包括：

• Agent type：root 或 subagent。
• Agent：已记录的ID、名称、模型与指令。
• Usage：该智能体自身用量，不含子智能体。
• Duration与Outcome status：已记录时长，以及完成、失败或未完成状态。

模型生成

Generation span聚合一次模型响应的输入和输出，一轮可有多次生成。模型读取输入后可能请求工具；工具返回后，再由下一次生成继续。

• Input：相关的已记录用户消息或工具结果等输入。
• Output：模型生成的回答或工具调用等项目。
• Model：记录可用时显示所用模型。

工具

Tool span记录调用及结果，包含应用函数、MCP、搜索及命令执行：

• Call：请求、工具名与可用参数。
• Result：可用的返回结果。
• Outcome status与Error：结果状态及可用错误。

MCP的Call包含 server_label、name、arguments，响应及错误也以 output、error 放在此处。因此独立Result面板可能为空。

时间与状态

时间线显示先后及重叠，Zoom in 查看短步骤细节，Fit timeline 查看全会话。各span显示时长和结果，失败可带错误详情。

Agent span时长包含子步骤，重叠不能简单相加：两个子智能体并行各运行10秒，经过时间约10秒。

词元用量

会话摘要Tokens是会话用量，Agent span的Usage是该智能体自身记录。用量可能晚于轮次结束到达，空白或 null 表示未知，不是零。更多数据到达时会变化，也不是最终账单。

追踪何时可用

追踪在轮次结束后构建，回答可能先于追踪和用量出现。工作中进度看实时会话事件。

导出会话追踪

GET /v1/agents/sessions/{session_id}/traces 分页返回含OpenTelemetry Protocol（OTLP）JSON的追踪，可供其他工具分析。

组织须启用导出，项目API密钥具有 api.traces.read 或更广的 api.agents.read。设置 OPENAI_API_KEY，用实际ID替换 sess_123。以下用cURL和jq把一页保存为 traces.otlp.json：

来源示例 1（bash）：

## [中文] 示例 1：导出会话追踪。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions/sess_123/traces?limit=20&order=asc；示例占位地址需替换为实际资源。
curl --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 为真则以 last_id 为 after，保持 order，先保存或上传本页再读取下一页，直到无更多页。

每页只含请求时已可用追踪。历史导出应等待轮次结束并留出追踪生成时间；导出不会自动持续投递未来追踪。

导出一个智能体的追踪

先以 agent_id 列出会话，替换示意值 agent_123：

来源示例 2（bash）：

## [中文] 示例 2：导出一个智能体的追踪。
## [中文] 本段涉及的请求或服务地址：https://api.openai.com/v1/agents/sessions?agent_id=agent_123&limit=100&order=asc；示例占位地址需替换为实际资源。
curl --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 为真时，用该列表 last_id 作为 after，保持 agent_id 和 order。
3. 重复直到会话列表结束。

过滤条件匹配会话主智能体。会话列表游标与各会话追踪游标分开保存。

示例：一个轮次与两个子智能体

以下来自已记录会话。主智能体调用MCP，同时两个子智能体运行命令、读取文档。名称作了简化，计数和时长来自该追踪。

会话与轮次

头部显示 1个轮次、10次工具调用、252,468词元，会话状态 Idle，第1轮 Completed，耗时 1分37秒。

展开后有 3个Agent span、11个Generation span、10个Tool span。以下树把重复生成和调用合并显示，用于表达父子关系，实际时序看时间线：

来源示例 3（text）：

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

模型工作与委派

主智能体首个Generation的Input含用户消息，Output含消息和两个 spawn_agent_call，这些调用也以Tool span出现，结果子智能体以子Agent span出现。

子智能体A有自己的生成和 command_execution；B有三次生成、两次 notion.fetch、一次 send_input_call，均归属各自span。

主智能体还有三次 wait_for_agents_call，最终生成含一条消息，记录时长6秒。

一次 MCP 调用

主智能体 demo_capability_probe 为已完成Tool span，耗时87毫秒，Tool type是 mcp_call，Call含：

来源示例 4（json）：

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

这只是记录片段，同面板还含 arguments 和MCP output。Result面板独立显示为 null，Parent span指向主智能体。B的两次 notion.fetch 结构相同，响应在Call中，父span为B。

此会话的时间与用量

A与B重叠执行，分别24秒、21秒，均包含在主智能体1分37秒内；控制台对显示时长有舍入。

此已记录会话中，三者合计252,468，与会话头部一致。