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