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

可观测性与用量

查看实时进度、已完成的工作和记录的 Token 用量。

您可以通过以下方式实时跟踪智能体活动、查看已完成的工作,并了解每个轮次的详细执行过程:

  1. 在平台控制台中查看会话日志。
  2. 通过会话事件和已保存的历史记录跟踪会话进展。
  3. 查看会话轮次,确定哪些命令由子智能体执行。
  4. 查看根智能体和子智能体各轮次记录的 Token 用量。

在控制台中查看会话

前往 platform.openai.com/logs?api=agents,打开智能体选项卡。

按 ID 搜索会话,即可查看该会话的轮次、工具调用和子智能体。

按照追踪指南在控制台中查看记录的模型响应、工具调用和子智能体活动,或通过公共 API 以 OTLP JSON 格式导出会话追踪记录。

跟踪事件并查看会话历史记录

每个会话都提供事件流,实时显示智能体正在执行的操作。请设置 OPENAI_API_KEY,并将以下示例中的会话 ID 替换为您保存的会话 ID:

实时跟踪会话事件
// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";

const client = new OpenAI();
const events = await client.beta.agents.sessions.events.stream("sess_123");
try {
  for await (const event of events) {
    if (
      [
        "agent.session.turn.failed",
        "agent.session.turn.cancelled",
        "agent.session.failed",
        "agent.session.environment.failed",
        "error",
      ].includes(event.type)
    ) {
      throw new Error(`Agent lifecycle failure: ${event.type}`);
    }
    console.log(JSON.stringify(event));
  }
} finally {
  events.controller.abort();
}

即使收到空闲事件,事件流也会保持连接,因此您不会错过排队等待执行的工作。按 Ctrl+C 可停止监看。

会话运行期间,您会看到如下事件:

agent.session.environment.connected
agent.session.turn.created
agent.session.turn.in_progress
agent.session.turn.item.added
agent.session.turn.output_text.delta
agent.session.turn.completed
agent.session.idle

要查看会话中已经执行的操作,请获取已保存的会话条目:

查看已保存的会话条目
// Replace the illustrative IDs and URLs below with your own resource values.
import OpenAI from "openai";
const client = new OpenAI();

const sessionId = "sess_123";
const items = await client.beta.agents.sessions.items.list(sessionId, {
  order: "asc",
  limit: 100,
});
console.log(items.data);

查看轮次并识别委派给子智能体的命令

您可以通过公共 API 获取会话轮次。请将命令条目中的 turn_id 与您保存的会话 ID 一起使用。Go 示例使用 SDK 内置的分页功能搜索根智能体和子智能体的轮次,然后从匹配轮次所属的智能体获取该轮次。请将示例中的 ID 替换为您会话中的 ID。cURL 示例需要使用 jq:

确定哪个智能体执行了委派的命令
// Replace the illustrative session and turn IDs with values from your command item.
import OpenAI from "openai";
const client = new OpenAI();

async function findTurn(sessionId: string, turnId: string) {
  for await (const turn of client.beta.agents.sessions.turns.list(sessionId, {
    limit: 100,
  })) {
    if (turn.id === turnId) {
      return client.beta.agents.sessions.turns.retrieve(turnId, {
        session_id: sessionId,
      });
    }
  }
  for await (const subagent of client.beta.agents.sessions.subagents.list(
    sessionId,
    { limit: 100 }
  )) {
    for await (const turn of client.beta.agents.sessions.subagents.turns.list(
      subagent.id,
      { session_id: sessionId, limit: 100 }
    )) {
      if (turn.id === turnId) {
        return client.beta.agents.sessions.subagents.turns.retrieve(turnId, {
          session_id: sessionId,
          subagent_id: subagent.id,
        });
      }
    }
  }
  throw new Error(`Turn ${turnId} not found in session ${sessionId}`);
}

const turn = await findTurn("sess_123", "turn_123");
console.log(turn.subagent_id || "main agent");

手动分页时,请将返回的 last_id 用作下一页的 after 值,前提是 has_more 为 true。Go 示例会自动翻页。

命令条目包含 turn_id。获取对应的轮次并读取 subagent_id,即可确定哪个子智能体受委派执行了该命令。如果子智能体 ID 为 null,则表示该命令由根智能体执行。API 不会报告命令输出是否被截断。

查看轮次追踪记录

在平台控制台中,您可以查看已完成的轮次以及该轮次中的智能体活动。 要通过公共 API 获取已保存的追踪记录,请使用项目 API 密钥调用会话追踪记录导出端点。控制台使用的追踪端点独立于面向客户正式提供的 API。

轮次资源通过 usage 提供当前能统计到的用量,并通过 subagent_id 标识委派给子智能体的工作。用量未知时,其值可能为 null,已记录的用量也可能变化。请参阅查看子智能体的 Token 用量。

要确定某个 shell 命令由哪个智能体执行,请根据命令条目中的 turn_id 获取对应的轮次,然后查看 turn.subagent_id。面向客户的 API 不会指明命令输出是否被截断。

错误与恢复

请参阅错误与恢复,了解如何排查故障、选择恢复方式并安全重试。

模型用量与费用

智能体在完成一项任务的过程中可能多次调用模型。与 Responses API 一样,每次调用都遵循该模型的 Token 定价和提示词缓存规则。估算费用时,请计入完成任务所需的全部调用。

哪些因素会产生费用?

每次模型调用都可能消耗以下几类 Token:

  • 输入 Token: 智能体指令、工具定义、对话历史记录、用户输入、文件或图像,以及工具结果。
  • 缓存输入 Token: 从匹配的提示词前缀中复用的输入,按该模型的缓存输入费率计费。
  • 输出 Token: 生成的文本、工具调用参数和推理内容。

推理 Token 按输出 Token 计费。

子智能体也可以调用模型。分析模型费用时,请同时查看子智能体记录的各轮次用量和根智能体的用量。

核算费用时,请计入根智能体和子智能体执行的所有工作,包括重试,以及适用的工具、沙盒计算和第三方服务费用。如果模型对缓存写入收费,将输入写入缓存也会产生费用。下文列出的 Agents API 用量字段不单独提供写入缓存的 Token 数,因此在适用此类定价时,无法仅凭这些字段确定模型调用的确切费用。

提示词缓存

智能体会在同一会话中沿用之前的上下文。如果连续的模型调用具有相同的提示词前缀,提示词缓存就可以复用之前对该前缀的处理结果。模型仍会生成新的响应,不会从缓存中返回之前的回答。保持会话并不能保证缓存命中。能否复用缓存,取决于前缀是否匹配,以及模型规定的缓存条件和有效期。

在可行的情况下,请保持初始指令和工具定义稳定,并在后续消息中补充新的任务细节。使用工具搜索时,找到的工具定义会添加到对话末尾,使之前的内容保持原样,以便复用缓存。有关各模型的具体规则,请参阅提示词缓存。

缓存输入占比很高,并不能说明任务总费用节省了多少。缓存输入仍需付费,多次调用也可能反复处理大量历史记录。请在满足应用对质量和延迟要求的前提下,比较完成同一任务的总费用。

了解 Token 用量

会话和轮次资源通过 usage 提供当前能统计到的用量。用量未知时,该字段可能为 null。随着计量数据陆续到达,已记录的数量可能变化。缺少用量数据不代表用量为零。这些统计数字不等同于最终账单。

记录的用量对象包含以下几类 Token:

{
  "input_tokens": 5000,
  "input_tokens_details": {
    "cached_tokens": 1500
  },
  "output_tokens": 900,
  "output_tokens_details": {
    "reasoning_tokens": 200
  },
  "total_tokens": 5900
}

在此示例中,智能体处理了 5,000 个输入 Token,并生成了 900 个输出 Token。输入 Token 中有 1,500 个命中了缓存,输出 Token 中有 200 个是推理 Token。

缓存 Token 已计入 input_tokens,推理 Token 已计入 output_tokens。

查看子智能体的 Token 用量

列出或获取会话轮次,然后查看每个轮次的 usage。字段 subagent_id 标识对应的子智能体,在根智能体的轮次中其值为 null。当 has_more 为 true 时,将 last_id 作为 after 传入,并保持 order 不变,即可读取其余轮次。

用量反映当前能统计到的数据。用量未知时,其值可能为 null,已记录的数值也可能变化。您还可以在追踪控制台中查看每个智能体记录的用量。