如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .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 依輸出 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 已計入 input_tokens,推理 Token 已計入 output_tokens。

檢視子代理程式的 Token 用量

列出或擷取工作階段中的回合,並檢視每個回合的 usage。subagent_id 用於識別子代理程式,在根智慧體的回合中,其值為 null。當 has_more 為 true 時,請將 last_id 作為 after 傳入,並沿用相同的 order 值,以讀取其餘回合。

用量會根據目前可取得的資料提供。用量不明時,值可能為 null,已記錄的數值也可能變更。你也可以在追蹤儀表板中檢視各智慧體記錄的用量。