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

OpenAI Agents SDK 0.22 适合正在把模型接到检索、工单、数据库或内部服务的开发者。它这次的重点不是增加一个新工具，而是收紧工具输出、终态失败和运行状态的处理边界。升级时，先把这三类失败路径写成回归测试，再替换依赖版本：`pip install -U openai-agents==0.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_snapshot

def test_rejected_tool_output_has_no_replay_copy():    raw_tool_output = "customer-private-result"    persisted_snapshot = run_and_export_after_guardrail(        tool_output=raw_tool_output,        guardrail_rejected=True,    )
    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-agents==0.22.0`，不同时改提示词、工具描述和模型版本。3. 先跑工具输出持久化、终态失败和检查点隔离三组断言，再跑现有集成测试。4. 检查追踪、日志和异常平台的导出字段，确认被拒绝的原值没有被应用侧副本带出。5. 灰度发布时按任务 ID 观察失败分支、重试次数和检查点用量；一旦偏离基线，回滚依赖并保留脱敏后的诊断记录。

常见问题

这是否意味着所有工具输出都会自动脱敏？
不是。官方变更针对被 Agent 输出护栏拒绝的终态函数工具输出在 SDK 可回放、持久化状态中的处理。你自己写入数据库、日志、消息队列或第三方观测平台的副本，仍应逐条检查。

只有使用 MCP 时才需要做这些测试吗？
不是。无论工具来自本地函数、HTTP 服务还是 MCP，都会经过“执行、结果、护栏、持久化、恢复”这条链路。MCP 只是让工具来源更分散，因此更需要明确权限和审计边界。

能把这篇文章的代码直接用于生产吗？
不能直接照搬。代码只展示回归断言的形状；`run_and_export_after_guardrail` 需要替换为你项目的真实执行和序列化适配器。生产环境还应按数据等级、工具权限、重试策略和合规要求补全审计规则。

结语
这次升级最值得带走的实践是：智能体的质量门禁不只验证“回答对不对”，还要验证失败时留下了什么、停止在哪里、恢复后是否保持独立。把三条契约写进持续集成，才能让工具调用从演示阶段走向可控的工程运行。

来源
- [OpenAI Agents SDK v0.22.0 官方发行说明](https://github.com/openai/openai-agents-python/releases/tag/v0.22.0)- [OpenAI Agents SDK v0.21.1 官方发行说明](https://github.com/openai/openai-agents-python/releases/tag/v0.21.1)- [OpenAI Agents SDK v0.20.0 官方发行说明](https://github.com/openai/openai-agents-python/releases/tag/v0.20.0)- [OpenAI Agents SDK 官方文档](https://openai.github.io/openai-agents-python/)- [PyPI：openai-agents 0.22.0 发布记录](https://pypi.org/project/openai-agents/0.22.0/)