OpenAI Agents SDK 版本策略与破坏性变更迁移指南0.Y.Z 语义化版本与 0.1.00.22.0 变更日志全解读【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonOpenAI Agents SDK当前仓库 pyproject.toml 中版本为0.22.0是一个面向多智能体工作流的轻量级 Python 框架。本文基于仓库官方发布文档docs/release.md 及日文版 docs/ja/release.md系统梳理 SDK 采用的0.Y.Z改良语义化版本规则并逐版本解读 0.1.0 至 0.22.0 的破坏性变更与重要新特性。读完本文你将理解每个版本号的增量含义、哪些变更会影响现有代码、如何规避破坏性变更并掌握若干关键迁移操作如沙箱路径授权、模型拒绝错误处理、OpenAI v3/HTTPX2 迁移等。版本规则0.Y.Z改良语义化版本与标准语义化版本SemVer不同本项目使用0.Y.Z三段式版本号开头的0明确表明 SDK 仍处于快速演进阶段。三个位置各自的增量规则如下。MinorY版本破坏性变更的信号任何未被标记为 beta 的公开接口发生破坏性变更breaking changes时会递增Y。例如从0.0.x升级到0.1.x就可能包含破坏性变更。迁移建议如果你的项目不希望遇到破坏性变更官方建议将依赖固定pin到0.0.x系列版本。注意由于 SDK 采用0.Y.Z结构0.0.x并不等同于“稳定的 1.0”而是表示尚未出现破坏性变更的早期阶段固定到该系列可避免 minor 版本引入的迁移成本。PatchZ版本非破坏性变更以下非破坏性变更通过递增Z发布缺陷修复bug fixes新功能new features私有接口的变更changes to private interfacesbeta 功能的更新updates to beta features也就是说新功能并非只出现在 minor 版本只要不破坏公开接口功能增强走 patch 即可。反过来即使 minor 版本号未变功能也在持续演进升级 patch 版本是低风险的。与仓库源码的对应关系当前仓库 pyproject.toml 声明version 0.22.0requires-python 3.10核心依赖为openai3.0.0,4、pydantic2.12.2,3、mcp1.19.0,3、websockets15.0,17等这些依赖约束正是后续 0.20.0、0.21.0 版本变更在源码层面的落点。运行时版本号通过 src/agents/version.py 从importlib.metadata.version(openai-agents)读取未安装时回退为0.0.0。破坏性变更日志全览0.1.0 → 0.22.0为便于快速检索先给出各版本的变更性质总览版本是否破坏性核心主题0.22.0是失败处理与数据隔离强化输出护栏、ModelBehaviorError、OpenAIProvider 参数冲突0.21.0是HTTP 层强制openaiv3OpenAI HTTP 集成迁移到 HTTPX20.20.0是MCP 依赖MCP Python SDK v2 支持、默认模型改为gpt-5.6-luna0.19.0否Programmatic Tool Calling、tool装饰器别名0.18.0否Realtime 默认模型更新为gpt-realtime-2.10.17.0是沙箱本地源文件实化限制在base_dir需extra_path_grants0.16.0是默认模型默认模型改为gpt-5.4-mini、max_turnsNone0.15.0是错误语义模型拒绝改为显式ModelRefusalError0.14.0否沙箱智能体Sandbox Agentsbeta 功能0.13.0否Realtime 默认模型gpt-realtime-1.5、MCP 资源 API0.12.0 / 0.11.0否功能新增见官方发布说明0.10.0否Responses API WebSocket 传输支持0.9.0是运行时移除 Python 3.9 支持0.8.0是运行时行为同步工具改到工作线程执行、MCP 失败处理可配置0.7.0是行为变更嵌套 handoff 历史改为 opt-in、默认 reasoning.effort 变更0.6.0是行为变更handoff 历史合并为单条 assistant 消息0.5.0否RealtimeRunner SIP 支持、run_sync 内部改版0.4.0是依赖不再支持 openai v1.x0.3.0是API 迁移Realtime API 迁移到 gpt-realtime GA 接口0.2.0是类型Agent→AgentBase类型收窄0.1.0是签名MCPServer.list_tools()新增run_context、agent参数下面按从新到旧的顺序逐版本详细解读。0.22.0失败处理与数据隔离强化当前版本0.22.0 对多个既有 API 的失败处理与数据隔离进行了收紧凡是使用显式客户端构造OpenAIProvider、同时又把organization或project传给 provider 的应用必须删除这些重复参数。主要变更点输出护栏拦截终态工具输出时的可重放性处理当**智能体级输出护栏agent-level output guardrail**阻止了由终态函数工具terminal function tool直接产生的最终输出时仅当校验字段允许安全重建时SDK 才保留可重放replay-valid的调用/输出对原始function_call_output载荷在会话历史、RunState以及流式结果状态中被替换为固定文本Output withheld by an output guardrail.含载荷的当前响应护栏元数据被清除或替换若当前响应包含推理内容或其他不支持的形态SDK 改为丢弃整个当前响应后缀先前已接受的轮次与护栏结果仍然可用。相关指南见 输出护栏。非流式 Responses 调用新增ModelBehaviorError非流式 OpenAI Responses 调用在返回响应的终态为failed或incomplete时现在会抛出ModelBehaviorError与既有流式终态事件处理保持一致。该行为适用于OpenAIResponsesModel以及AnyLLMModel的 Responses 路径。异常体系定义在 src/agents/exceptions.pyModelBehaviorError描述为“模型行为异常如调用不存在的工具或返回畸形 JSON”。相关指南见 异常。OpenAIProvider参数冲突校验扩展OpenAIProvider现在当openai_client与organization或project组合使用时也会抛出UserError此前已存在的与api_key、base_url、websocket_base_url的冲突校验保持不变。从源码可以看到__init__中只要openai_client非空且api_key/base_url/websocket_base_url/organization/project任一非空即抛出UserErrorif openai_client is not None: if any( value is not None for value in (api_key, base_url, websocket_base_url, organization, project) ): raise UserError( Dont provide api_key, base_url, websocket_base_url, organization, or project if you provide openai_client )正确做法是在显式AsyncOpenAI客户端上配置这些值详见 API 密钥与客户端。RunState 检查点独立用量快照每个RunResult.to_state()检查点现在持有独立的用量usage快照。恢复resume的结果从检查点合计值起步并累加自身的模型调用而不会改动源结果或同级检查点。嵌套的Agent.as_tool()恢复仍会将恢复后的用量聚合到处于活动状态的外层运行中。详见 RunState 检查点中的用量。可视化递归展开与 clone 语义澄清智能体可视化现在会递归展开通过handoff(agent)注册的目标智能体所拥有的工具、MCP 服务器及后续 handoff与handoffs列表中直接Agent条目的行为一致见 生成图。Agent.clone()与RealtimeAgent.clone()的 API 指引现在精确描述了既有的浅拷贝shallow-copy行为未被覆盖的列表属性仍指向同一列表对象若克隆体需要独立拥有容器请传入新列表见 克隆/复制智能体。0.21.0强制openaiv3 与 HTTPX2 迁移0.21.0 要求使用openaiv3并将 Agents SDK 的 OpenAI HTTP 集成迁移到HTTPX2。使用默认 OpenAI 客户端的应用无需修改客户端配置但自定义了 OpenAI HTTP 层的应用需要迁移传输层相关代码。必需依赖变为openai3.0.0,4与仓库 pyproject.toml 一致干净的核心安装使用 HTTPX2不再将传统httpx作为直接依赖安装。默认 OpenAI provider、Voice provider、Responses WebSocket 支持、tracing exporter 以及 provider 重试归一化均改用 HTTPX2既有公开配置与运行时行为不变。向AsyncOpenAI传入http_client的应用需要把自定义客户端、传输层、认证、事件钩子、mock 传输、超时值、URL、请求/响应及传输异常处理从httpx迁移到httpx2。若既需要 OpenAI 客户端默认配置又需要自定义 HTTP 选项官方推荐使用 OpenAI Python SDK 的DefaultAsyncHttpx2Client该类型正是 src/agents/models/openai_provider.py 中shared_http_client()所引用的实现。详见 openai v3 自定义 HTTP 客户端。Agents SDK不会自动把任意传统 HTTPX 对象转换为 HTTPX2OpenAI Python SDK 的临时 legacy 客户端兼容路径需要显式安装httpx应仅作为迁移的过渡桥梁。本地 MCP 的 HTTP 自定义继续跟随已安装的 MCP 包MCP Python SDK v1 提供并使用传统httpxv2 使用httpx2普通 MCP 连接无需改动见 MCP Python SDK v1 与 v2。公开的provider 无关测试工具现在可覆盖 Agent 模型、Sandbox 会话、Realtime 会话、Voice pipeline 工作流且不依赖真实 provider 或进程见 测试。0.20.0MCP v2 支持与默认模型更新0.20.0 对自定义本地 MCP HTTP 传输的应用包含潜在的破坏性 MCP 依赖迁移并更新了 SDK 默认模型。默认模型改为gpt-5.6-lunaSDK 默认模型从gpt-5.4-mini改为gpt-5.6-luna默认reasoning.effortnone与verbositylow设置不变。显式指定的智能体模型、运行级模型覆盖以及OPENAI_DEFAULT_MODEL环境变量始终优先于 SDK 默认值。Realtime 输入转写新模型Realtime 输入转写配置现可识别gpt-transcribe、gpt-live-transcribe、gpt-realtime-whisper低延迟的gpt-live-transcribe会话支持在嵌套audio.input.transcription中配置prompt、keywords及多个预期languagesSDK 固定的 OpenAI 客户端版本中delay延迟/精度级别仅gpt-realtime-whisper支持语音轮次提交后的转写或检测语言输出请通过 WebSocket 使用gpt-transcribe显式设置audio.input.turn_detectionNone可禁用自动轮次检测。详见 输入转写设置。本地 MCP 连接支持 MCP Python SDK v2Agents SDK 创建的本地 MCP 连接现在支持MCP Python SDK v2同时通过mcp1.19.0,3保留 v1 兼容性见 pyproject.toml。SDK 自动适配常规 stdio、SSE 与 Streamable HTTP 连接安装 MCP v2 时使用mcp.Client(modeauto)探测最新支持协议对旧服务器回退到传统initialize握手。若依赖解析选中 MCP v2提供自定义httpx.Auth对象或httpx.AsyncClient工厂的应用需把这些值迁移到httpx2或固定mcp2以保留 v1 HTTP 栈。MCPServerStreamableHttp的params[ignore_initialized_notification_failure] True选项仍仅限 v1。详见 MCP Python SDK v1 与 v2。沙箱挂载验证与凭据隔离沙箱挂载验证现在在任何沙箱或挂载辅助副作用发生之前拒绝不安全的凭据放置。可信应用可在不修改存储能力表的前提下针对容器内的精确挂载路径授权“挂载级或宽泛凭据暴露”这些授权仅在运行时生效序列化的沙箱状态本身不会授予凭据权限。在受保护挂载边界处SDK 返回新的脱敏异常若源异常是精确识别的 SDK 沙箱错误、且其获批的结构化字段通过校验则替换后保留该子类型与校验通过的安全字段可识别的MountConfigError还能保留 SDK 生成的安全校验消息其余情况下返回新的通用脱敏错误且不保留 provider 控制或未经批准的消息、命令数据、备注、上下文、原因及源 traceback 状态。详见 挂载与远程存储 与 从会话状态恢复。重试策略与恢复前输入重试策略可检查稳定的重放安全事实并对 provider 标记为不安全的非流式请求显式设置RetryDecision(approve_unsafe_replayTrue)。该批准不会绕过中止、已发出的流式输出或 Programmatic Tool Calling 等独立本地副作用否决见 Runner 管理的重试。可恢复的RunState对象支持在下次模型调用前用add_input()暂存持久用户输入暂存输入在序列化后仍保留、会经过输入护栏并在本地会话与服务器托管会话中产生一次持久 SDK 输入若显式批准了不安全重放输入可能被重新发送给 provider 并重复 provider 侧工作见 恢复前添加输入。运行时可靠性修复0.20.0 还统一了流式与非流式输出护栏的会话持久化、在复制与命名空间化时保留FunctionTool子类、对不支持的 Chat Completions 音频输出显式报错不再静默完成空流。OpenAIResponsesCompactionSession包装器会在取消到达调用方之前尝试并等待压缩前历史恢复。VoicePipeline消费者在干净运行后会收到转写会话关闭失败而较早的轮次失败优先于较晚的关闭失败。RunState往返现在保留本地 shell 输出、已确认的计算机安全检查、默认值工具输出字段以及在遍历字典/列表/元组时遇到的 Pydantic 模型或 dataclass 输出。MCP 转换保留自由形式对象 schema 与图像输出音频、资源等其他原始内容块以合法 JSON 文本序列化。MCPServerManager对重叠生命周期操作做串行化处理并对连接与清理应用有限默认超时。模型重放时输出项在作为输入使用前会移除服务器持有的created_by元数据。0.19.0Programmatic Tool Calling无破坏性变更本 minor 版本不引入破坏性变更递增 minor 是为了反映 OpenAI Responses 的重要新功能领域——Programmatic Tool Calling新增ProgrammaticToolCallingTool让支持的 OpenAI Responses 模型生成 JavaScript 来协调符合 Programmatic Tool Calling 条件的工具支持工具级allowed_callers、来自FunctionTool实例的 structured outputs以及与 Runner 流式、护栏、审批、会话、RunState的集成见 Programmatic Tool Calling。新增公开的agents.decorators模块以及作为既有function_tool装饰器短别名的tool与既有护栏装饰器并存FunctionTool实例现在也支持异步可调用对象。SDK 配置在智能体、运行、模型、会话、沙箱、语音 pipeline 中一致接受类型化配置对象或字典并校验未知配置。强化模型、工具、MCP、Realtime、会话、沙箱、tracing 的错误与诊断日志在保留有用调试上下文的同时避免暴露原始敏感载荷。改进 AnyLLM、LiteLLM、Chat Completions 兼容性模型重试间保留会话历史新增对响应开始前 WebSocket 过载的 provider 重试指引使 opt-in 的 Runner 重试策略在允许时重放失败尝试。通过VercelCloudBucketMountStrategy实现于 src/agents/extensions/sandbox/vercel/mounts.py新增仅 Vercel 沙箱创建时可配置的 S3 挂载挂载会话的桶内容不参与工作区持久化且有意不支持动态挂载变更与会话恢复。0.18.0Realtime 默认模型更新无破坏性变更本 minor 版本仅为 Realtime 智能体默认模型更新默认模型改为gpt-realtime-2.1新 Realtime 配置无需额外设置即可使用最新推荐模型。0.17.0沙箱本地源实化边界收紧含迁移示例本版本将沙箱本地源实化限制在实化的base_dir内除非源路径被Manifest.extra_path_grants覆盖LocalFile.src与LocalDir.src必须保持在base_dir之内。base_dir是清单manifest应用时 SDK 进程的当前工作目录相对本地源从该目录解析绝对本地源必须已经位于该目录内或处于显式授权范围内。这消除了本地工件边界问题但会影响那些有意把base_dir之外的受信主机文件/目录复制进沙箱工作区的应用。迁移方式在清单层使用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(pathstr(TRUSTED_DOCS_ROOT), read_onlyTrue), ), entries{ # No grant is needed for local sources that stay under the SDK process base_dir. fixtures: LocalDir(srcPath(fixtures), descriptionLocal test fixtures.), # This entry reads from the granted host root and copies it into the sandbox workspace. docs: LocalDir(srcTRUSTED_DOCS_ROOT, descriptionTrusted local documents.), # Dir creates a sandbox workspace directory; it does not read from the host filesystem. output: Dir(descriptionGenerated artifacts.), }, )务必把extra_path_grants视为受信应用配置除非应用已预先批准相应主机路径否则不要根据模型输出或其他不可信清单输入构造授权。0.16.0默认模型换代与max_turnsNone本版本把 SDK 默认模型从gpt-4.1改为gpt-5.4-mini影响所有未显式设置模型的智能体与运行。由于新默认是 GPT-5 模型隐式默认模型设置现在包含reasoning.effortnone、verbositylow等 GPT-5 默认值。需要保留旧默认行为的应用请在智能体或运行配置中显式指定模型或设置OPENAI_DEFAULT_MODEL环境变量agent Agent(nameAssistant, modelgpt-4.1)其他变更Runner.run、Runner.run_sync、Runner.run_streamed现在接受max_turnsNone以禁用轮次上限源码中max_turns: int | None DEFAULT_MAX_TURNS见 src/agents/run.py。沙箱工作区水合hydration现在拒绝包含指向归档根之外的符号链接的 tar 归档包括绝对符号链接目标本地、Docker 与 provider 支持的沙箱实现均适用。0.15.0模型拒绝改为显式ModelRefusalError本版本把模型拒绝refusal从“当作空文本输出”或对 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.0Sandbox Agents 测试版无破坏性变更本 minor 版本无破坏性变更但引入了重大新 beta 功能领域——Sandbox Agents以及跨本地、容器化、托管环境的运行时、后端与文档支持新增以SandboxAgent、Manifest、SandboxRunConfig为核心的 beta 沙箱运行时接口让智能体在带文件、目录、Git 仓库、挂载、快照与恢复支持的持久隔离工作区内工作。通过UnixLocalSandboxClient与DockerSandboxClient提供本地与容器化沙箱执行后端并通过 Python 包的可选依赖 extras见 pyproject.toml提供 Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel 的托管 provider 集成。新增沙箱内存支持通过渐进披露、多轮分组、可配置隔离边界以及 S3 支撑工作流在内的持久内存示例让后续运行复用先前运行的经验。新增更全面的工作区与恢复模型本地与合成工作区条目、S3/R2/GCS/Azure Blob Storage/S3 Files 远程存储挂载、可移植快照以及通过RunState、SandboxSessionState或已存快照的恢复流程。examples/sandbox/ 下新增大量沙箱示例与教程覆盖使用技能、handoff、内存的编码任务、provider 特定配置以及代码审查、数据室 QA、网站克隆等端到端工作流。核心运行时与 tracing 栈扩展了沙箱感知的会话准备、能力绑定、状态序列化、统一 tracing、prompt 缓存键默认值以及更安全的敏感 MCP 输出脱敏。0.13.0 与更早的 Responses 时代0.13.0Realtime 默认模型与 MCP 资源 API无破坏性变更包含值得注意的 Realtime 默认更新、新 MCP 能力与运行时稳定性修复默认 WebSocket Realtime 模型改为gpt-realtime-1.5新 Realtime 配置无需额外设置即可使用新模型。MCPServer公开list_resources()、list_resource_templates()、read_resource()MCPServerStreamableHttp公开session_id使使用 MCP Streamable HTTP 传输的会话可在重连或跨无状态 worker 恢复。Chat Completions 集成可通过should_replay_reasoning_content选择重新发送既有推理内容改善 LiteLLM/DeepSeek 等适配器的 provider 特定推理/工具调用连续性。修复多个运行时与会话边界问题SQLAlchemySession并发首次写入、推理剥离后含孤立 assistant 消息 ID 的压缩请求、remove_all_tools()残留 MCP/推理条目、FunctionTool实例批量执行器的竞态。0.12.0 / 0.11.0这两个 minor 版本均无破坏性变更主要功能新增请查阅仓库对应版本发布说明。0.10.0Responses API WebSocket 传输无破坏性变更但为 OpenAI Responses 用户引入重要新功能领域——Responses API 的WebSocket 传输支持为 OpenAI Responses 模型新增 WebSocket 传输支持opt-inHTTP 仍为默认传输。新增responses_websocket_session()辅助函数 /ResponsesWebSocketSession实现于 src/agents/responses_websocket_session.py用于在跨多轮运行中复用共享的 WebSocket 能力 provider 与RunConfig。新增覆盖流式、工具、审批与后续轮次的 WebSocket 流式示例 examples/basic/stream_ws.py。0.9.0 至 0.1.0早期运行时与 API 演进0.9.0移除 Python 3.9Python 3.9 因该主版本三个月前已 EOL生命周期结束而不再受支持请升级到更新运行时。同时Agent#as_tool()返回值的类型提示从Tool收窄为FunctionTool通常不会造成破坏但若代码依赖更宽泛的联合类型则需调整。0.8.0同步工具线程化与 MCP 失败处理可配置本版本有两处运行时行为变更可能需要迁移包装同步Python callable 的FunctionTool实例现在通过asyncio.to_thread(...)在工作线程上执行而不再运行在事件循环线程上。若工具逻辑依赖线程本地状态或线程亲和资源请迁移到异步工具实现或在工具代码中显式处理线程亲和性。本地 MCP 工具失败处理现在可配置默认行为可返回模型可见的错误输出而不再让整个运行失败。若依赖 fail-fast 语义请设置mcp_config{failure_error_function: None}由于服务器级failure_error_function值会覆盖智能体级设置请在每个具有显式处理器的本地 MCP 服务器上设置failure_error_functionNone。0.7.0嵌套 handoff 历史改为 opt-in嵌套 handoff 历史现在是opt-in默认关闭。若依赖 v0.6.x 的默认嵌套行为请显式设置RunConfig(nest_handoff_historyTrue)。gpt-5.1/gpt-5.2的默认reasoning.effort从 SDK 默认配置的low改为none。若提示词或质量/成本画像依赖low请在model_settings中显式设置。0.6.0handoff 历史合并为单条消息默认 handoff 历史不再以独立消息传递用户与 assistant 轮次而是打包为单条 assistant 消息为下游智能体提供简洁、可预测的总结。既有单消息 handoff 转录现在默认以精确字面文本For context, here is the conversation so far between the user and the previous agent:开头后接CONVERSATION HISTORY块为下游智能体提供清晰标注的总结。0.5.0 与 0.4.00.5.0 无可见破坏性变更RealtimeRunner新增 SIP 协议连接处理支持为兼容 Python 3.14 大幅修订Runner#run_sync内部逻辑。0.4.0 起不再支持 openai 包 v1.x请配合本 SDK 使用 openai v2.x后续 0.21.0 进一步要求 v3。0.3.0 至 0.1.00.3.0Realtime API 支持迁移到 gpt-realtime 模型及其 API 接口GA 版本。0.2.0部分原本接收Agent作为参数的位置改为接收AgentBase如 MCP 服务器的list_tools()方法签名。这是纯类型变更仍会收到Agent对象只需把Agent替换为AgentBase修复类型错误。0.1.0MCPServer.list_tools()新增run_context与agent两个参数所有在MCPServer子类中覆写的list_tools()方法都需补充这两个参数。迁移决策速查不想遇到破坏性变更将依赖固定到0.0.x系列升级前先对照本文表格确认目标版本是否标记为破坏性。正在自定义 OpenAI HTTP 层确认是否传入http_client若是则迁移到httpx2或使用DefaultAsyncHttpx2Client0.21.0。正在自定义本地 MCP HTTP 传输确认依赖解析是否选中 MCP v2若是则迁移自定义httpx.Auth/httpx.AsyncClient工厂或固定mcp20.20.0。沙箱需要读取base_dir之外的主机文件在Manifest.extra_path_grants中显式授权0.17.0。依赖旧默认模型行为在智能体或运行上显式设置模型或用OPENAI_DEFAULT_MODEL覆盖0.16.0 / 0.20.0。依赖拒绝即空输出的旧语义改用model_refusal运行错误处理器0.15.0。依赖事件循环线程上的同步工具执行迁移到异步工具或显式处理线程亲和性0.8.0。依赖 v0.6.x 的嵌套 handoff 默认行为显式设置RunConfig(nest_handoff_historyTrue)0.7.0。结合仓库 docs/release.md、pyproject.toml 与 src/agents/exceptions.py 等源码可以在升级前精确核对每个版本号的语义与受影响接口从而制定低风险的升级路径。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenAI Agents SDK 版本策略与破坏性变更迁移指南：0.Y.Z 语义化版本与 0.1.0～0.22.0 变更日志全解读
OpenAI Agents SDK 版本策略与破坏性变更迁移指南0.Y.Z 语义化版本与 0.1.00.22.0 变更日志全解读【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-pythonOpenAI Agents SDK当前仓库 pyproject.toml 中版本为0.22.0是一个面向多智能体工作流的轻量级 Python 框架。本文基于仓库官方发布文档docs/release.md 及日文版 docs/ja/release.md系统梳理 SDK 采用的0.Y.Z改良语义化版本规则并逐版本解读 0.1.0 至 0.22.0 的破坏性变更与重要新特性。读完本文你将理解每个版本号的增量含义、哪些变更会影响现有代码、如何规避破坏性变更并掌握若干关键迁移操作如沙箱路径授权、模型拒绝错误处理、OpenAI v3/HTTPX2 迁移等。版本规则0.Y.Z改良语义化版本与标准语义化版本SemVer不同本项目使用0.Y.Z三段式版本号开头的0明确表明 SDK 仍处于快速演进阶段。三个位置各自的增量规则如下。MinorY版本破坏性变更的信号任何未被标记为 beta 的公开接口发生破坏性变更breaking changes时会递增Y。例如从0.0.x升级到0.1.x就可能包含破坏性变更。迁移建议如果你的项目不希望遇到破坏性变更官方建议将依赖固定pin到0.0.x系列版本。注意由于 SDK 采用0.Y.Z结构0.0.x并不等同于“稳定的 1.0”而是表示尚未出现破坏性变更的早期阶段固定到该系列可避免 minor 版本引入的迁移成本。PatchZ版本非破坏性变更以下非破坏性变更通过递增Z发布缺陷修复bug fixes新功能new features私有接口的变更changes to private interfacesbeta 功能的更新updates to beta features也就是说新功能并非只出现在 minor 版本只要不破坏公开接口功能增强走 patch 即可。反过来即使 minor 版本号未变功能也在持续演进升级 patch 版本是低风险的。与仓库源码的对应关系当前仓库 pyproject.toml 声明version 0.22.0requires-python 3.10核心依赖为openai3.0.0,4、pydantic2.12.2,3、mcp1.19.0,3、websockets15.0,17等这些依赖约束正是后续 0.20.0、0.21.0 版本变更在源码层面的落点。运行时版本号通过 src/agents/version.py 从importlib.metadata.version(openai-agents)读取未安装时回退为0.0.0。破坏性变更日志全览0.1.0 → 0.22.0为便于快速检索先给出各版本的变更性质总览版本是否破坏性核心主题0.22.0是失败处理与数据隔离强化输出护栏、ModelBehaviorError、OpenAIProvider 参数冲突0.21.0是HTTP 层强制openaiv3OpenAI HTTP 集成迁移到 HTTPX20.20.0是MCP 依赖MCP Python SDK v2 支持、默认模型改为gpt-5.6-luna0.19.0否Programmatic Tool Calling、tool装饰器别名0.18.0否Realtime 默认模型更新为gpt-realtime-2.10.17.0是沙箱本地源文件实化限制在base_dir需extra_path_grants0.16.0是默认模型默认模型改为gpt-5.4-mini、max_turnsNone0.15.0是错误语义模型拒绝改为显式ModelRefusalError0.14.0否沙箱智能体Sandbox Agentsbeta 功能0.13.0否Realtime 默认模型gpt-realtime-1.5、MCP 资源 API0.12.0 / 0.11.0否功能新增见官方发布说明0.10.0否Responses API WebSocket 传输支持0.9.0是运行时移除 Python 3.9 支持0.8.0是运行时行为同步工具改到工作线程执行、MCP 失败处理可配置0.7.0是行为变更嵌套 handoff 历史改为 opt-in、默认 reasoning.effort 变更0.6.0是行为变更handoff 历史合并为单条 assistant 消息0.5.0否RealtimeRunner SIP 支持、run_sync 内部改版0.4.0是依赖不再支持 openai v1.x0.3.0是API 迁移Realtime API 迁移到 gpt-realtime GA 接口0.2.0是类型Agent→AgentBase类型收窄0.1.0是签名MCPServer.list_tools()新增run_context、agent参数下面按从新到旧的顺序逐版本详细解读。0.22.0失败处理与数据隔离强化当前版本0.22.0 对多个既有 API 的失败处理与数据隔离进行了收紧凡是使用显式客户端构造OpenAIProvider、同时又把organization或project传给 provider 的应用必须删除这些重复参数。主要变更点输出护栏拦截终态工具输出时的可重放性处理当**智能体级输出护栏agent-level output guardrail**阻止了由终态函数工具terminal function tool直接产生的最终输出时仅当校验字段允许安全重建时SDK 才保留可重放replay-valid的调用/输出对原始function_call_output载荷在会话历史、RunState以及流式结果状态中被替换为固定文本Output withheld by an output guardrail.含载荷的当前响应护栏元数据被清除或替换若当前响应包含推理内容或其他不支持的形态SDK 改为丢弃整个当前响应后缀先前已接受的轮次与护栏结果仍然可用。相关指南见 输出护栏。非流式 Responses 调用新增ModelBehaviorError非流式 OpenAI Responses 调用在返回响应的终态为failed或incomplete时现在会抛出ModelBehaviorError与既有流式终态事件处理保持一致。该行为适用于OpenAIResponsesModel以及AnyLLMModel的 Responses 路径。异常体系定义在 src/agents/exceptions.pyModelBehaviorError描述为“模型行为异常如调用不存在的工具或返回畸形 JSON”。相关指南见 异常。OpenAIProvider参数冲突校验扩展OpenAIProvider现在当openai_client与organization或project组合使用时也会抛出UserError此前已存在的与api_key、base_url、websocket_base_url的冲突校验保持不变。从源码可以看到__init__中只要openai_client非空且api_key/base_url/websocket_base_url/organization/project任一非空即抛出UserErrorif openai_client is not None: if any( value is not None for value in (api_key, base_url, websocket_base_url, organization, project) ): raise UserError( Dont provide api_key, base_url, websocket_base_url, organization, or project if you provide openai_client )正确做法是在显式AsyncOpenAI客户端上配置这些值详见 API 密钥与客户端。RunState 检查点独立用量快照每个RunResult.to_state()检查点现在持有独立的用量usage快照。恢复resume的结果从检查点合计值起步并累加自身的模型调用而不会改动源结果或同级检查点。嵌套的Agent.as_tool()恢复仍会将恢复后的用量聚合到处于活动状态的外层运行中。详见 RunState 检查点中的用量。可视化递归展开与 clone 语义澄清智能体可视化现在会递归展开通过handoff(agent)注册的目标智能体所拥有的工具、MCP 服务器及后续 handoff与handoffs列表中直接Agent条目的行为一致见 生成图。Agent.clone()与RealtimeAgent.clone()的 API 指引现在精确描述了既有的浅拷贝shallow-copy行为未被覆盖的列表属性仍指向同一列表对象若克隆体需要独立拥有容器请传入新列表见 克隆/复制智能体。0.21.0强制openaiv3 与 HTTPX2 迁移0.21.0 要求使用openaiv3并将 Agents SDK 的 OpenAI HTTP 集成迁移到HTTPX2。使用默认 OpenAI 客户端的应用无需修改客户端配置但自定义了 OpenAI HTTP 层的应用需要迁移传输层相关代码。必需依赖变为openai3.0.0,4与仓库 pyproject.toml 一致干净的核心安装使用 HTTPX2不再将传统httpx作为直接依赖安装。默认 OpenAI provider、Voice provider、Responses WebSocket 支持、tracing exporter 以及 provider 重试归一化均改用 HTTPX2既有公开配置与运行时行为不变。向AsyncOpenAI传入http_client的应用需要把自定义客户端、传输层、认证、事件钩子、mock 传输、超时值、URL、请求/响应及传输异常处理从httpx迁移到httpx2。若既需要 OpenAI 客户端默认配置又需要自定义 HTTP 选项官方推荐使用 OpenAI Python SDK 的DefaultAsyncHttpx2Client该类型正是 src/agents/models/openai_provider.py 中shared_http_client()所引用的实现。详见 openai v3 自定义 HTTP 客户端。Agents SDK不会自动把任意传统 HTTPX 对象转换为 HTTPX2OpenAI Python SDK 的临时 legacy 客户端兼容路径需要显式安装httpx应仅作为迁移的过渡桥梁。本地 MCP 的 HTTP 自定义继续跟随已安装的 MCP 包MCP Python SDK v1 提供并使用传统httpxv2 使用httpx2普通 MCP 连接无需改动见 MCP Python SDK v1 与 v2。公开的provider 无关测试工具现在可覆盖 Agent 模型、Sandbox 会话、Realtime 会话、Voice pipeline 工作流且不依赖真实 provider 或进程见 测试。0.20.0MCP v2 支持与默认模型更新0.20.0 对自定义本地 MCP HTTP 传输的应用包含潜在的破坏性 MCP 依赖迁移并更新了 SDK 默认模型。默认模型改为gpt-5.6-lunaSDK 默认模型从gpt-5.4-mini改为gpt-5.6-luna默认reasoning.effortnone与verbositylow设置不变。显式指定的智能体模型、运行级模型覆盖以及OPENAI_DEFAULT_MODEL环境变量始终优先于 SDK 默认值。Realtime 输入转写新模型Realtime 输入转写配置现可识别gpt-transcribe、gpt-live-transcribe、gpt-realtime-whisper低延迟的gpt-live-transcribe会话支持在嵌套audio.input.transcription中配置prompt、keywords及多个预期languagesSDK 固定的 OpenAI 客户端版本中delay延迟/精度级别仅gpt-realtime-whisper支持语音轮次提交后的转写或检测语言输出请通过 WebSocket 使用gpt-transcribe显式设置audio.input.turn_detectionNone可禁用自动轮次检测。详见 输入转写设置。本地 MCP 连接支持 MCP Python SDK v2Agents SDK 创建的本地 MCP 连接现在支持MCP Python SDK v2同时通过mcp1.19.0,3保留 v1 兼容性见 pyproject.toml。SDK 自动适配常规 stdio、SSE 与 Streamable HTTP 连接安装 MCP v2 时使用mcp.Client(modeauto)探测最新支持协议对旧服务器回退到传统initialize握手。若依赖解析选中 MCP v2提供自定义httpx.Auth对象或httpx.AsyncClient工厂的应用需把这些值迁移到httpx2或固定mcp2以保留 v1 HTTP 栈。MCPServerStreamableHttp的params[ignore_initialized_notification_failure] True选项仍仅限 v1。详见 MCP Python SDK v1 与 v2。沙箱挂载验证与凭据隔离沙箱挂载验证现在在任何沙箱或挂载辅助副作用发生之前拒绝不安全的凭据放置。可信应用可在不修改存储能力表的前提下针对容器内的精确挂载路径授权“挂载级或宽泛凭据暴露”这些授权仅在运行时生效序列化的沙箱状态本身不会授予凭据权限。在受保护挂载边界处SDK 返回新的脱敏异常若源异常是精确识别的 SDK 沙箱错误、且其获批的结构化字段通过校验则替换后保留该子类型与校验通过的安全字段可识别的MountConfigError还能保留 SDK 生成的安全校验消息其余情况下返回新的通用脱敏错误且不保留 provider 控制或未经批准的消息、命令数据、备注、上下文、原因及源 traceback 状态。详见 挂载与远程存储 与 从会话状态恢复。重试策略与恢复前输入重试策略可检查稳定的重放安全事实并对 provider 标记为不安全的非流式请求显式设置RetryDecision(approve_unsafe_replayTrue)。该批准不会绕过中止、已发出的流式输出或 Programmatic Tool Calling 等独立本地副作用否决见 Runner 管理的重试。可恢复的RunState对象支持在下次模型调用前用add_input()暂存持久用户输入暂存输入在序列化后仍保留、会经过输入护栏并在本地会话与服务器托管会话中产生一次持久 SDK 输入若显式批准了不安全重放输入可能被重新发送给 provider 并重复 provider 侧工作见 恢复前添加输入。运行时可靠性修复0.20.0 还统一了流式与非流式输出护栏的会话持久化、在复制与命名空间化时保留FunctionTool子类、对不支持的 Chat Completions 音频输出显式报错不再静默完成空流。OpenAIResponsesCompactionSession包装器会在取消到达调用方之前尝试并等待压缩前历史恢复。VoicePipeline消费者在干净运行后会收到转写会话关闭失败而较早的轮次失败优先于较晚的关闭失败。RunState往返现在保留本地 shell 输出、已确认的计算机安全检查、默认值工具输出字段以及在遍历字典/列表/元组时遇到的 Pydantic 模型或 dataclass 输出。MCP 转换保留自由形式对象 schema 与图像输出音频、资源等其他原始内容块以合法 JSON 文本序列化。MCPServerManager对重叠生命周期操作做串行化处理并对连接与清理应用有限默认超时。模型重放时输出项在作为输入使用前会移除服务器持有的created_by元数据。0.19.0Programmatic Tool Calling无破坏性变更本 minor 版本不引入破坏性变更递增 minor 是为了反映 OpenAI Responses 的重要新功能领域——Programmatic Tool Calling新增ProgrammaticToolCallingTool让支持的 OpenAI Responses 模型生成 JavaScript 来协调符合 Programmatic Tool Calling 条件的工具支持工具级allowed_callers、来自FunctionTool实例的 structured outputs以及与 Runner 流式、护栏、审批、会话、RunState的集成见 Programmatic Tool Calling。新增公开的agents.decorators模块以及作为既有function_tool装饰器短别名的tool与既有护栏装饰器并存FunctionTool实例现在也支持异步可调用对象。SDK 配置在智能体、运行、模型、会话、沙箱、语音 pipeline 中一致接受类型化配置对象或字典并校验未知配置。强化模型、工具、MCP、Realtime、会话、沙箱、tracing 的错误与诊断日志在保留有用调试上下文的同时避免暴露原始敏感载荷。改进 AnyLLM、LiteLLM、Chat Completions 兼容性模型重试间保留会话历史新增对响应开始前 WebSocket 过载的 provider 重试指引使 opt-in 的 Runner 重试策略在允许时重放失败尝试。通过VercelCloudBucketMountStrategy实现于 src/agents/extensions/sandbox/vercel/mounts.py新增仅 Vercel 沙箱创建时可配置的 S3 挂载挂载会话的桶内容不参与工作区持久化且有意不支持动态挂载变更与会话恢复。0.18.0Realtime 默认模型更新无破坏性变更本 minor 版本仅为 Realtime 智能体默认模型更新默认模型改为gpt-realtime-2.1新 Realtime 配置无需额外设置即可使用最新推荐模型。0.17.0沙箱本地源实化边界收紧含迁移示例本版本将沙箱本地源实化限制在实化的base_dir内除非源路径被Manifest.extra_path_grants覆盖LocalFile.src与LocalDir.src必须保持在base_dir之内。base_dir是清单manifest应用时 SDK 进程的当前工作目录相对本地源从该目录解析绝对本地源必须已经位于该目录内或处于显式授权范围内。这消除了本地工件边界问题但会影响那些有意把base_dir之外的受信主机文件/目录复制进沙箱工作区的应用。迁移方式在清单层使用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(pathstr(TRUSTED_DOCS_ROOT), read_onlyTrue), ), entries{ # No grant is needed for local sources that stay under the SDK process base_dir. fixtures: LocalDir(srcPath(fixtures), descriptionLocal test fixtures.), # This entry reads from the granted host root and copies it into the sandbox workspace. docs: LocalDir(srcTRUSTED_DOCS_ROOT, descriptionTrusted local documents.), # Dir creates a sandbox workspace directory; it does not read from the host filesystem. output: Dir(descriptionGenerated artifacts.), }, )务必把extra_path_grants视为受信应用配置除非应用已预先批准相应主机路径否则不要根据模型输出或其他不可信清单输入构造授权。0.16.0默认模型换代与max_turnsNone本版本把 SDK 默认模型从gpt-4.1改为gpt-5.4-mini影响所有未显式设置模型的智能体与运行。由于新默认是 GPT-5 模型隐式默认模型设置现在包含reasoning.effortnone、verbositylow等 GPT-5 默认值。需要保留旧默认行为的应用请在智能体或运行配置中显式指定模型或设置OPENAI_DEFAULT_MODEL环境变量agent Agent(nameAssistant, modelgpt-4.1)其他变更Runner.run、Runner.run_sync、Runner.run_streamed现在接受max_turnsNone以禁用轮次上限源码中max_turns: int | None DEFAULT_MAX_TURNS见 src/agents/run.py。沙箱工作区水合hydration现在拒绝包含指向归档根之外的符号链接的 tar 归档包括绝对符号链接目标本地、Docker 与 provider 支持的沙箱实现均适用。0.15.0模型拒绝改为显式ModelRefusalError本版本把模型拒绝refusal从“当作空文本输出”或对 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.0Sandbox Agents 测试版无破坏性变更本 minor 版本无破坏性变更但引入了重大新 beta 功能领域——Sandbox Agents以及跨本地、容器化、托管环境的运行时、后端与文档支持新增以SandboxAgent、Manifest、SandboxRunConfig为核心的 beta 沙箱运行时接口让智能体在带文件、目录、Git 仓库、挂载、快照与恢复支持的持久隔离工作区内工作。通过UnixLocalSandboxClient与DockerSandboxClient提供本地与容器化沙箱执行后端并通过 Python 包的可选依赖 extras见 pyproject.toml提供 Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel 的托管 provider 集成。新增沙箱内存支持通过渐进披露、多轮分组、可配置隔离边界以及 S3 支撑工作流在内的持久内存示例让后续运行复用先前运行的经验。新增更全面的工作区与恢复模型本地与合成工作区条目、S3/R2/GCS/Azure Blob Storage/S3 Files 远程存储挂载、可移植快照以及通过RunState、SandboxSessionState或已存快照的恢复流程。examples/sandbox/ 下新增大量沙箱示例与教程覆盖使用技能、handoff、内存的编码任务、provider 特定配置以及代码审查、数据室 QA、网站克隆等端到端工作流。核心运行时与 tracing 栈扩展了沙箱感知的会话准备、能力绑定、状态序列化、统一 tracing、prompt 缓存键默认值以及更安全的敏感 MCP 输出脱敏。0.13.0 与更早的 Responses 时代0.13.0Realtime 默认模型与 MCP 资源 API无破坏性变更包含值得注意的 Realtime 默认更新、新 MCP 能力与运行时稳定性修复默认 WebSocket Realtime 模型改为gpt-realtime-1.5新 Realtime 配置无需额外设置即可使用新模型。MCPServer公开list_resources()、list_resource_templates()、read_resource()MCPServerStreamableHttp公开session_id使使用 MCP Streamable HTTP 传输的会话可在重连或跨无状态 worker 恢复。Chat Completions 集成可通过should_replay_reasoning_content选择重新发送既有推理内容改善 LiteLLM/DeepSeek 等适配器的 provider 特定推理/工具调用连续性。修复多个运行时与会话边界问题SQLAlchemySession并发首次写入、推理剥离后含孤立 assistant 消息 ID 的压缩请求、remove_all_tools()残留 MCP/推理条目、FunctionTool实例批量执行器的竞态。0.12.0 / 0.11.0这两个 minor 版本均无破坏性变更主要功能新增请查阅仓库对应版本发布说明。0.10.0Responses API WebSocket 传输无破坏性变更但为 OpenAI Responses 用户引入重要新功能领域——Responses API 的WebSocket 传输支持为 OpenAI Responses 模型新增 WebSocket 传输支持opt-inHTTP 仍为默认传输。新增responses_websocket_session()辅助函数 /ResponsesWebSocketSession实现于 src/agents/responses_websocket_session.py用于在跨多轮运行中复用共享的 WebSocket 能力 provider 与RunConfig。新增覆盖流式、工具、审批与后续轮次的 WebSocket 流式示例 examples/basic/stream_ws.py。0.9.0 至 0.1.0早期运行时与 API 演进0.9.0移除 Python 3.9Python 3.9 因该主版本三个月前已 EOL生命周期结束而不再受支持请升级到更新运行时。同时Agent#as_tool()返回值的类型提示从Tool收窄为FunctionTool通常不会造成破坏但若代码依赖更宽泛的联合类型则需调整。0.8.0同步工具线程化与 MCP 失败处理可配置本版本有两处运行时行为变更可能需要迁移包装同步Python callable 的FunctionTool实例现在通过asyncio.to_thread(...)在工作线程上执行而不再运行在事件循环线程上。若工具逻辑依赖线程本地状态或线程亲和资源请迁移到异步工具实现或在工具代码中显式处理线程亲和性。本地 MCP 工具失败处理现在可配置默认行为可返回模型可见的错误输出而不再让整个运行失败。若依赖 fail-fast 语义请设置mcp_config{failure_error_function: None}由于服务器级failure_error_function值会覆盖智能体级设置请在每个具有显式处理器的本地 MCP 服务器上设置failure_error_functionNone。0.7.0嵌套 handoff 历史改为 opt-in嵌套 handoff 历史现在是opt-in默认关闭。若依赖 v0.6.x 的默认嵌套行为请显式设置RunConfig(nest_handoff_historyTrue)。gpt-5.1/gpt-5.2的默认reasoning.effort从 SDK 默认配置的low改为none。若提示词或质量/成本画像依赖low请在model_settings中显式设置。0.6.0handoff 历史合并为单条消息默认 handoff 历史不再以独立消息传递用户与 assistant 轮次而是打包为单条 assistant 消息为下游智能体提供简洁、可预测的总结。既有单消息 handoff 转录现在默认以精确字面文本For context, here is the conversation so far between the user and the previous agent:开头后接CONVERSATION HISTORY块为下游智能体提供清晰标注的总结。0.5.0 与 0.4.00.5.0 无可见破坏性变更RealtimeRunner新增 SIP 协议连接处理支持为兼容 Python 3.14 大幅修订Runner#run_sync内部逻辑。0.4.0 起不再支持 openai 包 v1.x请配合本 SDK 使用 openai v2.x后续 0.21.0 进一步要求 v3。0.3.0 至 0.1.00.3.0Realtime API 支持迁移到 gpt-realtime 模型及其 API 接口GA 版本。0.2.0部分原本接收Agent作为参数的位置改为接收AgentBase如 MCP 服务器的list_tools()方法签名。这是纯类型变更仍会收到Agent对象只需把Agent替换为AgentBase修复类型错误。0.1.0MCPServer.list_tools()新增run_context与agent两个参数所有在MCPServer子类中覆写的list_tools()方法都需补充这两个参数。迁移决策速查不想遇到破坏性变更将依赖固定到0.0.x系列升级前先对照本文表格确认目标版本是否标记为破坏性。正在自定义 OpenAI HTTP 层确认是否传入http_client若是则迁移到httpx2或使用DefaultAsyncHttpx2Client0.21.0。正在自定义本地 MCP HTTP 传输确认依赖解析是否选中 MCP v2若是则迁移自定义httpx.Auth/httpx.AsyncClient工厂或固定mcp20.20.0。沙箱需要读取base_dir之外的主机文件在Manifest.extra_path_grants中显式授权0.17.0。依赖旧默认模型行为在智能体或运行上显式设置模型或用OPENAI_DEFAULT_MODEL覆盖0.16.0 / 0.20.0。依赖拒绝即空输出的旧语义改用model_refusal运行错误处理器0.15.0。依赖事件循环线程上的同步工具执行迁移到异步工具或显式处理线程亲和性0.8.0。依赖 v0.6.x 的嵌套 handoff 默认行为显式设置RunConfig(nest_handoff_historyTrue)0.7.0。结合仓库 docs/release.md、pyproject.toml 与 src/agents/exceptions.py 等源码可以在升级前精确核对每个版本号的语义与受影响接口从而制定低风险的升级路径。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考