追蹤

工作階段 將智慧體的對話與工作整合在一起。一個工作階段可以包含多個 回合，每個回合都是一個工作循環。 追蹤記錄 會顯示單一回合內的各個步驟：模型回應、工具呼叫，以及委派給其他智慧體的工作。

追蹤儀表板會顯示智慧體執行過的工作，包括每個步驟所記錄的輸入、輸出、持續時間與狀態。

若要透過 API 取得工作階段狀態、即時事件、已儲存的輸出與用量，請先參閱可觀測性。

新工作階段預設會啟用追蹤功能。您可以在儀表板中檢視追蹤記錄，或透過 API 匯出。

開啟追蹤記錄

1. 開啟 記錄 → 智慧體，並選取執行智慧體的專案。
2. 使用 搜尋記錄尋找工作階段。使用 新增篩選條件 ，依模型、狀態或日期篩選。
3. 選取工作階段，即可開啟其時間軸與回合清單。
4. 展開回合，再選取時間軸或事件清單中的步驟，即可查看詳細資訊。

工作階段摘要會顯示狀態、模型、開始時間、最近活動、回合數，以及所記錄的 Token 用量。

閱讀追蹤記錄

先查看工作階段，再深入查看回合：

1. 工作階段： 「記錄 → 智慧體」中的每個項目都是一個工作階段。開啟後即可查看其時間軸與回合清單。例如，使用者可以先詢問訂單，再於同一個工作階段中繼續追問。
2. 回合： 展開回合，即可查看該工作循環中執行的工作。一個回合可以包含多次模型回應與工具呼叫。回合結束後傳送的後續訊息，會在同一個工作階段中啟動另一個回合。
3. 回合內的步驟： 追蹤記錄會將模型回應與工具呼叫歸在執行它們的根智慧體或子代理程式之下。每個記錄下來的步驟稱為一個 區段。

選取區段，即可查看其狀態、持續時間、開始與結束時間，以及所記錄的資料：

智慧體

智慧體區段會彙整 根智慧體 或 子代理程式所執行的工作；子代理程式是受託處理部分任務的另一個智慧體。模型回應與工具呼叫會顯示在執行它們的智慧體之下。

詳細資訊面板會顯示：

• 智慧體類型： 根智慧體（root）或子代理程式（subagent）。
• 智慧體： 其 ID、名稱、模型與指示（若有記錄）。
• 用量： 該智慧體所記錄的 Token 數量。這些數量僅涵蓋智慧體本身，不包含其子代理程式。
• 持續時間 與 結果狀態： 所記錄的工作耗時多久，以及工作已完成、失敗或未完成。

生成

生成區段會彙整所記錄的模型輸入與輸出。每個回合可以包含多次生成。

模型推論時，會讀取輸入並產生回應。該回應可以要求呼叫工具。工具傳回結果後，模型可以在新一次生成中產生另一個回應。

• 輸入： 與該回應相關的輸入記錄，例如使用者訊息或工具結果。
• 輸出： 模型產生的項目記錄，例如答案文字或工具呼叫。
• 模型： 用於產生該回應的模型（若有記錄）。

工具

工具區段會描述一次工具呼叫及其記錄的結果。

工具區段包含對你的函式及 MCP (Model Context Protocol) 伺服器上工具的呼叫。網頁搜尋與指令執行也可能顯示為工具區段。

• 呼叫： 工具請求，包括工具名稱與引數（若有）。
• 結果： 所記錄的工具回應（若有）。
• 結果狀態 與 錯誤： 所記錄的結果與錯誤詳細資訊（若有）。

對於 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 項目。這些呼叫也會顯示為 工具 追蹤區段，而由此建立的子代理程式則會顯示為根智慧體底下的 智慧體 追蹤區段。

子代理程式 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 。