OpenAI Agents SDK 0.22 適合正在把模型接到檢索、工單、數據庫或內部服務的開發者。它這次的重點不是增加一個新工具而是收緊工具輸出、終態失敗和運行狀態的處理邊界。升級時先把這三類失敗路徑寫成回歸測試再替換依賴版本pip install -U openai-agents0.22.0 pytest隨后執行pytest tests/test_agent_upgrade_contract.py -q。這樣能先確認被攔截的內容不會進入可回放狀態、失敗不會被誤當成功、并行任務的用量不會串賬。## 0.22 到底改變了什么官方 2026 年 8 月 19 日發布的v0.22.0說明運行時會從可回放、可持久化的 SDK 狀態中脫敏那些被 Agent 輸出護欄拒絕的終態函數工具輸出。非流式 Responses 如果以failed或incomplete結束會拋出ModelBehaviorError獨立RunState檢查點之間的用量統計也被隔離同時保留嵌套 Agent 的匯總能力。這三個事實對應的不是“升級后更安全”這種籠統結論而是三個可檢查的契約被拒絕的工具原文不能進入你的回放存儲終態失敗必須顯式進入錯誤路徑兩個并行或恢復中的任務不能互相污染計量數據。## 為什么工具輸出也要做持久化回歸很多團隊只檢查提示詞和模型最終回答卻把函數返回值原樣寫入追蹤、會話快照或排障日志。問題是護欄已經拒絕的輸出仍可能在另一條持久化鏈路中留下原文。0.22 的變更把這個邊界推進到 SDK 的可回放狀態但應用側仍應確認自己的追蹤導出、審計存儲和異常收集器沒有額外復制原值。下面的示例是項目接入層的回歸斷言模板不是 SDK 原樣 API。把persisted_snapshot替換成你自己的會話快照或審計記錄即可pythondef assert_blocked_output_is_not_persisted(persisted_snapshot: str, raw_tool_output: str) - None: assert raw_tool_output not in persisted_snapshotdef test_rejected_tool_output_has_no_replay_copy(): raw_tool_output customer-private-result persisted_snapshot run_and_export_after_guardrail( tool_outputraw_tool_output, guardrail_rejectedTrue, ) assert_blocked_output_is_not_persisted(persisted_snapshot, raw_tool_output)斷言的對象應當是實際落盤或實際發送到觀測系統的序列化結果而不是內存中的臨時變量。測試數據必須是脫敏的虛構值不要為了證明測試有效而放入真實客戶信息、令牌或內部地址。## 終態失敗為什么不能偽裝成空結果在非流式調用中failed與incomplete是終態不應由業務代碼繼續把它包裝為空字符串、默認答案或“任務完成”。官方在 0.22 中讓這兩類終態觸發ModelBehaviorError目的是讓調用方進入明確的錯誤分支。應用層要做的是區分“可以重試的瞬時失敗”和“需要人工或工作流決定的終態失敗”。前者寫入有限次數、帶退避的隊列后者保留失敗原因、輸入摘要和關聯任務 ID并停止后續的高權限工具調用。## 如何檢查恢復任務沒有串用量長任務常常會暫停、恢復或把子任務交給另一個 Agent。若用量統計混在一起預算告警、成本核對和任務級審計都會失去意義。0.22 的發行說明提到獨立RunState檢查點之間隔離用量同時保留嵌套 Agent 聚合這不等于應用可以放棄驗證。建議構造兩個輸入不同、執行時間交疊的恢復任務分別讀回它們的檢查點再驗證每個任務的用量只包含自己的模型調用。嵌套子 Agent 的聚合結果要單獨斷言不能把“父任務匯總正確”誤認為“兩個父任務彼此獨立”。## 一套可執行的升級順序是什么1. 在隔離分支鎖定舊版本保存現有的正常、被拒絕和終態失敗測試樣本。2. 升級到openai-agents0.22.0不同時改提示詞、工具描述和模型版本。3. 先跑工具輸出持久化、終態失敗和檢查點隔離三組斷言再跑現有集成測試。4. 檢查追蹤、日志和異常平臺的導出字段確認被拒絕的原值沒有被應用側副本帶出。5. 灰度發布時按任務 ID 觀察失敗分支、重試次數和檢查點用量一旦偏離基線回滾依賴并保留脫敏后的診斷記錄。## 常見問題### 這是否意味著所有工具輸出都會自動脫敏不是。官方變更針對被 Agent 輸出護欄拒絕的終態函數工具輸出在 SDK 可回放、持久化狀態中的處理。你自己寫入數據庫、日志、消息隊列或第三方觀測平臺的副本仍應逐條檢查。### 只有使用 MCP 時才需要做這些測試嗎不是。無論工具來自本地函數、HTTP 服務還是 MCP都會經過“執行、結果、護欄、持久化、恢復”這條鏈路。MCP 只是讓工具來源更分散因此更需要明確權限和審計邊界。### 能把這篇文章的代碼直接用于生產嗎不能直接照搬。代碼只展示回歸斷言的形狀run_and_export_after_guardrail需要替換為你項目的真實執行和序列化適配器。生產環境還應按數據等級、工具權限、重試策略和合規要求補全審計規則。## 結語這次升級最值得帶走的實踐是智能體的質量門禁不只驗證“回答對不對”還要驗證失敗時留下了什么、停止在哪里、恢復后是否保持獨立。把三條契約寫進持續集成才能讓工具調用從演示階段走向可控的工程運行。## 來源- OpenAI Agents SDK v0.22.0 官方發行說明- OpenAI Agents SDK v0.21.1 官方發行說明- OpenAI Agents SDK v0.20.0 官方發行說明- OpenAI Agents SDK 官方文檔- PyPIopenai-agents 0.22.0 發布記錄