openai-agents-python 版本发布流程与 Breaking Change 升级指南：从 0.Y.Z 语义版本到逐版本变更日志全解析

openai-agents-python 版本发布流程与 Breaking Change 升级指南：从 0.Y.Z 语义版本到逐版本变更日志全解析

【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python

docs/release.md是 openai-agents-python（OpenAI Agents SDK）官方的发布流程与变更日志文档，它定义了项目特有的0.Y.Z语义化版本规则，并逐版本记录了从 0.22.0 到 0.1.0 的全部破坏性变更（Breaking Changes）。本文将完整继承该文档的版本规则与变更清单，结合仓库源码（pyproject.toml、src/agents/）逐条剖析每个版本背后的实现变化，帮助你在升级 SDK 时准确评估迁移成本、规避破坏性变更，并理解 SDK 的演进脉络。

版本号体系：0.Y.Z 语义化版本

openai-agents-python 采用一种"经过微调的语义化版本"（a slightly modified version of semantic versioning），版本号形如0.Y.Z。开头的0表明该 SDK 仍在快速演进中（still evolving rapidly），API 尚未进入稳定期。理解这一点对依赖管理至关重要：不要因为前缀是0就轻视版本差异，Y位的每次递增都可能意味着你需要修改代码。

当前仓库的版本号定义在 pyproject.toml 中：

[project] name = "openai-agents" version = "0.22.0"

而运行时版本号由 src/agents/version.py 通过importlib.metadata从已安装的发行包读取，未安装时回退为0.0.0：

import importlib.metadata try: __version__ = importlib.metadata.version("openai-agents") except importlib.metadata.PackageNotFoundError: # Fallback if running from source without being installed __version__ = "0.0.0"

也就是说，升级时请始终以 pyproject.toml 中声明的version为准，代码里的回退值只在源码直接运行时出现。

Minor（Y）版本：破坏性变更的信号

项目会在Y位递增时引入对未标记为 beta 的公共接口的破坏性变更。例如从0.0.x升到0.1.x就可能包含 breaking changes。

升级建议：如果你不希望被破坏性变更影响，官方明确推荐在项目中将依赖锁定到0.0.x系列版本（pin to0.0.xversions）。

Patch（Z）版本：非破坏性变更

Z位递增只包含非破坏性变更，官方列出的范围包括：

• Bug 修复（bug fixes）
• 新功能（new features）
• 私有接口的改动（changes to private interfaces）
• beta 功能的更新（updates to beta features）

注意：新增功能并不总是小版本递增，这与很多项目的惯例不同。只有触碰公共接口、且非 beta 的破坏性变化才会推动Y递增。

版本基线速查（以当前仓库为准）

从 pyproject.toml 的依赖声明与 docs/release.md 的变更记录中，可以整理出当前版本的关键基线：

项目	当前仓库中的值	说明
SDK 版本	0.22.0	见 pyproject.toml
Python 支持	>=3.10	0.9.0 起不再支持 Python 3.9
openai 依赖	openai>=3.0.0,<4	0.21.0 起要求 openai v3
HTTP 栈	HTTPX2	0.21.0 起核心不再直接依赖 legacyhttpx
MCP 依赖	mcp>=1.19.0,<3	0.20.0 起兼容 v1/v2 双栈
SDK 默认模型	gpt-5.6-luna	见 src/agents/models/default_models.py
Realtime 默认模型	gpt-realtime-2.1	见 src/agents/realtime/openai_realtime.py

其中默认模型通过环境变量OPENAI_DEFAULT_MODEL覆盖，源码实现如下（src/agents/models/default_models.py）：

def get_default_model() -> str: """ Returns the default model name. """ return os.getenv(OPENAI_DEFAULT_MODEL_ENV_VARIABLE_NAME, "gpt-5.6-luna").lower()

Breaking Change 变更日志详解（0.22.0 → 0.1.0）

以下按时间倒序完整继承官方 changelog，并结合源码给出迁移与原理说明。

0.22.0：收紧迫失败处理与数据隔离

总述：0.22.0 对若干既有 API 收紧了失败处理（failure handling）与数据隔离（data isolation）。如果你用显式 client 构造OpenAIProvider，同时又向 provider 传了organization或project，必须移除这些重复参数。

亮点逐条解析：

1. Agent 级输出护栏拦截工具函数的终态输出：当 agent 级输出护栏（output guardrail）拦截了由终端函数工具直接产生的最终输出时，SDK 只在被校验字段允许安全重建的情况下保留"可回放（replay-valid）的调用/输出对"。原function_call_output载荷会在会话历史、RunState和流式结果状态中被替换为固定文本"Output withheld by an output guardrail."，携带载荷的当前响应护栏元数据会被清除或替换。如果当前响应包含 reasoning 或其他不受支持的形态，SDK 会直接丢弃完整的当前响应后缀；此前已接受的回合与护栏结果仍然保留。详见 输出护栏。

2. 非流式 OpenAI Responses 调用的终态错误：非流式调用现在会在返回的响应处于终态failed或incomplete时抛出ModelBehaviorError，与既有的流式终态事件处理保持一致。这适用于OpenAIResponsesModel以及AnyLLMModel中的 Responses 路径。该异常定义在 src/agents/exceptions.py：

   class ModelBehaviorError(AgentsException): """Exception raised when the model does something unexpected, e.g. calling a tool that doesn't exist, or providing malformed JSON. """

   详见 异常处理。

3. OpenAIProvider的参数冲突校验：OpenAIProvider现在还会在openai_client与organization或project同时出现时抛出UserError；与api_key、base_url、websocket_base_url的既有冲突行为不变。正确做法是把这些值配置在显式AsyncOpenAIclient 上。详见 API keys and clients。

4. RunResult.to_state()独立 usage 快照：每个 checkpoint 现在持有独立的 usage 快照。恢复（resume）的结果以 checkpoint 总计为起点，只累加自己的模型调用，不会修改源结果或兄弟 checkpoint。嵌套的Agent.as_tool()恢复仍会把恢复后的 usage 聚合进外层活跃 run。详见 RunState checkpoints 中的 usage。

5. Agent 可视化递归展开：可视化现在会递归展开通过handoff(agent)注册的目标的 tools、MCP servers 与下游 handoffs，与 agent 的handoffs列表中直接登记的Agent条目行为一致。详见 生成依赖图。

6. clone()浅拷贝语义明确化：Agent.clone()与RealtimeAgent.clone()的文档现在精确说明其既有浅拷贝行为——未被覆盖的列表属性保持为同一个列表对象。需要克隆体独立持有容器时，请传入新列表。其实现基于dataclasses.replace（src/agents/agent.py）：

   def clone(self, **kwargs: Any) -> Agent[TContext]: """Make a copy of the agent, with the given arguments changed. Notes: - Uses `dataclasses.replace`, which performs a **shallow copy** and never copies a list attribute such as `tools`, `handoffs`, `mcp_servers`, `input_guardrails`, or `output_guardrails`. ... """ ... return dataclasses.replace(self, **kwargs)

   例如agent.clone(tools=[*agent.tools, extra_tool])才能让克隆体持有全新的列表。详见 克隆/复制 agents。

0.21.0：升级到 openai v3 与 HTTPX2

总述：0.21.0 要求openaiv3，并把 Agents SDK 的 OpenAI HTTP 集成迁移到 HTTPX2。使用默认 OpenAI client 的应用无需改动 client 配置；但定制了 OpenAI HTTP 层的应用可能需要迁移传输层代码。

亮点逐条解析：

1. 依赖收窄：必需的 OpenAI 依赖变为openai>=3.0.0,<4（与 pyproject.toml 一致）。干净的核心安装使用 HTTPX2，不再把 legacyhttpx作为直接依赖安装。
2. HTTPX2 全面接管：默认 OpenAI provider、Voice provider、Responses WebSocket 支持、tracing exporter、provider 重试归一化均改用 HTTPX2，其公开配置与运行时行为保持不变。
3. 迁移指引：向AsyncOpenAI传http_client=的应用，应把自定义 client、transport、认证、事件钩子、mock transport、超时值、URL、请求/响应及传输异常处理从httpx迁移到httpx2。需要"OpenAI client 默认值 + 自定义 HTTP 选项"时，优先使用 OpenAI Python SDK 的DefaultAsyncHttpx2Client。详见 Custom HTTP clients with openai v3。
4. 不自动转换 legacy HTTPX 对象：SDK 不会把任意 legacy HTTPX 对象转换为 HTTPX2。OpenAI Python SDK 的临时 legacy-client 兼容路径要求显式安装httpx，应仅作为迁移桥梁对待。
5. 本地 MCP HTTP 定制跟随 MCP 包：MCP Python SDK v1 供应并使用 legacyhttpx，MCP Python SDK v2 使用httpx2。普通 MCP 连接无需应用改动。详见 MCP Python SDK v1 and v2。
6. 公共测试工具：provider 中立的公共测试工具现在覆盖 Agent 模型、Sandbox session、Realtime session 与 Voice pipeline 工作流，且不依赖 provider 或进程。详见 测试。

0.20.0：MCP 双栈支持与默认模型更新

总述：0.20.0 对定制本地 MCP HTTP transport 的应用包含一个潜在的破坏性 MCP 依赖迁移；同时更新了 SDK 默认模型。

亮点逐条解析：

1. 默认模型变更：SDK 默认模型从gpt-5.4-mini改为gpt-5.6-luna；默认reasoning.effort="none"与verbosity="low"设置不变。显式 agent 模型、run 级模型覆盖与OPENAI_DEFAULT_MODEL环境变量优先级仍高于 SDK 默认值。
2. Realtime 输入转写设置：新增识别gpt-transcribe、gpt-live-transcribe、gpt-realtime-whisper。低延迟gpt-live-transcribe会话可在嵌套的audio.input.transcription中提供prompt、keywords与多个期望languages（类型定义见 src/agents/realtime/config.py）。本 SDK 锁定的 OpenAI client 版本仅在gpt-realtime-whisper上支持delay延迟/精度档位；提交完成的音频回合后或需要检测语言输出时，应通过 WebSocket 使用gpt-transcribe。显式设置audio.input.turn_detection=None可禁用自动语音检测。详见 输入转写设置。
3. MCP v2 支持：本地 MCP 连接现在支持 MCP Python SDK v2，同时通过mcp>=1.19.0,<3保留 v1 兼容。SDK 自动适配 stdio、SSE 与 Streamable HTTP 连接；装 MCP v2 时用mcp.Client(mode="auto")探测最新协议并在旧服务器上回退到 legacyinitialize握手。若依赖解析选中 MCP v2，提供自定义httpx.Auth或httpx.AsyncClient工厂的应用必须把这些值迁移到httpx2，或固定mcp<2保留 v1 HTTP 栈。MCPServerStreamableHttp的params["ignore_initialized_notification_failure"] = True选项仍是 v1 专有。详见 MCP Python SDK v1 and v2。
4. Sandbox 挂载校验收紧：sandbox 挂载校验现在会在任何 sandbox 或挂载助手副作用之前拒绝不安全的凭据放置。受信应用可针对精确的容器内挂载路径确认挂载级或宽泛的凭据暴露，而不改变存储能力表。这些确认仅运行时有效，序列化的 sandbox 状态本身绝不授予凭据权限。在受保护挂载边界，SDK 返回全新脱敏异常（redacted exception）；若源异常是精确识别的 SDK sandbox 错误且其批准的结构化字段通过校验，替换异常保留该子类型与校验通过的字段；被识别的MountConfigError可保留 SDK 生成的安全校验消息，否则返回全新通用脱敏错误。provider 控制或未批准的 message、命令数据、notes、context、cause、源 traceback 状态一律不保留。详见 挂载与远程存储 与 从会话状态恢复。
5. 重试策略可显式批准不安全重放：重试策略现在可以检查稳定的可重放安全事实，并为 provider 标记为不安全的非流式请求显式设置RetryDecision(approve_unsafe_replay=True)（实现见 src/agents/retry.py）。该批准不会绕过 abort、已发出的流式输出或独立本地副作用否决（如 Programmatic Tool Calling）。详见 Runner 管理的重试。
6. RunState可暂存持久化用户输入：可恢复的RunState现在可以在下次模型调用前通过add_input()暂存持久化用户输入。暂存输入可跨序列化存活、经过输入护栏，并在本地会话与服务端管理的对话中产生一次持久化 SDK 输入记录。显式批准的 unsafe replay 仍会重发输入给 provider 并重复 provider 侧工作。详见 恢复前添加输入。
7. 运行时可靠性修复：对齐了流式与非流式的输出护栏会话持久化；在复制与命名空间化时保留FunctionTool子类；对不支持的 Chat Completions 音频输出显式报错而非静默完成空流；OpenAIResponsesCompactionSession包装器会在取消到达调用方前尝试并等待压缩前历史恢复；VoicePipeline消费者在干净运行后会收到转写会话关闭失败，而更早的回合失败优先于稍后的关闭失败；RunState往返现在保留本地 shell 输出、已确认的计算机安全检查、默认值工具输出字段，以及遍历字典/列表/元组时遇到的 Pydantic 模型或 dataclass 输出；MCP 转换保留自由形式对象 schema 与图像输出，并把音频、资源块等其他原始内容块序列化为合法 JSON 文本；MCPServerManager串行化重叠生命周期操作并应用有限默认超时；模型重放会在把输出项用作输入前移除服务器拥有的created_by元数据。

0.19.0：Programmatic Tool Calling 新功能面

总述：0.19.0不引入破坏性变更，小版本递增反映的是重大新功能面——Programmatic Tool Calling。

亮点逐条解析：

1. ProgrammaticToolCallingTool：新增于 src/agents/tool.py，允许受支持的 OpenAI Responses 模型生成 JavaScript 来编排符合 Programmatic Tool Calling 条件的工具。支持按工具的allowed_callers、来自FunctionTool实例的结构化输出，以及与 Runner 流式、护栏、审批、会话和RunState的集成。详见 Programmatic Tool Calling。
2. @tool装饰器：新增公共agents.decorators模块与@tool（作为既有@function_tool的短别名），同时保留既有护栏装饰器。FunctionTool实例现在还支持异步可调用对象。
3. 配置统一：SDK 配置现在跨 agents、runs、models、sessions、sandboxes 和 voice pipelines 一致地接受类型化设置对象或字典，并对未知设置做校验。
4. 日志加固：跨 models、tools、MCP、Realtime、sessions、sandboxes 和 tracing 加固错误与诊断日志，避免暴露原始敏感载荷，同时保留有用的调试上下文。
5. 兼容性改进：改善 AnyLLM、LiteLLM、Chat Completions 兼容性；模型重试时保留会话历史；为响应开始前的 WebSocket 过载补充 provider 重试指引，使可选的 Runner 重试策略在允许时重放失败尝试。
6. S3 挂载：新增仅可在创建 Vercel sandbox 时配置的 S3 挂载（VercelCloudBucketMountStrategy）。挂载会话从工作区持久化中排除桶内容，且不支持动态挂载变更或会话恢复。

0.18.0：Realtime 默认模型更新

总述：0.18.0不引入破坏性变更，小版本递增仅因 Realtime agents 默认模型更新。

亮点：Realtime agents 现在默认使用gpt-realtime-2.1，新 Realtime 环境无需额外配置即可使用最新推荐模型。源码中的默认值与模型名白名单见 src/agents/realtime/openai_realtime.py 与 src/agents/realtime/config.py。

0.17.0：Sandbox 本地物化边界收紧

总述：0.17.0 中，sandbox 本地源物化把LocalFile.src与LocalDir.src限制在物化base_dir内，除非源路径被Manifest.extra_path_grants覆盖。base_dir是应用 manifest 时 SDK 进程的当前工作目录；相对本地源从该目录解析，绝对本地源必须已位于其内或处于显式授权下。这关闭了一个本地工件边界问题，但可能影响从该 base 目录之外故意拷贝受信主机文件/目录到 sandbox 工作区的应用。

迁移方式：在 manifest 层用SandboxPathGrant授权受信主机根目录，sandbox 只需读取时建议只读：

from pathlib import Path from agents.sandbox import Manifest, SandboxPathGrant from agents.sandbox.entries import Dir, LocalDir # This is an absolute host path outside the SDK process base_dir. TRUSTED_DOCS_ROOT = Path("/opt/my-app/docs") manifest = Manifest( extra_path_grants=( # This host root is outside the SDK process base_dir, so the manifest must grant it. SandboxPathGrant(path=str(TRUSTED_DOCS_ROOT), read_only=True), ), entries={ # No grant is needed for local sources that stay under the SDK process base_dir. "fixtures": LocalDir(src=Path("fixtures"), description="Local test fixtures."), # This entry reads from the granted host root and copies it into the sandbox workspace. "docs": LocalDir(src=TRUSTED_DOCS_ROOT, description="Trusted local documents."), # Dir creates a sandbox workspace directory; it does not read from the host filesystem. "output": Dir(description="Generated artifacts."), }, )

安全提示：请把extra_path_grants视为受信应用配置。除非应用已批准这些主机路径，否则不要用模型输出或其他不可信的 manifest 输入填充授权项。

0.16.0：默认模型切换与max_turns=None

总述：0.16.0 中 SDK 默认模型从gpt-4.1改为gpt-5.4-mini。由于新默认是 GPT-5 模型，隐式默认模型设置现在包含 GPT-5 默认值，如reasoning.effort="none"与verbosity="low"（对应 src/agents/models/default_models.py 的_GPT_5_NONE_DEFAULT_MODEL_SETTINGS）。

恢复旧行为：在 agent 或 run config 上显式设置模型，或设置OPENAI_DEFAULT_MODEL环境变量：

agent = Agent(name="Assistant", model="gpt-4.1")

亮点逐条解析：

1. Runner.run、Runner.run_sync、Runner.run_streamed现在接受max_turns=None以禁用回合数上限。
2. Sandbox 工作区水合现在拒绝 tar 归档中指向归档根之外（含绝对符号链接目标）的符号链接，覆盖本地、Docker 与 provider 支持的 sandbox 实现。

0.15.0：模型拒答显式化

总述：0.15.0 起，模型拒答（model refusal）以ModelRefusalError显式呈现，不再被当作空文本输出，或（结构化输出时）让运行循环重试到MaxTurnsExceeded。异常定义见 src/agents/exceptions.py：

class ModelRefusalError(AgentsException): """Exception raised when the model refuses to produce the requested output.""" refusal: str """The refusal text returned by the model.""" def __init__(self, refusal: str): self.refusal = refusal super().__init__(f"Model refused to produce output: {refusal}")

迁移：此前依赖"仅拒答响应以final_output == ""完成"的代码需要调整。想不抛异常地处理拒答，可提供model_refusalrun 错误处理器：

result = Runner.run_sync( agent, input, error_handlers={"model_refusal": lambda data: data.error.refusal}, )

对结构化输出 agent，处理器可以返回符合 agent 输出 schema 的值，SDK 会像其他 run 错误处理器的最终输出一样校验它。

0.14.0：Sandbox Agents 新 beta 功能面

总述：0.14.0不引入破坏性变更，但新增了重大 beta 功能面：Sandbox Agents，以及跨本地、容器化与托管环境使用它们所需的运行时、后端与文档支持。

亮点逐条解析：

1. 新增以SandboxAgent、Manifest、SandboxRunConfig为核心的 beta sandbox 运行时表面，让 agent 在带文件、目录、Git 仓库、挂载、快照与恢复支持的持久化隔离工作区中工作。
2. 新增本地与容器化开发的 sandbox 执行后端（UnixLocalSandboxClient、DockerSandboxClient），以及通过 Python 包可选依赖 extras 接入的托管 provider 集成（Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel）。
3. 新增 sandbox 记忆支持，未来运行可复用先前运行的经验：渐进式披露、多轮分组、可配置隔离边界，以及含 S3 工作流的持久化记忆示例。
4. 更宽的工作区与恢复模型：本地与合成工作区条目、S3/R2/GCS/Azure Blob Storage/S3 Files 远程存储挂载、可移植快照，以及通过RunState、SandboxSessionState或已存快照的恢复流程。
5. 大量 sandbox 示例与教程位于 examples/sandbox/，覆盖带技能的编码任务、handoffs、记忆、provider 特定配置与端到端工作流（如代码评审、dataroom QA、网站克隆）。
6. 扩展核心运行时与 tracing 栈：sandbox 感知的会话准备、能力绑定、状态序列化、统一 tracing、prompt cache key 默认值与更安全的敏感 MCP 输出脱敏。

0.13.0：Realtime 默认模型更新与 MCP 资源 API

总述：0.13.0不引入破坏性变更，但包含显著的 Realtime 默认更新，以及新的 MCP 能力与运行时稳定性修复。

亮点逐条解析：

1. 默认 WebSocket Realtime 模型改为gpt-realtime-1.5，新 Realtime 环境无需额外配置即可用更新模型。
2. MCPServer现在暴露list_resources()、list_resource_templates()、read_resource()；MCPServerStreamableHttp暴露session_id，使使用 MCP Streamable HTTP transport 的会话可在重连或无状态 worker 间恢复。
3. Chat Completions 集成可通过should_replay_reasoning_content选择重发既有 reasoning 内容，改善 LiteLLM/DeepSeek 等适配器的 provider 特定 reasoning/工具调用连续性。
4. 修复多个运行时与会话边界问题：SQLAlchemySession并发首次写入、reasoning 剥离后孤儿 assistant 消息 ID 的压缩请求、remove_all_tools()遗留 MCP/reasoning 条目、FunctionTool实例批处理执行器中的竞态。

0.12.0 / 0.11.0

这两个版本均不引入破坏性变更，官方指出主要功能新增请查看对应 GitHub Release 页面（仓库内未重复罗列细节）。

0.10.0：Responses API WebSocket 传输

总述：0.10.0不引入破坏性变更，但为 OpenAI Responses 用户新增了重大功能面：Responses API 的 WebSocket 传输支持。

亮点逐条解析：

1. 为 OpenAI Responses 模型新增 WebSocket 传输支持（opt-in；HTTP 仍是默认传输）。
2. 新增responses_websocket_session()辅助函数 /ResponsesWebSocketSession，用于跨多轮运行复用共享的 WebSocket 能力 provider 与RunConfig。
3. 新增 WebSocket 流式示例 examples/basic/stream_ws.py，覆盖流式、工具、审批与后续回合。

0.9.0：放弃 Python 3.9

总述：0.9.0 起不再支持 Python 3.9（该主版本三个月前已 EOL），请升级到更新的运行时。

此外，Agent#as_tool()的返回值类型提示从Tool收窄为FunctionTool。这通常不会造成破坏，但如果代码依赖更宽泛的联合类型，可能需要做相应调整。

0.8.0：两个运行时行为变化

总述：0.8.0 有两个可能需要迁移的运行时行为变化：

1. 同步工具移至工作线程执行：包装同步Python 可调用对象的FunctionTool实例现在通过asyncio.to_thread(...)在工作线程执行，而不是在事件循环线程上运行。如果工具逻辑依赖线程局部状态或线程亲和资源，请迁移到异步工具实现，或在工具代码中显式处理线程亲和性。
2. 本地 MCP 工具失败处理可配置：默认行为现在可返回模型可见的错误输出，而不是使整个 run 失败。如果依赖 fail-fast 语义，请设置mcp_config={"failure_error_function": None}。server 级failure_error_function会覆盖 agent 级设置，因此需要在每个有显式处理器的本地 MCP server 上设置failure_error_function=None。

0.7.0：嵌套 handoff 历史改为 opt-in

总述：0.7.0 有若干会影响既有应用的行为变化：

1. 嵌套 handoff 历史现在默认为 opt-in（默认关闭）。如果你依赖 v0.6.x 的默认嵌套行为，请显式设置RunConfig(nest_handoff_history=True)。
2. gpt-5.1/gpt-5.2的默认reasoning.effort从 SDK 默认配置的"low"改为"none"（对应源码 src/agents/models/default_models.py 中的模式映射）。如果提示词或质量/成本画像依赖"low"，请在model_settings中显式设置。

0.6.0：handoff 历史打包为单条消息

总述：0.6.0 中默认 handoff 历史现在打包进单条 assistant 消息，而不是把 user 与 assistant 回合作为独立消息传递，为下游 agent 提供简洁、可预测的摘要。

• 既有的单消息 handoff 转录现在默认以精确字面文本For context, here is the conversation so far between the user and the previous agent:开头，后接<CONVERSATION HISTORY>块，使下游 agent 获得清晰标注的摘要。

0.5.0：SIP 支持与 run_sync 内部重构

总述：0.5.0 没有可见的破坏性变更，但包含新功能与若干重大内部更新：

• RealtimeRunner新增对 SIP 协议连接 的支持。
• 为 Python 3.14 兼容性显著重构了Runner#run_sync的内部逻辑。

0.4.0：openai v1.x 不再支持

总述：0.4.0 起不再支持openai包 v1.x，请与本 SDK 一起使用 openai v2.x。（注意：此后的 0.21.0 又将基线推进到 openai v3。）

0.3.0：Realtime 迁移至 gpt-realtime GA

总述：0.3.0 中 Realtime API 支持迁移到 gpt-realtime 模型及其 API 接口（GA 版本）。

0.2.0：Agent参数类型改为AgentBase

总述：0.2.0 中若干原本接收Agent作为参数的位置改为接收AgentBase（例如 MCP server 的list_tools()方法签名）。这纯粹是类型层面的变化，运行时仍会收到Agent对象。更新方式：把类型错误中的Agent替换为AgentBase即可。

0.1.0：MCPServer.list_tools()新增参数

总述：0.1.0 中MCPServer.list_tools()新增两个参数：run_context与agent。MCPServer子类中每个被覆盖的list_tools()方法都必须加上这两个参数。

升级实战建议

综合以上逐版本变更记录，可以沉淀出几条实用的升级策略：

1. 先看Y位：0.Y.Z的Y递增是破坏性变更的风向标。升级前先对照本文变更日志，重点检查涉及"显式 client 参数冲突"、"类型收窄"、"线程执行语义"、"默认模型/默认设置变更"、"HTTP/MCP 依赖栈"的条目。
2. 敏感时刻锁定版本：不想承担破坏性变更时，官方建议锁定0.0.x系列；需要跟随新功能时可关注 Patch 版本（Z）的非破坏性更新。
3. 注意默认值漂移：SDK 默认模型（当前gpt-5.6-luna，src/agents/models/default_models.py）与默认reasoning.effort会随版本变化。对质量/成本敏感的生产应用，在 agent 或 run config 上显式指定模型与model_settings，或设置OPENAI_DEFAULT_MODEL环境变量。
4. 关注依赖基线：openai v3 + HTTPX2（0.21.0+）、MCP v1/v2 双栈（0.20.0+）、Python >=3.10（0.9.0+）是当前仓库 pyproject.toml 的实际基线，迁移代码时以这三个约束为准。
5. 异常语义变化优先排查：ModelRefusalError（0.15.0）、终态failed/incomplete抛ModelBehaviorError（0.22.0）、UserError参数冲突（0.22.0）都会改变失败路径的行为，相关异常类型与字段定义集中在 src/agents/exceptions.py，处理异常逻辑时应以该文件为准。

结语

openai-agents-python 的0.Y.Z版本体系让破坏性变更集中在Y位，配合本文梳理的逐版本 changelog，你可以把升级风险从"黑盒试错"变成"对照清单迁移"。本文所引用的源码证据（默认模型、异常类型、重试决策、clone 语义、Realtime 模型白名单等）均可在 src/agents/ 下直接查阅；完整的运行、配置与迁移细节，可继续阅读 docs/ 目录下的对应指南（agents.md、config.md、mcp.md、tools.md、sandbox/guide.md 等）。

【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python