工作階段會將智慧體的對話和執行的工作記錄在一起。一個工作階段可以包含多個回合,每個回合都是一個工作週期。追蹤記錄會呈現單一回合中的各個步驟,包括模型回應、工具呼叫,以及委派給其他智慧體的工作。
追蹤儀表板會顯示智慧體執行了哪些工作,以及每個步驟記錄的輸入、輸出、耗時和狀態。
如要透過 API 查看工作階段狀態、即時事件、已儲存的輸出和用量,請先參閱可觀測性。
新工作階段預設會啟用追蹤功能。你可以在儀表板中查看追蹤記錄,也可以透過 API 匯出記錄。
開啟追蹤記錄
- 開啟日誌 → 智慧體,然後選取執行智慧體時使用的專案。
- 使用搜尋日誌找出工作階段。使用新增篩選條件依模型、狀態或日期篩選。
- 選取工作階段,開啟時間軸和回合清單。
- 展開一個回合,然後在時間軸或事件清單中選取一個步驟,查看詳細資料。
工作階段摘要會顯示狀態、模型、開始時間、最近活動時間、回合數,以及已記錄的 Token 用量。
解讀追蹤記錄
先查看工作階段,再逐層查看回合中的步驟:
- 工作階段: 「日誌 → 智慧體」中的每一筆項目都是一個工作階段。開啟工作階段即可查看時間軸和回合清單。例如,使用者可以詢問訂單資訊,然後在同一個工作階段中繼續追問。
- 回合: 展開回合即可查看該工作週期內執行的工作。一個回合可以包含多次模型回應和工具呼叫。回合結束後,使用者傳送的下一則訊息會在同一個工作階段中開啟新回合。
- 回合中的步驟: 追蹤記錄會將模型回應和工具呼叫歸在執行該步驟的根智慧體或子代理程式之下。每個記錄下來的步驟稱為一個跨度。
選取跨度即可查看其狀態、耗時、開始和結束時間,以及記錄的資料:
智慧體
智慧體跨度會彙整根智慧體或子代理程式執行的工作。子代理程式是受委派處理部分任務的另一個智慧體。模型回應和工具呼叫會顯示在執行該步驟的智慧體之下。
詳細資料面板會顯示:
- 智慧體類型: 根智慧體(
root)或子代理程式(subagent)。 - 智慧體: 其 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 Protocol(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"- 針對
data中的每個工作階段,使用該工作階段的id,依照上述方式逐頁匯出所有追蹤記錄。 - 如果工作階段清單包含
has_more: true,請將該清單的last_id作為after的值傳入,以擷取下一頁。保持agent_id和order不變。 - 重複上述步驟,直到工作階段清單包含
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。
呼叫面板包含以下欄位:
{
"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 數 | 輸出 Token 數 | Token 總數 |
|---|---|---|---|
| 根智慧體 | 126,390 | 1,567 | 127,957 |
| 子代理程式 A | 34,075 | 465 | 34,540 |
| 子代理程式 B | 89,304 | 667 | 89,971 |
在這個工作階段的記錄中,三個智慧體的 Token 總數相加,正好是工作階段頂端顯示的 252,468 個 Token。