理解 Trace 與 Span 怎樣記錄工作流，區分結果評分和行為評分，再圍繞工具、交接、Guardrail 與反饋恢復建立證據標準，用批量評估比較不同版本。
上一篇建立了 Agent Eval 的基本結構：給定任務，運行多次嘗試，再檢查執行記錄和實際結果。但拿到一條“失敗”的評分以後，排查才剛開始：是選錯了工具，傳錯了參數，交接時丟了信息，還是工具正確執行後，Agent 把結果理解錯了？
這些問題需要回到執行軌跡裏看。Trace Evaluation 不是把最終回答再評一次，而是把工作流中的行動、反饋和銜接納入判斷，讓一次成功或失敗有可以核對的過程依據。
結合 OpenAI 的《Evaluate agent workflows》與《Trace grading》，本文從三層展開：
- 記錄： Trace 與 Span 怎樣組織一次工作流，判斷行動需要哪些前後文。
- 診斷： 怎樣分別檢查工具、交接和執行邊界，區分行為錯誤、執行失敗與有效恢復。
- 比較： 怎樣把發現的問題寫成評分標準，再通過數據集與評估運行檢查改動。
下面延續一個假設的退款場景：用户已確認退回指定訂單的 50 元付款。例子中的金額統一使用人民幣，工具參數 amount_minor 以分為單位；日誌、字段與評分結果均為本文自擬的教學示意。
一、Trace 怎樣還原一次工作流h2
只看最終回答，往往只知道 Agent 宣佈了什麼。Trace 的作用，是把它拿到了哪些信息、提出過哪些動作、實際收到什麼反饋，以及下一步怎樣銜接，放進同一條執行記錄。
1. Trace 與 Span：整體執行和局部操作h3
Trace 組織一次工作流的整體記錄；Span 描述其中一段有邊界的操作。 模型調用、工具執行和 Agent 交接，可以分別成為軌跡中的局部片段。
例如，售後工作流可能先由入口 Agent 識別任務，再交給退款 Agent；退款 Agent 查詢訂單、提交操作、讀取反饋，最後答覆。只保存各步獨立日誌，就很難判斷某條工具返回屬於哪個請求，或者是哪位 Agent 在收到反饋以後繼續執行。
用整體記錄關聯局部操作，便能沿着工作流查看：
- 這一步由哪個角色發起，處於哪個任務中。
- 請求攜帶了什麼參數，實際返回了什麼。
- 操作何時開始、何時結束，是否報錯。
- 它與前後步驟是什麼關係，是否屬於某個子任務。
OpenAI 的SDK tracing 説明介紹了模型調用、工具、Handoff、Guardrail 和自定義 Span 等記錄，也給出了把多個 SDK run 放入同一 Trace 的用法。因此，不能機械地把一條 Trace 等同於一次模型推理或一次 SDK 調用。
具體能看到什麼，取決於實際採集。沒有記錄的檢查或外部狀態，不會因為界面上出現一條完整時間線就自動變得可見；Trace 也不是模型全部內部推理的透明快照。
2. 上下文與反饋：給每個動作找到判斷依據h3
看到一次 process_refund 調用，不能只檢查工具名和參數形狀。還要看當時已經具備什麼條件：訂單是否屬於當前用户、政策是否允許退款、用户是否確認，以及金額來自哪裏。
下面是一段簡化記錄：
用户请求：退回订单 ord_demo_18 的 50 元付款，已确认订单查询：订单已取消，尚未退款，可退金额 5000 分工具请求：process_refund(order_id="ord_demo_18", amount_minor=50000)执行前检查：金额超过可退范围，拒绝；未发生写操作后续行动：依据错误反馈，把 amount_minor 修正为 5000參數 50000 是合法整數，但與前序結果中的 5000 不一致。錯誤不是“模型沒有使用退款工具”，而是已經取得正確金額，卻在構造參數時放大了十倍。
這條差異只有把工具請求與前面的證據連起來才能看見。如果只保留“調用失敗”，就會丟掉兩個重要信息：失敗來自執行前檢查，而不是退款服務宕機；Agent 是否讀取拒絕原因並修正，還要看後續記錄。
因此，讀 Trace 不是逐行挑錯，而是檢查輸入依據 → 行動請求 → 實際反饋 → 後續處理有沒有接上。前序信息缺失、請求內容錯誤和反饋被忽略，是不同的排查位置。
二、怎樣從軌跡中檢查行為錯誤h2
結果評分和過程評分可以同時存在。前者核對任務是否完成，後者檢查這次完成或失敗中，哪些行為符合要求、哪些需要改進。
3. Outcome 與行為評分：分別檢查完成情況和執行質量h3
繼續看前面的錯誤金額。如果檢查拒絕後，Agent 修正參數，實際只退回 50 元，並準確告知用户，那麼最終 Outcome 可以正確，但“首次金額構造”這項行為檢查仍然未通過。
同時，“根據反饋恢復”可以通過。它沒有無視拒絕反覆提交，也沒有繞過檢查，而是用已有證據修正錯誤。一次錯誤和一次有效恢復，都應當在記錄中保留下來。
另一種情況是，Agent 選對工具、傳對參數，但退款服務返回錯誤，最終沒有成功記錄。這時任務未完成，卻不能把失敗直接標成“參數錯誤”。需要繼續區分工具執行問題，以及 Agent 有沒有如實報告失敗、有沒有采取符合約定的後續處理。
這兩種情況説明，業務結果、行為要求和恢復能力是可以分別評分的維度。總分可以彙總它們，卻不應該把它們的區別抹掉。
4. Tool Selection 與 Arguments：選對能力，傳入有依據的參數h3
工具檢查可以拆成兩個問題：這項能力適不適合當前任務，以及參數是否符合當前證據與業務語義。
在退款例子裏：
- 使用訂單查詢定位付款，是能力選擇問題。
- 查詢的是不是當前用户的目標訂單，是參數與對象對應問題。
amount_minor是否等於已確認的可退金額，是單位與數值問題。- 重複申請時有沒有創建第二筆退款，是狀態與冪等要求問題。
如果用户只是諮詢退款政策，直接選擇退款寫操作，即使參數完全合法，選擇仍然不合適。反過來，選中了正確的退款工具，卻把 50 元寫成 500 元，則是另一類錯誤。
這樣的劃分會影響修改方向。經常選錯能力，可以檢查工具名稱、用途邊界和指令；經常傳錯金額，則要繼續核對單位説明、返回字段和參數構造。Trace 提供排查線索，不意味着看到某個錯誤就能斷定唯一原因。
5. Routing 與 Handoff：檢查職責選擇和交接信息h3
多 Agent 工作流還要看任務交給了誰，以及接手者拿到了什麼。
例如，入口 Agent 已經取得訂單、身份核實結果與用户確認，再 Handoff 給退款 Agent。接手者如果只看到“用户想退款”，就可能重複追問，甚至用另一筆訂單繼續處理。表面上是後續 Agent 沒有完成任務，問題卻可能從交接信息開始。
可以分別檢查：
- Routing： 根據當時的請求和條件，是否選中了合適的處理分支。
- Handoff： 交接是否符合職責邊界，必要信息有沒有隨之傳遞。
- 接手處理： 後續角色是否使用了已取得的證據，是否正確接續未完成動作。
Manager 與 Handoff的返回關係也不同。專家作為工具返回結果，和轉交後續處理權，不能只因日誌裏都出現另一個 Agent，就用同一條“是否交接成功”標準判斷。
這裏檢查的是具體關係，不是要求所有售後問題都必須走相同的 Agent 順序。任務可以由單 Agent 完成時，沒有發生 Handoff 也不自動構成失敗。
6. Guardrail 與反饋恢復：區分攔截、違規和無效重試h3
Guardrail 出現拒絕記錄，不一定説明整個系統失效。在圖中的例子裏，金額檢查確實擋住了錯誤操作。但要同時保留兩項事實：Agent 提出了錯誤請求，執行層避免了它造成副作用。
評估還需要看拒絕之後發生了什麼：
- 依據可修正的錯誤原因調整參數，屬於有效恢復。
- 原樣重複不合法請求，增加調用卻沒有解決原因。
- 改用另一條通道執行同一違規動作，需要檢查是否試圖繞過邊界。
- 無法繼續時如實解釋並停止，可以符合任務的失敗處理要求。
因此，“觸發 Guardrail 的次數越少越好”不是充分的標準。檢查是否應該觸發、是否在操作前生效、是否錯誤攔截正常動作，都需要對應任務條件。
調用次數和輪次也要這樣理解。多問一次訂單號，可能是在補齊必要信息；把已經確認的訂單重複詢問五次，則可能暴露狀態沒有傳好。次數適合幫助篩選異常軌跡，是否冗餘仍需結合當時的信息判斷。
三、怎樣把單條診斷變成可重複的評估h2
讀懂一條 Trace，能夠幫助修復一次問題；把同類行為寫成一致標準，再作用於一批記錄，才能判斷它是不是反覆發生，以及改動有沒有改善。
7. Rubric：把判斷寫成帶證據的評分標準h3
“工具用得合理”太寬泛，不容易穩定評分。可以把它拆成可觀察的問題，並約定通過、失敗和證據不足時怎樣處理。
例如，在用户已確認退款的任務中，“金額參數是否正確”可以這樣定義：
檢查發往退款執行入口的請求，其訂單、幣種和金額是否與授權範圍及已核實的可退金額一致。按接口約定解釋單位。記錄被檢查的請求及相應證據；缺少關鍵條件時標為無法判斷，不猜測金額。
這樣的標準明確了檢查對象和依據，也避免只對着最終答覆判分。具體數值可以用程序核對；用户確認是否對應當前訂單等開放語義，可以結合模型評分與人工樣本校準。
下面是針對圖中例子的自擬評分結果，不是 OpenAI API 的返回結構：
{ "outcome": "pass", "first_refund_arguments": { "label": "fail", "evidence": "已确认金额为 5000 分，首次请求传入 50000 分" }, "amount_guardrail": { "label": "pass", "evidence": "执行前拒绝超额请求，未发生写操作" }, "feedback_recovery": { "label": "pass", "evidence": "读取拒绝原因后，修正为 5000 分并完成退款" }}結果應能追溯到實際記錄。工程中可以關聯到對應的 Span 或事件標識，讓評審者找到那次請求和反饋，而不只保留一句概括。
還要區分“這項標準不適用”和“缺少證據”。沒有要求 Handoff 的單 Agent 任務，可以不檢查交接；本應採集的交接信息丟失，則不能直接判為正確。
8. Dataset 與 Eval Run：從代表性記錄到批量比較h3
OpenAI 的工作流評估説明把單條 Trace 檢查與可重複的數據集評估連接起來：先弄清什麼行為值得檢查，再安排系統性的評估運行。
對於退款場景，可以把觀察到的問題整理成不同任務條件：金額單位變化、需要交接、重複申請、執行拒絕和服務失敗。每種條件都應包含正常與異常行為，避免評分器看到退款相關記錄就一律判錯。
批量評分後，不僅看整體通過率，還要按問題類型回看：
| 觀察到的變化 | 值得進一步檢查什麼 |
|---|---|
| 參數錯誤減少，最終完成率沒有提高 | 是否還有工具執行、交接或結果解釋問題 |
| 總分提高，但正常退款更常被拒絕 | 新規則是否造成過度攔截 |
| 平均調用數下降，信息不足任務更常失敗 | 是否減少了原本必要的澄清與查詢 |
| Handoff 次數減少，重複追問增加 | 職責調整是否同時破壞了信息銜接 |
這些是診斷方向，不是單靠統計就能證明的原因。需要抽查對應 Trace，確認評分依據與真實行為一致。
官方資料也給出了從 Traces 中檢查工作流、創建 Grader，再批量評估的入口。界面能夠幫助運行這些步驟，但哪些問題值得檢查、證據怎樣解釋，仍然取決於任務與標準本身。
9. Version Comparison：區分重評分和重新運行 Agenth3
比較版本時，有兩個容易混淆的操作：
- 對舊 Trace 重新評分： 行為記錄沒有變，改變的是檢查標準或評分器。
- 讓新版 Agent 重跑任務： 行為重新發生，產生新的 Trace 和 Outcome，再用可比較的標準評分。
如果只是修改 Grader 後，舊記錄的分數提高了，説明評價方式發生了變化，不能據此聲稱 Agent 已經改好。要驗證新指令是否讓金額構造更準確，需要讓新版本在相同任務起點重新執行。
反過來，新版本換了執行路徑，也不必因為它不再復現舊軌跡而扣分。應當檢查它是否仍滿足同樣的行為要求與結果標準，而不是把舊版本的步驟表當答案。
比較中記錄任務、Agent 配置與 Grader 版本，保留各維度結果，並抽查有明顯變化的軌跡。改進可能發生在參數構造、恢復方式或交接質量，而不一定立刻反映為總分的大幅變化。
Trace 給出的證據可以支持“錯誤發生在這一環”，但要驗證“修改這一處解決了問題”，還需要重跑和對照。例如，參數單位寫錯可能來自工具説明、上下文缺失或錯誤轉換，不能僅憑調用記錄直接把原因歸結為模型能力不足。
我更看重 Trace Evaluation 提供的這條連接：把一次執行裏的具體行為，變成可以定位、核對和持續比較的檢查項。 Outcome 説明做成了什麼，Trace 解釋執行過程中出現了什麼；兩者放在一起，改進才有明確對象。
幾個關鍵問題，串起執行記錄、診斷與迴歸h2
Trace 和普通日誌有什麼區別？
關鍵不在名字，而在關聯。零散日誌記錄發生過的事件，結構化 Trace 進一步組織它們屬於哪次工作流、哪項操作，以及怎樣相互銜接。只有大量文本，卻無法對應請求與結果，仍然不利於診斷。
最終成功了，中間傳錯一次參數還需要記錄嗎？
需要，但應分維度解釋。結果可以通過，首次參數檢查可以失敗，恢復能力可以通過。這樣既不掩蓋錯誤，也不把有效恢復誤寫成整條流程完全失敗。
Guardrail 拒絕了操作，應該給 Agent 通過還是失敗？
先看評的是什麼。錯誤請求應當被記錄；正確攔截可以通過執行邊界檢查；正常操作被誤拒則暴露另一類問題。單憑“有拒絕記錄”無法評價整條工作流。
Trace 能直接證明模型為什麼做錯嗎？
不能。它能顯示已記錄的輸入、請求和反饋，幫助定位錯誤環節，但不能讀出不可見的內部原因。修改工具説明、補齊上下文或調整指令後，還要通過重新執行驗證假設。
調用越少，是否説明工作流越好？
不一定。省去重複查詢有價值，省去必要確認卻可能增加錯誤。應先滿足結果和行為要求，再比較冗餘調用、輪次與耗時。
為什麼不能直接要求固定的工具調用順序？
因為合理任務可能有不同路徑。需要檢查的是有依據的約束，例如執行前取得確認，而不是無業務要求的步驟偏好。否則 Agent 找到了有效的替代路徑，也會被誤判。
給舊 Trace 換一個 Grader，算驗證新版 Agent 嗎？
不算。它驗證的是評分變化。新版 Agent 是否改善，需要重跑任務，取得新的執行記錄與結果，再在一致或明確記錄變化的標準下比較。