升级 OpenAI Agents SDK 0.22：用回归测试守住工具输出和运行状态

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 发布记录