如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

追踪

在控制台中查看智能体的活动并导出会话追踪记录。

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

追踪控制台展示智能体执行了哪些操作,以及每个步骤记录的输入、输出、耗时和状态。

如需通过 API 查看会话状态、实时事件、已保存的输出和用量,请先参阅可观测性。

新会话默认启用追踪。您可以在控制台中查看追踪记录,也可以通过 API 导出。

打开追踪记录

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

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

阅读追踪记录

先查看会话,再逐层查看轮次中的步骤:

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

选择一个跨度即可查看其状态、耗时、开始和结束时间,以及记录的数据:

选择项 可查看的内容
Agent 智能体的详情、指令和记录的 Token 用量
生成(一次模型响应) 为该次模型响应记录的输入和输出
工具 调用的工具、传给工具的参数,以及调用结果(如有)

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 协议(OTLP)格式的 JSON 数据。

您的组织必须已启用追踪记录导出功能。请使用会话所属项目的 API 密钥,该密钥需要具有追踪记录读取权限(api.traces.read)或范围更广的智能体读取权限(api.agents.read)。

设置 OPENAI_API_KEY,并将 sess_123 替换为您的会话 ID。以下示例使用 cURL 和 jq 将一页追踪记录保存为 traces.otlp.json:

下载一页会话追踪记录
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 为 true,请将 last_id 的值作为 after 参数请求下一页,并保持 order 不变。获取下一页之前,请先保存或上传当前页。重复此操作,直到 has_more 为 false。

每次请求只会导出当时可用的追踪记录。要导出历史记录,请等待会话中的所有轮次结束,并留出时间让追踪记录生成。导出操作不会自动配置后续追踪记录的投递。

导出某个智能体的追踪记录

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

查找某个智能体的会话
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: 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。

调用面板包含以下字段:

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

此片段展示了调用记录的一部分。同一面板还包含该调用的 arguments,以及保存在 output 中的 MCP 响应。单独的结果面板显示 null。该跨度的父跨度指向根智能体。

子智能体 B 的两个 notion.fetch 跨度具有相同的结构:工具类型为 mcp_call,MCP 响应位于调用面板中,父跨度指向子智能体 B。

本次会话的耗时与用量

两个子智能体的跨度在时间线上重叠。子智能体 A 耗时 24 秒,子智能体 B 耗时 21 秒,两者都在根智能体耗时 1 分 37 秒的跨度内运行。控制台显示的这些时长均经过四舍五入。

每个智能体跨度的用量面板显示为该智能体自身记录的 Token 数:

智能体 输入 Token 数 输出 Token 数 Token 总数
根智能体 126,390 1,567 127,957
子智能体 A 34,075 465 34,540
子智能体 B 89,304 667 89,971

在本次会话记录中,三个智能体的 Token 总数相加,正好等于会话顶部显示的 252,468 个 Token。