企业官网建设流程全解析

OpenAI Agents SDK（openai-agents-python）版本策略与破坏性变更完全指南

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

本文围绕 OpenAI Agents SDK（openai-agents-python）的官方发布流程与变更日志文档（docs/zh/release.md），系统讲解其0.Y.Z版本语义、次版本与补丁版本的递增规则，并逐版本梳理 0.1.0 至 0.22.0 的全部破坏性变更与重大功能演进，同时结合仓库源码（src/agents/、pyproject.toml）给出迁移建议。阅读完本文，你将掌握该 SDK 的版本演进脉络、升级时需要注意的破坏性变更点，以及如何通过版本固定、错误处理程序、显式客户端配置等手段平滑升级到最新版本。

版本策略：采用略作修改的语义化版本控制

OpenAI Agents SDK 采用格式为0.Y.Z的语义化版本控制（SemVer 变体）。开头的0明确表示 SDK 仍在快速演进之中，主版本0不会像常规语义化版本那样在破坏性变更时递增——破坏性变更的载体是次版本Y。

当前仓库发布版本为0.22.0，见 pyproject.toml 中的version = "0.22.0"；运行时代码通过importlib.metadata.version("openai-agents")读取已安装版本，源码未安装时回退为0.0.0（见 src/agents/version.py）。

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

对于任何未标记为 beta的公共接口发生的破坏性变更，SDK 都会递增次版本Y。例如，从0.0.x升级到0.1.x时可能包含破坏性变更。

迁移建议：如果你不希望引入破坏性变更，建议在项目中固定使用0.0.x版本（在实际操作中，可依据你的依赖管理工具将版本精确锁定到当前使用的0.Y.Z组合，例如openai-agents==0.22.0）。

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

对于非破坏性变更，SDK 会递增Z，包括：

• 错误修复（Bug fixes）
• 新功能（New features）
• 私有接口变更（Changes to private interfaces）
• beta 功能更新（Updates to beta features）

换句话说：补丁版本始终安全，次版本则需谨慎评估；而版本号中的0前缀意味着即使按"次版本"递增，也不能把0.x的稳定性等同于成熟的1.x语义化版本。

破坏性变更日志详解（0.1.0 → 0.22.0）

以下按时间倒序整理官方变更日志（中文翻译以 docs/zh/release.md 为准，英文原文见 docs/release.md），并在关键条目后补充源码级佐证与迁移指引。

0.22.0：失败处理与数据隔离强化

版本 0.22.0 加强了多个现有 API 的失败处理和数据隔离。使用显式客户端构造OpenAIProvider，同时还向提供商传递organization或project的应用程序，必须移除这些重复参数。要点如下：

• 输出安全防护措施与终止函数工具：当智能体级输出安全防护措施阻止由终止函数工具直接生成的最终输出时，仅当经过验证的字段允许安全重建时，SDK 才会保留可用于重放的调用/输出对。原始function_call_output载荷会在会话历史记录、RunState和流式结果状态中替换为固定文本"Output withheld by an output guardrail."，而包含载荷的当前响应安全防护措施元数据会被清除或替换。如果当前响应包含推理内容或其他不受支持的结构，SDK 会改为丢弃完整的当前响应后缀。此前已接受的轮次和安全防护措施结果仍然可用。参见输出安全防护措施。

• 非流式调用终止状态报错：对于非流式 OpenAI Responses 调用，当返回响应的终止状态为failed或incomplete时，现在会引发ModelBehaviorError，与现有的流式终止事件处理方式一致。这适用于OpenAIResponsesModel以及AnyLLMModel中的 Responses 路径。ModelBehaviorError定义于 src/agents/exceptions.py，其 docstring 为"模型做出意外行为时（例如调用不存在的工具、返回畸形 JSON）抛出的异常"。参见异常。

• OpenAIProvider参数冲突检查扩展：当openai_client与organization或project结合使用时，OpenAIProvider现在也会引发UserError。与api_key、base_url和websocket_base_url的现有冲突保持不变。请改为在显式AsyncOpenAI客户端上配置这些值。源码中的冲突检查实现于 src/agents/models/openai_provider.py：只要openai_client非空且api_key/base_url/websocket_base_url/organization/project任一被传入，即抛出UserError（"Don't provide api_key, base_url, websocket_base_url, organization, or project if you provide openai_client"）。参见 API 密钥和客户端。

• RunState检查点独立用量快照：每个RunResult.to_state()检查点现在都拥有独立的用量快照。恢复后的结果以检查点总量为起点，并累加自身的模型调用，而不会修改源结果或同级检查点。嵌套的Agent.as_tool()恢复仍会将恢复后的用量汇总到当前活跃的外层运行中。参见 RunState 检查点中的用量。

• 智能体可视化递归展开：智能体可视化现在会递归展开通过handoff(agent)注册的目标所包含的工具、MCP 服务器和下游任务转移，其行为与智能体handoffs列表中的直接Agent条目一致。参见图形生成。

• clone()浅拷贝语义明确化：Agent.clone()和RealtimeAgent.clone()的 API 指南现在准确说明了其现有的浅拷贝行为：未被覆盖的列表属性仍是相同的列表对象。如果克隆对象必须独立拥有该容器，请传入新列表。参见智能体的克隆/复制。

0.21.0：迁移到openaiv3 与 HTTPX2

版本 0.21.0 要求使用openaiv3，并将 Agents SDK 的 OpenAI HTTP 集成迁移到 HTTPX2。使用默认 OpenAI 客户端的应用程序无需更改客户端设置，但自定义 OpenAI HTTP 层的应用程序可能需要迁移面向传输层的代码。要点：

• 现在要求的 OpenAI 依赖项为openai>=3.0.0,<4。全新的核心安装使用 HTTPX2，并且不再将旧版httpx作为直接依赖项安装。这与当前 pyproject.toml 中dependencies声明的"openai>=3.0.0,<4"完全一致。
• 默认 OpenAI 提供商、语音提供商、Responses WebSocket 支持、追踪导出器和提供商重试规范化现在使用 HTTPX2，其现有的 Agents SDK 公共配置和运行时行为保持不变。
• 向AsyncOpenAI传递http_client=的应用程序，应将自定义客户端、传输、身份验证、事件钩子、模拟传输、超时值、URL、请求、响应和传输异常处理从httpx迁移到httpx2。如果应用程序既需要 OpenAI 客户端的默认设置，又需要自定义 HTTP 选项，请优先使用 OpenAI Python SDK 的DefaultAsyncHttpx2Client。参见使用openaiv3 的自定义 HTTP 客户端。
• Agents SDK 不会将任意旧版 HTTPX 对象转换为 HTTPX2。OpenAI Python SDK 的临时旧版客户端兼容路径要求显式安装httpx，应将其视为迁移过渡方案。
• 本地 MCP HTTP 自定义继续遵循已安装的 MCP 软件包：MCP Python SDK v1 提供并使用旧版httpx，而 MCP Python SDK v2 使用httpx2。普通 MCP 连接无需更改应用程序。参见 MCP Python SDK v1 和 v2。
• 公共的提供商中立测试实用工具现在无需依赖提供商或进程，即可覆盖智能体模型、沙箱会话、Realtime 会话和语音管线工作流。参见测试。

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

版本 0.20.0 包含一项可能具有破坏性的 MCP 依赖项迁移（影响自定义本地 MCP HTTP 传输的应用程序），并更新了 SDK 默认模型：

• SDK 默认模型现在是gpt-5.6-luna，而不再是gpt-5.4-mini。默认的reasoning.effort="none"和verbosity="low"设置保持不变。显式指定的智能体模型、运行级模型覆盖以及OPENAI_DEFAULT_MODEL环境变量仍然优先于 SDK 默认值。
• Realtime 输入转录设置现在可识别gpt-transcribe、gpt-live-transcribe和gpt-realtime-whisper。对于低延迟gpt-live-transcribe会话，嵌套的audio.input.transcription设置可以提供prompt、keywords和多个预期的languages。此 SDK 固定使用的 OpenAI 客户端版本仅在搭配gpt-realtime-whisper时支持delay延迟/准确度级别。若要在提交音频轮次后进行转录，或获取检测到的语言输出，请通过 WebSocket 使用gpt-transcribe。显式设置audio.input.turn_detection=None会禁用自动轮次检测。参见输入转录设置。
• 本地 MCP 连接支持 MCP Python SDK v2，同时通过mcp>=1.19.0,<3保持与 v1 的兼容性（当前 pyproject.toml 中声明为"mcp>=1.19.0, <3"）。Agents SDK 会自动适配普通的 stdio、SSE 和 Streamable HTTP 连接。安装 MCP v2 后，这些连接会使用mcp.Client(mode="auto")探测最新支持的协议，并针对旧版服务器回退到传统的initialize握手。如果依赖项解析选择了 MCP v2，则提供自定义httpx.Auth对象或httpx.AsyncClient工厂的应用程序必须将这些值迁移到httpx2，或者固定使用mcp<2以保留 v1 HTTP 栈。MCPServerStreamableHttp的params["ignore_initialized_notification_failure"] = True选项也仍然仅支持 v1。参见 MCP Python SDK v1 和 v2。
• 沙箱挂载验证现在会在产生沙箱或挂载辅助程序的副作用之前，拒绝不安全的凭证放置方式。受信任的应用程序可以针对容器内的确切挂载路径确认挂载范围内或广泛的凭证暴露，而无需更改存储能力表；这些确认仅在运行时有效，序列化的沙箱状态本身绝不会授予凭证权限。在受保护的挂载边界处，SDK 会返回一个新的、已脱敏的异常。可识别的MountConfigError也可以保留由 SDK 生成的安全验证消息；由提供商控制或未经批准的消息、命令数据、注释、上下文、原因和源回溯状态均不会保留。参见挂载与远程存储和从会话状态恢复。
• 重试策略安全批准：重试策略可以检查稳定的重放安全事实，并为提供商标记为不安全的非流式请求显式设置RetryDecision(approve_unsafe_replay=True)。此批准不会绕过中止、已发出的流式输出，也不会绕过诸如程序化工具调用等单独的本地副作用否决。参见由 Runner 管理的重试。
• 恢复前暂存输入：可恢复的RunState对象现在可以在下次模型调用之前使用add_input()暂存持久化用户输入。暂存的输入可在序列化后保留，会经过输入安全防护措施，并在本地会话和服务器管理的对话中产生一次持久化 SDK 输入记录。参见恢复前添加输入。
• 运行时可靠性修复：统一了流式和非流式的输出安全防护措施会话持久化；在复制和命名空间处理期间保留FunctionTool子类；针对不受支持的 Chat Completions 音频输出引发显式错误而不是静默完成空流；OpenAIResponsesCompactionSession包装器会在取消操作到达调用方之前尝试并等待压缩前历史记录恢复；VoicePipeline使用方会在运行正常结束后收到转录会话关闭失败，若某轮次更早失败则其优先级更高；RunState往返转换保留本地 shell 输出、已确认的计算机安全检查、默认值工具输出字段、Pydantic 模型或数据类输出；MCP 转换保留自由形式的对象 schema 和图像输出，将音频块、资源块等其他原始内容块序列化为有效 JSON 文本；MCPServerManager串行化重叠的生命周期操作，并对连接和清理应用有限的默认超时；模型重放会先从输出项中移除服务器拥有的created_by元数据再作为输入使用。

0.19.0：程序化工具调用（非破坏性）

此次次版本发布不会引入破坏性变更，次版本号递增是因为新增了一个重要的 OpenAI Responses 功能领域——程序化工具调用（Programmatic Tool Calling）：

• 新增ProgrammaticToolCallingTool，其 docstring 描述为"一种托管的 Responses 工具，允许生成的 JavaScript 编排其他工具"。支持的 OpenAI Responses 模型可通过它生成 JavaScript 来协调符合程序化工具调用条件的工具。它支持每个工具的allowed_callers、来自FunctionTool实例的 structured outputs，以及与 Runner 流式传输、安全防护措施、审批、会话和RunState的集成。参见程序化工具调用。
• 新增公共agents.decorators模块，并增加@tool，作为现有@function_tool装饰器的较短别名，同时保留现有安全防护措施装饰器。FunctionTool实例现在也支持异步可调用对象。
• SDK 配置现在可在智能体、运行、模型、会话、沙箱和语音管线中一致地接受带类型的设置对象或字典，并会验证未知设置。
• 强化了模型、工具、MCP、Realtime、会话、沙箱和追踪中的错误及诊断日志记录，在保留有用调试上下文的同时避免暴露原始敏感载荷。
• 改进了 AnyLLM、LiteLLM 和 Chat Completions 的兼容性，在模型重试期间保留会话历史记录，并为响应开始前发生的 WebSocket 过载添加了提供商重试指南。
• 通过VercelCloudBucketMountStrategy新增了仅能在创建 Vercel 沙箱时配置的 S3 挂载。已挂载的会话会从工作区持久化中排除存储桶内容，并且有意不支持动态挂载变更或会话恢复。

0.18.0：Realtime 默认模型更新（非破坏性）

此次次版本发布不会引入破坏性变更，次版本号递增仅用于更新 Realtime 智能体的默认模型：Realtime 智能体现在使用gpt-realtime-2.1作为默认模型，新的 Realtime 设置无需额外配置即可使用最新的推荐模型。

0.17.0：沙箱本地源路径边界（破坏性）

在此版本中，除非源路径由Manifest.extra_path_grants覆盖，否则沙箱本地源实体化会将LocalFile.src和LocalDir.src限制在实体化base_dir内。应用清单时，base_dir是 SDK 进程的当前工作目录；相对本地源从该目录解析，而绝对本地源必须已经位于其中或位于显式授权的路径下。此变更修复了本地产物边界问题，但可能影响有意将该基础目录之外的受信任主机文件或目录复制到沙箱工作区的应用程序。

迁移方式：使用SandboxPathGrant在清单级别授予对受信任主机根目录的访问权限；如果沙箱只需读取这些文件，最好授予只读权限：

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视为受信任的应用程序配置。除非应用程序已批准这些主机路径，否则不要根据模型输出或其他不受信任的清单输入填充授权。

0.16.0：默认模型切换为gpt-5.4-mini

在此版本中，SDK 默认模型从gpt-4.1变为gpt-5.4-mini。这影响未显式设置模型的智能体和运行。由于新的默认模型是 GPT-5 模型，隐式默认模型设置现在包括reasoning.effort="none"和verbosity="low"等 GPT-5 默认值。

如果需要保留之前的默认模型行为，请在智能体或运行配置中显式设置模型，或者设置OPENAI_DEFAULT_MODEL环境变量：

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

其他要点：

• Runner.run、Runner.run_sync和Runner.run_streamed现在接受max_turns=None，以禁用轮次限制。
• 对于本地、Docker 和提供商支持的沙箱实现，沙箱工作区填充现在会拒绝包含指向归档根目录之外的符号链接的 tar 归档，其中也包括目标为绝对路径的符号链接。

0.15.0：模型拒绝显式化为ModelRefusalError

在此版本中，模型拒绝现在会显式呈现为ModelRefusalError，而不会被视为空文本输出；对于 structured outputs，也不会再导致运行循环持续重试直至MaxTurnsExceeded。ModelRefusalError定义于 src/agents/exceptions.py，携带refusal字段（模型返回的拒绝文本）。

这影响此前预期仅包含拒绝的模型响应以final_output == ""完成的代码。若要处理拒绝而不引发异常，请提供model_refusal运行错误处理程序：

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

对于使用 structured outputs 的智能体，处理程序可以返回与智能体输出 schema 匹配的值，SDK 会像验证其他运行错误处理程序的最终输出一样验证该值。

0.14.0：沙箱智能体（beta，非破坏性）

此次次版本发布不会引入破坏性变更，但新增了一个重要的 beta 功能领域：沙箱智能体（Sandbox Agents），以及本地、容器化和托管环境中使用它们所需的运行时、后端和文档支持：

• 新增以SandboxAgent、Manifest和SandboxRunConfig为核心的 beta 沙箱运行时接口，使智能体能够在持久化的隔离工作区内处理文件、目录、Git 仓库、挂载和快照，并支持恢复。
• 新增通过UnixLocalSandboxClient和DockerSandboxClient实现的本地及容器化开发沙箱执行后端，并通过 Python 软件包中的可选依赖 extras（见 pyproject.toml 的[project.optional-dependencies]：blaxel、daytona、cloudflare、e2b、modal、runloop、vercel、docker等）为 Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop 和 Vercel 提供托管提供商集成。
• 新增沙箱记忆支持，使未来的运行能够复用以往运行中获得的经验，并提供渐进式披露、多轮分组、可配置的隔离边界，以及包括 S3 支持工作流在内的持久化记忆代码示例。
• 新增更广泛的工作区和恢复模型，包括本地及合成工作区条目、S3/R2/GCS/Azure Blob Storage/S3 Files 的远程存储挂载、可移植快照，以及通过RunState、SandboxSessionState或已保存快照实现的恢复流程。
• 在 examples/sandbox/ 下新增大量沙箱代码示例和教程，涵盖使用技能、任务转移和记忆完成编码任务、提供商专用设置，以及代码审查、数据室问答和网站克隆等端到端工作流。
• 扩展了核心运行时和追踪栈，新增沙箱感知的会话准备、能力绑定、状态序列化、统一追踪、提示词缓存键默认值，以及更安全的敏感 MCP 输出脱敏。

0.13.0：Realtime 默认模型与 MCP 资源能力（非破坏性）

此次次版本发布不会引入破坏性变更，但包含值得注意的 Realtime 默认值更新、新的 MCP 能力以及运行时稳定性修复：

• 默认 websocket Realtime 模型现在是gpt-realtime-1.5。
• MCPServer现在公开list_resources()、list_resource_templates()和read_resource()，而MCPServerStreamableHttp现在公开session_id，因此使用 MCP Streamable HTTP 传输的会话可以在重新连接后或无状态工作进程之间恢复。
• Chat Completions 集成现在可以通过should_replay_reasoning_content选择重新发送现有推理内容，从而改善 LiteLLM/DeepSeek 等适配器中特定于提供商的推理/工具调用连续性。
• 修复了多个运行时和会话边界情况，包括SQLAlchemySession中的并发首次写入、移除推理内容后带有孤立助手消息 ID 的压缩请求、remove_all_tools()遗留 MCP/推理项，以及FunctionTool实例批处理执行器中的竞态条件。

0.12.0 与 0.11.0

这两个次版本发布不会引入破坏性变更，均属于功能增量版本，主要新增功能请查阅对应版本号的官方 GitHub 发布说明（仓库中未收录其正文）。

0.10.0：Responses API WebSocket 传输（非破坏性）

此次次版本发布不会引入破坏性变更，但为 OpenAI Responses 用户新增了一个重要功能领域——Responses API 的 WebSocket 传输支持：

• 新增对 OpenAI Responses 模型的 WebSocket 传输支持（选择启用；HTTP 仍是默认传输）。
• 新增responses_websocket_session()辅助函数 /ResponsesWebSocketSession，用于在多轮运行中复用支持 WebSocket 的共享提供商和RunConfig。
• 新增 WebSocket 流式传输代码示例 examples/basic/stream_ws.py，涵盖流式传输、工具、审批和后续轮次。

0.9.0：Python 3.9 停止支持

在此版本中，不再支持 Python 3.9（该版本已于三个月前终止支持），请升级到较新的运行时版本。当前 pyproject.toml 声明requires-python = ">=3.10"，classifiers 覆盖 Python 3.10～3.14。

此外，Agent#as_tool()方法返回值的类型提示已从Tool收窄为FunctionTool。此变更通常不会造成破坏性问题，但如果代码依赖更宽泛的联合类型，可能需要进行一些调整。

0.8.0：工具执行线程模型与 MCP 失败处理

在此版本中，两项运行时行为变更可能需要迁移：

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

0.7.0：嵌套任务转移历史选择启用

在此版本中，有几项行为变更可能影响现有应用程序：

• 嵌套任务转移历史记录现在需要选择启用（默认禁用）。如果依赖 v0.6.x 的默认嵌套行为，请显式设置RunConfig(nest_handoff_history=True)。
• gpt-5.1/gpt-5.2的默认reasoning.effort已更改为"none"（之前是由 SDK 默认值配置的"low"）。如果提示词或质量/成本配置依赖"low"，请在model_settings中显式设置。

0.6.0：任务转移历史记录封装

在此版本中，默认任务转移历史记录现在会封装为一条助手消息，而不再将用户和助手轮次作为单独消息传递，从而为下游智能体提供简洁且可预测的摘要：

• 现有的单消息任务转移记录现在默认会在<CONVERSATION HISTORY>块之前，以完全一致的字面文本For context, here is the conversation so far between the user and the previous agent:开头，以便下游智能体获得带有清晰标签的摘要。

0.5.0：SIP 支持与 Python 3.14 兼容

此版本不会引入任何可见的破坏性变更，但包含新功能和若干重要的底层更新：

• 在RealtimeRunner中新增对处理 SIP 协议连接的支持（电话/语音接入场景，相关传输说明见 docs/zh/realtime/transport.md）。
• 大幅修订了Runner#run_sync的内部逻辑，以兼容 Python 3.14。

0.4.0：openaiv1 停止支持

在此版本中，不再支持openai软件包 v1.x 版本，请使用 openai v2.x 与此 SDK 搭配使用。到 0.21.0 时依赖进一步升级为openai>=3.0.0,<4（见上文）。

0.3.0：Realtime API 迁移至 GA

在此版本中，Realtime API 支持迁移到 gpt-realtime 模型及其 API 接口（GA 版本）。

0.2.0：Agent到AgentBase的类型收窄

在此版本中，之前有几处接受Agent作为参数的位置改为接受AgentBase。例如，这适用于 MCP 服务器中的list_tools()方法签名。这只是类型方面的变更，你仍会收到Agent对象。若要更新，只需将Agent替换为AgentBase以修复类型错误。

0.1.0：MCPServer.list_tools()新参数

在此版本中，MCPServer.list_tools()新增了两个参数：run_context和agent。你需要将这些参数添加到MCPServer子类中每个被重写的MCPServer.list_tools()方法。

从变更日志看 SDK 演进主线

将 0.1.0 至 0.22.0 的变更串联起来，可以清晰看到 OpenAI Agents SDK 的三条演进主线：

1. 默认模型持续迭代：从gpt-4.1（0.16.0 前）→gpt-5.4-mini（0.16.0）→gpt-5.6-luna（0.20.0）；Realtime 默认模型从gpt-realtime-1.5（0.13.0）→gpt-realtime-2.1（0.18.0）。未显式指定模型的智能体会随版本升级静默更换底层模型，因此对模型行为敏感的团队应显式设置model或OPENAI_DEFAULT_MODEL。

2. 依赖栈持续收紧：Python 3.9 于 0.9.0 停止支持；openai从 v1（0.4.0 弃用）到 v2，再到 v3 + HTTPX2（0.21.0）；MCP Python SDK 从 v1 到 v2 自动适配（0.20.0）。这些变更对自定义 HTTP 层、自定义 MCP 传输的应用程序影响最大，普通使用者通常无需改动。

3. 沙箱与 Realtime 两大 beta 领域快速生长：沙箱智能体于 0.14.0 引入，随后在 0.16.0（tar 符号链接安全）、0.17.0（本地源路径边界与SandboxPathGrant）、0.20.0（挂载凭证验证与脱敏异常）持续加固；Realtime 则在 0.3.0 GA 化后，依次获得 SIP 支持（0.5.0）、WebSocket 传输（0.10.0）、转录设置扩展（0.20.0）。

升级检查清单

结合以上变更日志，升级 SDK 版本时建议按以下清单逐项核对：

1. 确认当前版本：通过pip show openai-agents或importlib.metadata.version("openai-agents")（参见 src/agents/version.py）确认当前版本，规划升级路径。
2. 锁定目标版本：不希望引入破坏性变更时，将openai-agents精确固定到当前使用的0.Y.Z版本。
3. 检查OpenAIProvider构造调用（0.22.0）：使用显式openai_client时，不要再同时传api_key/base_url/websocket_base_url/organization/project，冲突会触发UserError（实现见 src/agents/models/openai_provider.py）。
4. 检查openai与 HTTP 客户端（0.21.0）：确认依赖解析到openai>=3.0.0,<4；自定义http_client=的代码需从httpx迁移到httpx2。
5. 检查默认模型依赖（0.16.0 / 0.20.0）：未显式设置模型的智能体/运行会跟随默认模型切换，必要时显式设置或配置OPENAI_DEFAULT_MODEL。
6. 检查模型拒绝与终止状态处理（0.15.0 / 0.22.0）：依赖final_output == ""表示拒绝的代码需改用model_refusal错误处理程序；非流式 Responses 调用的failed/incomplete终止状态现在会抛出ModelBehaviorError。
7. 检查沙箱清单与挂载（0.17.0 / 0.20.0）：引用base_dir之外的本地源需通过SandboxPathGrant授权；挂载凭证放置需符合新的安全校验。
8. 检查 MCP 依赖与失败处理（0.8.0 / 0.20.0）：自定义 MCP HTTP 传输需适配 MCP v2（或固定mcp<2）；需要快速失败语义时设置mcp_config={"failure_error_function": None}。
9. 检查任务转移与线程模型（0.6.0 / 0.7.0 / 0.8.0）：嵌套任务转移历史需显式RunConfig(nest_handoff_history=True)；同步FunctionTool现在在工作线程执行，注意线程局部状态依赖。

按照上述清单逐项核对，即可在享受新功能的同时，将破坏性变更对现有应用的影响降到最低。

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