升级 OpenAI Agents SDK Python v0.20.0，最危险的不一定是立刻报错，而是代码还能跑、运行契约却已经变了：隐式默认模型发生变化，自定义 MCP HTTP 扩展跨主版本不再天然兼容，恢复后的审批也必须绑定具体工具调用。

核心判断只有一句：先把运行契约显式化，再升级依赖；先证明旧状态能安全恢复，再放真实流量。

官方 Release 将 v0.20.0 标为 minor release，但明确提醒了两处迁移面：隐式默认模型改为 gpt-5.6-luna；本地 MCP 同时兼容 Python SDK v1 / v2，但自定义 HTTP 认证或 Client Factory 必须使用已安装 MCP 主版本拥有的 HTTP 类型，或者暂时固定 mcp<2。

一、先识别三种“没有报错”的漂移

漂移面	为什么冒烟测试可能看不见	最小过关证据
默认模型	请求仍成功，但质量、延迟和费用基线改变	Trace 中的实际模型 ID 与发布配置一致
MCP 主版本	stdio 可能正常，自定义 HTTP 认证只在特定 Transport 失败	v1 / v2 与自定义 Client Factory 组合回归通过
恢复审批	正常新 Run 没问题，暂停、重启、恢复后才暴露身份错配	原调用可恢复，参数变化后必须重新审批

如果只测“Agent 能回答一句话”，三类风险都可能漏掉。升级门禁应按依赖顺序拆成四个阶段。

二、阶段 1：锁定模型，不让默认值参与生产路由

最小动作是让生产配置显式给出模型 ID，并在进程启动时拒绝空值。无论你用 Agent(model=...)、运行级覆盖还是 OPENAI_DEFAULT_MODEL，最终都应在 Trace 中记录解析后的真实模型。

import os
from agents import Agent

model = os.environ["AGENT_MODEL"].strip()
if not model:
    raise RuntimeError("AGENT_MODEL must be explicit")

agent = Agent(name="support", model=model)

过关证据不是“环境变量存在”，而是预发布请求的 Trace、费用估算和质量样本都指向同一个模型 ID。适用边界也要写清：本地探索可以接受 SDK 默认值，生产和可回放评测不应依赖隐式默认。

三、阶段 2：把 MCP 主版本和自定义 HTTP 扩展绑成一项检查

v0.20.0 同时支持 MCP Python SDK v1 / v2 的 stdio、SSE 和 Streamable HTTP，不代表应用里的自定义认证代码可以无修改跨主版本运行。真正的迁移单元是：

MCP 主版本
× Transport
× 自定义认证 / Client Factory
× 关闭与清理路径

最小动作是先读取锁文件里的 MCP 主版本，再检查自定义 HTTP Client 使用的类型来自同一主版本。若迁移窗口不够，官方给出的保守路径是暂时固定 mcp<2，而不是让线上环境自动跨主版本。

过关证据至少包含：stdio、SSE、Streamable HTTP 中实际使用的路径；认证头是否注入；连接异常后是否关闭；进程退出时是否残留任务。没有自定义 HTTP 扩展的项目，不需要为不存在的 Client Factory 写迁移层。

四、阶段 3：恢复状态必须绑定输入、调用身份和审批

这次 Release 增加 RunState.add_input()，允许在恢复模型调用前暂存持久用户输入，并进入 Guardrail、持久化与序列化链路。它同时修复了多项恢复契约：审批绑定具体工具调用、已确认安全检查可序列化、本地 Shell 输出保留，以及 Session 原子变更与失败回滚。

这意味着“恢复成功”不能只看 Run 继续执行。最小动作是为工具名和规范化参数计算稳定身份；恢复时只有身份完全相同的调用才能继承审批。

from hashlib import sha256
import json

def approval_id(tool: str, arguments: dict[str, object]) -> str:
    payload = json.dumps(
        {"tool": tool, "arguments": arguments},
        ensure_ascii=False,
        sort_keys=True,
        separators=(",", ":"),
    )
    return sha256(payload.encode()).hexdigest()[:16]

参数顺序变化不应制造新身份，但工具名、目标资源或任何有效参数变化都必须得到不同结果。这里的哈希只是框架无关演示；生产中还要绑定调用主体、运行版本、过期时间与撤销状态。

五、阶段 4：最后回归挂载、Schema 与失败回滚

v0.20.0 还增加 Sandbox Mount 凭据暴露显式确认，并保持错误脱敏；严格 Schema 会拒绝过深递归和不安全的 $ref 同级字段。这些保护是最后一道门禁，不替代最小挂载、只读权限、秘密隔离和出站网络控制。

最小动作是准备一组明确失败样本：带凭据的挂载配置、越深递归 Schema、带不安全同级字段的 $ref、恢复写入中途失败。过关证据应是“被拒绝且错误不泄露敏感值”，而不是只看成功路径。

六、用 5 项标准库自检先挡住配置错误

本地使用 Python 3.14.4 运行了一个无第三方依赖的最小检查。它验证：模型不能为空；MCP 与自定义 HTTP Client 主版本必须一致；审批身份不受字典键顺序影响，但有效参数变化必须产生新身份。

from dataclasses import dataclass
from hashlib import sha256
import json

@dataclass(frozen=True)
class UpgradeContract:
    model: str
    mcp_major: int
    http_client_major: int

def validate(contract: UpgradeContract) -> None:
    if not contract.model.strip():
        raise ValueError("model must be explicit")
    if contract.mcp_major != contract.http_client_major:
        raise ValueError("MCP and custom HTTP client major versions differ")

def approval_id(tool: str, arguments: dict[str, object]) -> str:
    payload = json.dumps(
        {"tool": tool, "arguments": arguments},
        ensure_ascii=False,
        sort_keys=True,
        separators=(",", ":"),
    )
    return sha256(payload.encode()).hexdigest()[:16]

运行结果：

{'checks': 5, 'approval_id': '4866a324261e7326', 'status': 'passed'}

它只验证框架无关的配置与身份规则，不证明 Agents SDK、MCP Server 或真实 Sandbox 已经完成升级。

七、上线前检查表

• 生产模型 ID 显式配置，Trace 回读值与发布配置一致；
• 记录 Agents SDK 与 MCP Python SDK 的精确版本；
• 按实际 Transport 回归自定义认证、Client Factory 和清理路径；
• 暂停前输入、审批、安全确认和 Shell 输出能在恢复后保持；
• 工具参数变化后旧审批失效，不发生越权复用；
• Session 写入失败能回滚，不留下半份状态；
• 挂载与严格 Schema 的失败样本被拒绝，错误日志保持脱敏；
• 小流量 Trace 同时核对模型、延迟、用量、工具身份和恢复终态。

官方来源：OpenAI Agents SDK Python v0.20.0 Release。

验证边界：本文基于 2026-08-12 对官方 Release 的核验，并运行了框架无关的 Python 标准库自检；未安装或升级 Agents SDK，未连接 MCP Server，未调用真实模型、Sandbox、Session 存储或生产流量。SDK API 的具体接入应以项目锁定版本的官方文档为准。