OpenAI Agents SDK 0.20.0 升级避坑指南

dev.to · AI#OpenAI#Agent SDK#版本升级

Editor brief · 编辑速览

该版本隐性默认模型改为 gpt-5.6-luna，升级依赖包即可改变运行时行为；同时跨越 MCP v2 边界，工具审批绑定更严格，升级前需锁定多个关键配置。

文章思维导图

Knowledge map

拖拽缩放

Full translation

完整中文译文

即便应用代码一动不动，SDK 升级也可能改变 Agent 的行为。

OpenAI Agents SDK 0.20.0 将隐式默认模型更换为 gpt-5.6-luna。显式模型、run 级别覆盖以及 OPENAI_DEFAULT_MODEL 仍优先于隐式默认，但一个依赖隐式默认的应用只需升级依赖项，运行时行为就会发生变化。

该版本还跨越了 MCP v2 迁移边界。本地连接支持 MCP Python SDK v1 和 v2，传输协议涵盖 stdio、SSE 和 Streamable HTTP。自定义 HTTP 认证和客户端工厂仍需使用所安装 MCP 主版本对应的 HTTP 类型，或在迁移期间锁定 mcp<2。

还有两项变更值得纳入恢复测试：RunState.add_input() 可以在恢复模型调用之前持久化新输入，而 tool 审批也与更具体的调用标识绑定得更紧密。

这是一篇版本说明解读，而非本地复现。升级之前，请锁定以下各项：model ID、Agents SDK 版本、MCP 主版本号、传输层、approval call ID，以及一个 interrupt-resume canary 测试用例。