尧图网页设计 
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-pythondocs/release.md是 openai-agents-pythonOpenAI 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 rapidlyAPI 尚未进入稳定期。理解这一点对依赖管理至关重要不要因为前缀是0就轻视版本差异Y位的每次递增都可能意味着你需要修改代码。当前仓库的版本号定义在 pyproject.toml 中[project] name openai-agents version 0.22.0而运行时版本号由 src/agents/version.py 通过importlib.metadata从已安装的发行包读取未安装时回退为0.0.0import 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为准代码里的回退值只在源码直接运行时出现。MinorY版本破坏性变更的信号项目会在Y位递增时引入对未标记为 beta 的公共接口的破坏性变更。例如从0.0.x升到0.1.x就可能包含 breaking changes。升级建议如果你不希望被破坏性变更影响官方明确推荐在项目中将依赖锁定到0.0.x系列版本pin to0.0.xversions。PatchZ版本非破坏性变更Z位递增只包含非破坏性变更官方列出的范围包括Bug 修复bug fixes新功能new features私有接口的改动changes to private interfacesbeta 功能的更新updates to beta features注意新增功能并不总是小版本递增这与很多项目的惯例不同。只有触碰公共接口、且非 beta 的破坏性变化才会推动Y递增。版本基线速查以当前仓库为准从 pyproject.toml 的依赖声明与 docs/release.md 的变更记录中可以整理出当前版本的关键基线项目当前仓库中的值说明SDK 版本0.22.0见 pyproject.tomlPython 支持3.100.9.0 起不再支持 Python 3.9openai 依赖openai3.0.0,40.21.0 起要求 openai v3HTTP 栈HTTPX20.21.0 起核心不再直接依赖 legacyhttpxMCP 依赖mcp1.19.0,30.20.0 起兼容 v1/v2 双栈SDK 默认模型gpt-5.6-luna见 src/agents/models/default_models.pyRealtime 默认模型gpt-realtime-2.1见 src/agents/realtime/openai_realtime.py其中默认模型通过环境变量OPENAI_DEFAULT_MODEL覆盖源码实现如下src/agents/models/default_models.pydef 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必须移除这些重复参数。亮点逐条解析Agent 级输出护栏拦截工具函数的终态输出当 agent 级输出护栏output guardrail拦截了由终端函数工具直接产生的最终输出时SDK 只在被校验字段允许安全重建的情况下保留可回放replay-valid的调用/输出对。原function_call_output载荷会在会话历史、RunState和流式结果状态中被替换为固定文本Output withheld by an output guardrail.携带载荷的当前响应护栏元数据会被清除或替换。如果当前响应包含 reasoning 或其他不受支持的形态SDK 会直接丢弃完整的当前响应后缀此前已接受的回合与护栏结果仍然保留。详见 输出护栏。非流式 OpenAI Responses 调用的终态错误非流式调用现在会在返回的响应处于终态failed或incomplete时抛出ModelBehaviorError与既有的流式终态事件处理保持一致。这适用于OpenAIResponsesModel以及AnyLLMModel中的 Responses 路径。该异常定义在 src/agents/exceptions.pyclass ModelBehaviorError(AgentsException): Exception raised when the model does something unexpected, e.g. calling a tool that doesnt exist, or providing malformed JSON. 详见 异常处理。OpenAIProvider的参数冲突校验OpenAIProvider现在还会在openai_client与organization或project同时出现时抛出UserError与api_key、base_url、websocket_base_url的既有冲突行为不变。正确做法是把这些值配置在显式AsyncOpenAIclient 上。详见 API keys and clients。RunResult.to_state()独立 usage 快照每个 checkpoint 现在持有独立的 usage 快照。恢复resume的结果以 checkpoint 总计为起点只累加自己的模型调用不会修改源结果或兄弟 checkpoint。嵌套的Agent.as_tool()恢复仍会把恢复后的 usage 聚合进外层活跃 run。详见 RunState checkpoints 中的 usage。Agent 可视化递归展开可视化现在会递归展开通过handoff(agent)注册的目标的 tools、MCP servers 与下游 handoffs与 agent 的handoffs列表中直接登记的Agent条目行为一致。详见 生成依赖图。clone()浅拷贝语义明确化Agent.clone()与RealtimeAgent.clone()的文档现在精确说明其既有浅拷贝行为——未被覆盖的列表属性保持为同一个列表对象。需要克隆体独立持有容器时请传入新列表。其实现基于dataclasses.replacesrc/agents/agent.pydef 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 层的应用可能需要迁移传输层代码。亮点逐条解析依赖收窄必需的 OpenAI 依赖变为openai3.0.0,4与 pyproject.toml 一致。干净的核心安装使用 HTTPX2不再把 legacyhttpx作为直接依赖安装。HTTPX2 全面接管默认 OpenAI provider、Voice provider、Responses WebSocket 支持、tracing exporter、provider 重试归一化均改用 HTTPX2其公开配置与运行时行为保持不变。迁移指引向AsyncOpenAI传http_client的应用应把自定义 client、transport、认证、事件钩子、mock transport、超时值、URL、请求/响应及传输异常处理从httpx迁移到httpx2。需要OpenAI client 默认值 自定义 HTTP 选项时优先使用 OpenAI Python SDK 的DefaultAsyncHttpx2Client。详见 Custom HTTP clients with openai v3。不自动转换 legacy HTTPX 对象SDK 不会把任意 legacy HTTPX 对象转换为 HTTPX2。OpenAI Python SDK 的临时 legacy-client 兼容路径要求显式安装httpx应仅作为迁移桥梁对待。本地 MCP HTTP 定制跟随 MCP 包MCP Python SDK v1 供应并使用 legacyhttpxMCP Python SDK v2 使用httpx2。普通 MCP 连接无需应用改动。详见 MCP Python SDK v1 and v2。公共测试工具provider 中立的公共测试工具现在覆盖 Agent 模型、Sandbox session、Realtime session 与 Voice pipeline 工作流且不依赖 provider 或进程。详见 测试。0.20.0MCP 双栈支持与默认模型更新总述0.20.0 对定制本地 MCP HTTP transport 的应用包含一个潜在的破坏性 MCP 依赖迁移同时更新了 SDK 默认模型。亮点逐条解析默认模型变更SDK 默认模型从gpt-5.4-mini改为gpt-5.6-luna默认reasoning.effortnone与verbositylow设置不变。显式 agent 模型、run 级模型覆盖与OPENAI_DEFAULT_MODEL环境变量优先级仍高于 SDK 默认值。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_detectionNone可禁用自动语音检测。详见 输入转写设置。MCP v2 支持本地 MCP 连接现在支持 MCP Python SDK v2同时通过mcp1.19.0,3保留 v1 兼容。SDK 自动适配 stdio、SSE 与 Streamable HTTP 连接装 MCP v2 时用mcp.Client(modeauto)探测最新协议并在旧服务器上回退到 legacyinitialize握手。若依赖解析选中 MCP v2提供自定义httpx.Auth或httpx.AsyncClient工厂的应用必须把这些值迁移到httpx2或固定mcp2保留 v1 HTTP 栈。MCPServerStreamableHttp的params[ignore_initialized_notification_failure] True选项仍是 v1 专有。详见 MCP Python SDK v1 and v2。Sandbox 挂载校验收紧sandbox 挂载校验现在会在任何 sandbox 或挂载助手副作用之前拒绝不安全的凭据放置。受信应用可针对精确的容器内挂载路径确认挂载级或宽泛的凭据暴露而不改变存储能力表。这些确认仅运行时有效序列化的 sandbox 状态本身绝不授予凭据权限。在受保护挂载边界SDK 返回全新脱敏异常redacted exception若源异常是精确识别的 SDK sandbox 错误且其批准的结构化字段通过校验替换异常保留该子类型与校验通过的字段被识别的MountConfigError可保留 SDK 生成的安全校验消息否则返回全新通用脱敏错误。provider 控制或未批准的 message、命令数据、notes、context、cause、源 traceback 状态一律不保留。详见 挂载与远程存储 与 从会话状态恢复。重试策略可显式批准不安全重放重试策略现在可以检查稳定的可重放安全事实并为 provider 标记为不安全的非流式请求显式设置RetryDecision(approve_unsafe_replayTrue)实现见 src/agents/retry.py。该批准不会绕过 abort、已发出的流式输出或独立本地副作用否决如 Programmatic Tool Calling。详见 Runner 管理的重试。RunState可暂存持久化用户输入可恢复的RunState现在可以在下次模型调用前通过add_input()暂存持久化用户输入。暂存输入可跨序列化存活、经过输入护栏并在本地会话与服务端管理的对话中产生一次持久化 SDK 输入记录。显式批准的 unsafe replay 仍会重发输入给 provider 并重复 provider 侧工作。详见 恢复前添加输入。运行时可靠性修复对齐了流式与非流式的输出护栏会话持久化在复制与命名空间化时保留FunctionTool子类对不支持的 Chat Completions 音频输出显式报错而非静默完成空流OpenAIResponsesCompactionSession包装器会在取消到达调用方前尝试并等待压缩前历史恢复VoicePipeline消费者在干净运行后会收到转写会话关闭失败而更早的回合失败优先于稍后的关闭失败RunState往返现在保留本地 shell 输出、已确认的计算机安全检查、默认值工具输出字段以及遍历字典/列表/元组时遇到的 Pydantic 模型或 dataclass 输出MCP 转换保留自由形式对象 schema 与图像输出并把音频、资源块等其他原始内容块序列化为合法 JSON 文本MCPServerManager串行化重叠生命周期操作并应用有限默认超时模型重放会在把输出项用作输入前移除服务器拥有的created_by元数据。0.19.0Programmatic Tool Calling 新功能面总述0.19.0不引入破坏性变更小版本递增反映的是重大新功能面——Programmatic Tool Calling。亮点逐条解析ProgrammaticToolCallingTool新增于 src/agents/tool.py允许受支持的 OpenAI Responses 模型生成 JavaScript 来编排符合 Programmatic Tool Calling 条件的工具。支持按工具的allowed_callers、来自FunctionTool实例的结构化输出以及与 Runner 流式、护栏、审批、会话和RunState的集成。详见 Programmatic Tool Calling。tool装饰器新增公共agents.decorators模块与tool作为既有function_tool的短别名同时保留既有护栏装饰器。FunctionTool实例现在还支持异步可调用对象。配置统一SDK 配置现在跨 agents、runs、models、sessions、sandboxes 和 voice pipelines 一致地接受类型化设置对象或字典并对未知设置做校验。日志加固跨 models、tools、MCP、Realtime、sessions、sandboxes 和 tracing 加固错误与诊断日志避免暴露原始敏感载荷同时保留有用的调试上下文。兼容性改进改善 AnyLLM、LiteLLM、Chat Completions 兼容性模型重试时保留会话历史为响应开始前的 WebSocket 过载补充 provider 重试指引使可选的 Runner 重试策略在允许时重放失败尝试。S3 挂载新增仅可在创建 Vercel sandbox 时配置的 S3 挂载VercelCloudBucketMountStrategy。挂载会话从工作区持久化中排除桶内容且不支持动态挂载变更或会话恢复。0.18.0Realtime 默认模型更新总述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.0Sandbox 本地物化边界收紧总述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(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视为受信应用配置。除非应用已批准这些主机路径否则不要用模型输出或其他不可信的 manifest 输入填充授权项。0.16.0默认模型切换与max_turnsNone总述0.16.0 中 SDK 默认模型从gpt-4.1改为gpt-5.4-mini。由于新默认是 GPT-5 模型隐式默认模型设置现在包含 GPT-5 默认值如reasoning.effortnone与verbositylow对应 src/agents/models/default_models.py 的_GPT_5_NONE_DEFAULT_MODEL_SETTINGS。恢复旧行为在 agent 或 run config 上显式设置模型或设置OPENAI_DEFAULT_MODEL环境变量agent Agent(nameAssistant, modelgpt-4.1)亮点逐条解析Runner.run、Runner.run_sync、Runner.run_streamed现在接受max_turnsNone以禁用回合数上限。Sandbox 工作区水合现在拒绝 tar 归档中指向归档根之外含绝对符号链接目标的符号链接覆盖本地、Docker 与 provider 支持的 sandbox 实现。0.15.0模型拒答显式化总述0.15.0 起模型拒答model refusal以ModelRefusalError显式呈现不再被当作空文本输出或结构化输出时让运行循环重试到MaxTurnsExceeded。异常定义见 src/agents/exceptions.pyclass 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__(fModel 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.0Sandbox Agents 新 beta 功能面总述0.14.0不引入破坏性变更但新增了重大 beta 功能面Sandbox Agents以及跨本地、容器化与托管环境使用它们所需的运行时、后端与文档支持。亮点逐条解析新增以SandboxAgent、Manifest、SandboxRunConfig为核心的 beta sandbox 运行时表面让 agent 在带文件、目录、Git 仓库、挂载、快照与恢复支持的持久化隔离工作区中工作。新增本地与容器化开发的 sandbox 执行后端UnixLocalSandboxClient、DockerSandboxClient以及通过 Python 包可选依赖 extras 接入的托管 provider 集成Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel。新增 sandbox 记忆支持未来运行可复用先前运行的经验渐进式披露、多轮分组、可配置隔离边界以及含 S3 工作流的持久化记忆示例。更宽的工作区与恢复模型本地与合成工作区条目、S3/R2/GCS/Azure Blob Storage/S3 Files 远程存储挂载、可移植快照以及通过RunState、SandboxSessionState或已存快照的恢复流程。大量 sandbox 示例与教程位于 examples/sandbox/覆盖带技能的编码任务、handoffs、记忆、provider 特定配置与端到端工作流如代码评审、dataroom QA、网站克隆。扩展核心运行时与 tracing 栈sandbox 感知的会话准备、能力绑定、状态序列化、统一 tracing、prompt cache key 默认值与更安全的敏感 MCP 输出脱敏。0.13.0Realtime 默认模型更新与 MCP 资源 API总述0.13.0不引入破坏性变更但包含显著的 Realtime 默认更新以及新的 MCP 能力与运行时稳定性修复。亮点逐条解析默认 WebSocket Realtime 模型改为gpt-realtime-1.5新 Realtime 环境无需额外配置即可用更新模型。MCPServer现在暴露list_resources()、list_resource_templates()、read_resource()MCPServerStreamableHttp暴露session_id使使用 MCP Streamable HTTP transport 的会话可在重连或无状态 worker 间恢复。Chat Completions 集成可通过should_replay_reasoning_content选择重发既有 reasoning 内容改善 LiteLLM/DeepSeek 等适配器的 provider 特定 reasoning/工具调用连续性。修复多个运行时与会话边界问题SQLAlchemySession并发首次写入、reasoning 剥离后孤儿 assistant 消息 ID 的压缩请求、remove_all_tools()遗留 MCP/reasoning 条目、FunctionTool实例批处理执行器中的竞态。0.12.0 / 0.11.0这两个版本均不引入破坏性变更官方指出主要功能新增请查看对应 GitHub Release 页面仓库内未重复罗列细节。0.10.0Responses API WebSocket 传输总述0.10.0不引入破坏性变更但为 OpenAI Responses 用户新增了重大功能面Responses API 的 WebSocket 传输支持。亮点逐条解析为 OpenAI Responses 模型新增 WebSocket 传输支持opt-inHTTP 仍是默认传输。新增responses_websocket_session()辅助函数 /ResponsesWebSocketSession用于跨多轮运行复用共享的 WebSocket 能力 provider 与RunConfig。新增 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 有两个可能需要迁移的运行时行为变化同步工具移至工作线程执行包装同步Python 可调用对象的FunctionTool实例现在通过asyncio.to_thread(...)在工作线程执行而不是在事件循环线程上运行。如果工具逻辑依赖线程局部状态或线程亲和资源请迁移到异步工具实现或在工具代码中显式处理线程亲和性。本地 MCP 工具失败处理可配置默认行为现在可返回模型可见的错误输出而不是使整个 run 失败。如果依赖 fail-fast 语义请设置mcp_config{failure_error_function: None}。server 级failure_error_function会覆盖 agent 级设置因此需要在每个有显式处理器的本地 MCP server 上设置failure_error_functionNone。0.7.0嵌套 handoff 历史改为 opt-in总述0.7.0 有若干会影响既有应用的行为变化嵌套 handoff 历史现在默认为 opt-in默认关闭。如果你依赖 v0.6.x 的默认嵌套行为请显式设置RunConfig(nest_handoff_historyTrue)。gpt-5.1/gpt-5.2的默认reasoning.effort从 SDK 默认配置的low改为none对应源码 src/agents/models/default_models.py 中的模式映射。如果提示词或质量/成本画像依赖low请在model_settings中显式设置。0.6.0handoff 历史打包为单条消息总述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.0SIP 支持与 run_sync 内部重构总述0.5.0 没有可见的破坏性变更但包含新功能与若干重大内部更新RealtimeRunner新增对 SIP 协议连接 的支持。为 Python 3.14 兼容性显著重构了Runner#run_sync的内部逻辑。0.4.0openai v1.x 不再支持总述0.4.0 起不再支持openai包 v1.x请与本 SDK 一起使用 openai v2.x。注意此后的 0.21.0 又将基线推进到 openai v3。0.3.0Realtime 迁移至 gpt-realtime GA总述0.3.0 中 Realtime API 支持迁移到 gpt-realtime 模型及其 API 接口GA 版本。0.2.0Agent参数类型改为AgentBase总述0.2.0 中若干原本接收Agent作为参数的位置改为接收AgentBase例如 MCP server 的list_tools()方法签名。这纯粹是类型层面的变化运行时仍会收到Agent对象。更新方式把类型错误中的Agent替换为AgentBase即可。0.1.0MCPServer.list_tools()新增参数总述0.1.0 中MCPServer.list_tools()新增两个参数run_context与agent。MCPServer子类中每个被覆盖的list_tools()方法都必须加上这两个参数。升级实战建议综合以上逐版本变更记录可以沉淀出几条实用的升级策略先看Y位0.Y.Z的Y递增是破坏性变更的风向标。升级前先对照本文变更日志重点检查涉及显式 client 参数冲突、类型收窄、线程执行语义、默认模型/默认设置变更、HTTP/MCP 依赖栈的条目。敏感时刻锁定版本不想承担破坏性变更时官方建议锁定0.0.x系列需要跟随新功能时可关注 Patch 版本Z的非破坏性更新。注意默认值漂移SDK 默认模型当前gpt-5.6-lunasrc/agents/models/default_models.py与默认reasoning.effort会随版本变化。对质量/成本敏感的生产应用在 agent 或 run config 上显式指定模型与model_settings或设置OPENAI_DEFAULT_MODEL环境变量。关注依赖基线openai v3 HTTPX20.21.0、MCP v1/v2 双栈0.20.0、Python 3.100.9.0是当前仓库 pyproject.toml 的实际基线迁移代码时以这三个约束为准。异常语义变化优先排查ModelRefusalError0.15.0、终态failed/incomplete抛ModelBehaviorError0.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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-pythondocs/release.md是 openai-agents-pythonOpenAI 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 rapidlyAPI 尚未进入稳定期。理解这一点对依赖管理至关重要不要因为前缀是0就轻视版本差异Y位的每次递增都可能意味着你需要修改代码。当前仓库的版本号定义在 pyproject.toml 中[project] name openai-agents version 0.22.0而运行时版本号由 src/agents/version.py 通过importlib.metadata从已安装的发行包读取未安装时回退为0.0.0import 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为准代码里的回退值只在源码直接运行时出现。MinorY版本破坏性变更的信号项目会在Y位递增时引入对未标记为 beta 的公共接口的破坏性变更。例如从0.0.x升到0.1.x就可能包含 breaking changes。升级建议如果你不希望被破坏性变更影响官方明确推荐在项目中将依赖锁定到0.0.x系列版本pin to0.0.xversions。PatchZ版本非破坏性变更Z位递增只包含非破坏性变更官方列出的范围包括Bug 修复bug fixes新功能new features私有接口的改动changes to private interfacesbeta 功能的更新updates to beta features注意新增功能并不总是小版本递增这与很多项目的惯例不同。只有触碰公共接口、且非 beta 的破坏性变化才会推动Y递增。版本基线速查以当前仓库为准从 pyproject.toml 的依赖声明与 docs/release.md 的变更记录中可以整理出当前版本的关键基线项目当前仓库中的值说明SDK 版本0.22.0见 pyproject.tomlPython 支持3.100.9.0 起不再支持 Python 3.9openai 依赖openai3.0.0,40.21.0 起要求 openai v3HTTP 栈HTTPX20.21.0 起核心不再直接依赖 legacyhttpxMCP 依赖mcp1.19.0,30.20.0 起兼容 v1/v2 双栈SDK 默认模型gpt-5.6-luna见 src/agents/models/default_models.pyRealtime 默认模型gpt-realtime-2.1见 src/agents/realtime/openai_realtime.py其中默认模型通过环境变量OPENAI_DEFAULT_MODEL覆盖源码实现如下src/agents/models/default_models.pydef 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必须移除这些重复参数。亮点逐条解析Agent 级输出护栏拦截工具函数的终态输出当 agent 级输出护栏output guardrail拦截了由终端函数工具直接产生的最终输出时SDK 只在被校验字段允许安全重建的情况下保留可回放replay-valid的调用/输出对。原function_call_output载荷会在会话历史、RunState和流式结果状态中被替换为固定文本Output withheld by an output guardrail.携带载荷的当前响应护栏元数据会被清除或替换。如果当前响应包含 reasoning 或其他不受支持的形态SDK 会直接丢弃完整的当前响应后缀此前已接受的回合与护栏结果仍然保留。详见 输出护栏。非流式 OpenAI Responses 调用的终态错误非流式调用现在会在返回的响应处于终态failed或incomplete时抛出ModelBehaviorError与既有的流式终态事件处理保持一致。这适用于OpenAIResponsesModel以及AnyLLMModel中的 Responses 路径。该异常定义在 src/agents/exceptions.pyclass ModelBehaviorError(AgentsException): Exception raised when the model does something unexpected, e.g. calling a tool that doesnt exist, or providing malformed JSON. 详见 异常处理。OpenAIProvider的参数冲突校验OpenAIProvider现在还会在openai_client与organization或project同时出现时抛出UserError与api_key、base_url、websocket_base_url的既有冲突行为不变。正确做法是把这些值配置在显式AsyncOpenAIclient 上。详见 API keys and clients。RunResult.to_state()独立 usage 快照每个 checkpoint 现在持有独立的 usage 快照。恢复resume的结果以 checkpoint 总计为起点只累加自己的模型调用不会修改源结果或兄弟 checkpoint。嵌套的Agent.as_tool()恢复仍会把恢复后的 usage 聚合进外层活跃 run。详见 RunState checkpoints 中的 usage。Agent 可视化递归展开可视化现在会递归展开通过handoff(agent)注册的目标的 tools、MCP servers 与下游 handoffs与 agent 的handoffs列表中直接登记的Agent条目行为一致。详见 生成依赖图。clone()浅拷贝语义明确化Agent.clone()与RealtimeAgent.clone()的文档现在精确说明其既有浅拷贝行为——未被覆盖的列表属性保持为同一个列表对象。需要克隆体独立持有容器时请传入新列表。其实现基于dataclasses.replacesrc/agents/agent.pydef 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 层的应用可能需要迁移传输层代码。亮点逐条解析依赖收窄必需的 OpenAI 依赖变为openai3.0.0,4与 pyproject.toml 一致。干净的核心安装使用 HTTPX2不再把 legacyhttpx作为直接依赖安装。HTTPX2 全面接管默认 OpenAI provider、Voice provider、Responses WebSocket 支持、tracing exporter、provider 重试归一化均改用 HTTPX2其公开配置与运行时行为保持不变。迁移指引向AsyncOpenAI传http_client的应用应把自定义 client、transport、认证、事件钩子、mock transport、超时值、URL、请求/响应及传输异常处理从httpx迁移到httpx2。需要OpenAI client 默认值 自定义 HTTP 选项时优先使用 OpenAI Python SDK 的DefaultAsyncHttpx2Client。详见 Custom HTTP clients with openai v3。不自动转换 legacy HTTPX 对象SDK 不会把任意 legacy HTTPX 对象转换为 HTTPX2。OpenAI Python SDK 的临时 legacy-client 兼容路径要求显式安装httpx应仅作为迁移桥梁对待。本地 MCP HTTP 定制跟随 MCP 包MCP Python SDK v1 供应并使用 legacyhttpxMCP Python SDK v2 使用httpx2。普通 MCP 连接无需应用改动。详见 MCP Python SDK v1 and v2。公共测试工具provider 中立的公共测试工具现在覆盖 Agent 模型、Sandbox session、Realtime session 与 Voice pipeline 工作流且不依赖 provider 或进程。详见 测试。0.20.0MCP 双栈支持与默认模型更新总述0.20.0 对定制本地 MCP HTTP transport 的应用包含一个潜在的破坏性 MCP 依赖迁移同时更新了 SDK 默认模型。亮点逐条解析默认模型变更SDK 默认模型从gpt-5.4-mini改为gpt-5.6-luna默认reasoning.effortnone与verbositylow设置不变。显式 agent 模型、run 级模型覆盖与OPENAI_DEFAULT_MODEL环境变量优先级仍高于 SDK 默认值。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_detectionNone可禁用自动语音检测。详见 输入转写设置。MCP v2 支持本地 MCP 连接现在支持 MCP Python SDK v2同时通过mcp1.19.0,3保留 v1 兼容。SDK 自动适配 stdio、SSE 与 Streamable HTTP 连接装 MCP v2 时用mcp.Client(modeauto)探测最新协议并在旧服务器上回退到 legacyinitialize握手。若依赖解析选中 MCP v2提供自定义httpx.Auth或httpx.AsyncClient工厂的应用必须把这些值迁移到httpx2或固定mcp2保留 v1 HTTP 栈。MCPServerStreamableHttp的params[ignore_initialized_notification_failure] True选项仍是 v1 专有。详见 MCP Python SDK v1 and v2。Sandbox 挂载校验收紧sandbox 挂载校验现在会在任何 sandbox 或挂载助手副作用之前拒绝不安全的凭据放置。受信应用可针对精确的容器内挂载路径确认挂载级或宽泛的凭据暴露而不改变存储能力表。这些确认仅运行时有效序列化的 sandbox 状态本身绝不授予凭据权限。在受保护挂载边界SDK 返回全新脱敏异常redacted exception若源异常是精确识别的 SDK sandbox 错误且其批准的结构化字段通过校验替换异常保留该子类型与校验通过的字段被识别的MountConfigError可保留 SDK 生成的安全校验消息否则返回全新通用脱敏错误。provider 控制或未批准的 message、命令数据、notes、context、cause、源 traceback 状态一律不保留。详见 挂载与远程存储 与 从会话状态恢复。重试策略可显式批准不安全重放重试策略现在可以检查稳定的可重放安全事实并为 provider 标记为不安全的非流式请求显式设置RetryDecision(approve_unsafe_replayTrue)实现见 src/agents/retry.py。该批准不会绕过 abort、已发出的流式输出或独立本地副作用否决如 Programmatic Tool Calling。详见 Runner 管理的重试。RunState可暂存持久化用户输入可恢复的RunState现在可以在下次模型调用前通过add_input()暂存持久化用户输入。暂存输入可跨序列化存活、经过输入护栏并在本地会话与服务端管理的对话中产生一次持久化 SDK 输入记录。显式批准的 unsafe replay 仍会重发输入给 provider 并重复 provider 侧工作。详见 恢复前添加输入。运行时可靠性修复对齐了流式与非流式的输出护栏会话持久化在复制与命名空间化时保留FunctionTool子类对不支持的 Chat Completions 音频输出显式报错而非静默完成空流OpenAIResponsesCompactionSession包装器会在取消到达调用方前尝试并等待压缩前历史恢复VoicePipeline消费者在干净运行后会收到转写会话关闭失败而更早的回合失败优先于稍后的关闭失败RunState往返现在保留本地 shell 输出、已确认的计算机安全检查、默认值工具输出字段以及遍历字典/列表/元组时遇到的 Pydantic 模型或 dataclass 输出MCP 转换保留自由形式对象 schema 与图像输出并把音频、资源块等其他原始内容块序列化为合法 JSON 文本MCPServerManager串行化重叠生命周期操作并应用有限默认超时模型重放会在把输出项用作输入前移除服务器拥有的created_by元数据。0.19.0Programmatic Tool Calling 新功能面总述0.19.0不引入破坏性变更小版本递增反映的是重大新功能面——Programmatic Tool Calling。亮点逐条解析ProgrammaticToolCallingTool新增于 src/agents/tool.py允许受支持的 OpenAI Responses 模型生成 JavaScript 来编排符合 Programmatic Tool Calling 条件的工具。支持按工具的allowed_callers、来自FunctionTool实例的结构化输出以及与 Runner 流式、护栏、审批、会话和RunState的集成。详见 Programmatic Tool Calling。tool装饰器新增公共agents.decorators模块与tool作为既有function_tool的短别名同时保留既有护栏装饰器。FunctionTool实例现在还支持异步可调用对象。配置统一SDK 配置现在跨 agents、runs、models、sessions、sandboxes 和 voice pipelines 一致地接受类型化设置对象或字典并对未知设置做校验。日志加固跨 models、tools、MCP、Realtime、sessions、sandboxes 和 tracing 加固错误与诊断日志避免暴露原始敏感载荷同时保留有用的调试上下文。兼容性改进改善 AnyLLM、LiteLLM、Chat Completions 兼容性模型重试时保留会话历史为响应开始前的 WebSocket 过载补充 provider 重试指引使可选的 Runner 重试策略在允许时重放失败尝试。S3 挂载新增仅可在创建 Vercel sandbox 时配置的 S3 挂载VercelCloudBucketMountStrategy。挂载会话从工作区持久化中排除桶内容且不支持动态挂载变更或会话恢复。0.18.0Realtime 默认模型更新总述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.0Sandbox 本地物化边界收紧总述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(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视为受信应用配置。除非应用已批准这些主机路径否则不要用模型输出或其他不可信的 manifest 输入填充授权项。0.16.0默认模型切换与max_turnsNone总述0.16.0 中 SDK 默认模型从gpt-4.1改为gpt-5.4-mini。由于新默认是 GPT-5 模型隐式默认模型设置现在包含 GPT-5 默认值如reasoning.effortnone与verbositylow对应 src/agents/models/default_models.py 的_GPT_5_NONE_DEFAULT_MODEL_SETTINGS。恢复旧行为在 agent 或 run config 上显式设置模型或设置OPENAI_DEFAULT_MODEL环境变量agent Agent(nameAssistant, modelgpt-4.1)亮点逐条解析Runner.run、Runner.run_sync、Runner.run_streamed现在接受max_turnsNone以禁用回合数上限。Sandbox 工作区水合现在拒绝 tar 归档中指向归档根之外含绝对符号链接目标的符号链接覆盖本地、Docker 与 provider 支持的 sandbox 实现。0.15.0模型拒答显式化总述0.15.0 起模型拒答model refusal以ModelRefusalError显式呈现不再被当作空文本输出或结构化输出时让运行循环重试到MaxTurnsExceeded。异常定义见 src/agents/exceptions.pyclass 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__(fModel 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.0Sandbox Agents 新 beta 功能面总述0.14.0不引入破坏性变更但新增了重大 beta 功能面Sandbox Agents以及跨本地、容器化与托管环境使用它们所需的运行时、后端与文档支持。亮点逐条解析新增以SandboxAgent、Manifest、SandboxRunConfig为核心的 beta sandbox 运行时表面让 agent 在带文件、目录、Git 仓库、挂载、快照与恢复支持的持久化隔离工作区中工作。新增本地与容器化开发的 sandbox 执行后端UnixLocalSandboxClient、DockerSandboxClient以及通过 Python 包可选依赖 extras 接入的托管 provider 集成Blaxel、Cloudflare、Daytona、E2B、Modal、Runloop、Vercel。新增 sandbox 记忆支持未来运行可复用先前运行的经验渐进式披露、多轮分组、可配置隔离边界以及含 S3 工作流的持久化记忆示例。更宽的工作区与恢复模型本地与合成工作区条目、S3/R2/GCS/Azure Blob Storage/S3 Files 远程存储挂载、可移植快照以及通过RunState、SandboxSessionState或已存快照的恢复流程。大量 sandbox 示例与教程位于 examples/sandbox/覆盖带技能的编码任务、handoffs、记忆、provider 特定配置与端到端工作流如代码评审、dataroom QA、网站克隆。扩展核心运行时与 tracing 栈sandbox 感知的会话准备、能力绑定、状态序列化、统一 tracing、prompt cache key 默认值与更安全的敏感 MCP 输出脱敏。0.13.0Realtime 默认模型更新与 MCP 资源 API总述0.13.0不引入破坏性变更但包含显著的 Realtime 默认更新以及新的 MCP 能力与运行时稳定性修复。亮点逐条解析默认 WebSocket Realtime 模型改为gpt-realtime-1.5新 Realtime 环境无需额外配置即可用更新模型。MCPServer现在暴露list_resources()、list_resource_templates()、read_resource()MCPServerStreamableHttp暴露session_id使使用 MCP Streamable HTTP transport 的会话可在重连或无状态 worker 间恢复。Chat Completions 集成可通过should_replay_reasoning_content选择重发既有 reasoning 内容改善 LiteLLM/DeepSeek 等适配器的 provider 特定 reasoning/工具调用连续性。修复多个运行时与会话边界问题SQLAlchemySession并发首次写入、reasoning 剥离后孤儿 assistant 消息 ID 的压缩请求、remove_all_tools()遗留 MCP/reasoning 条目、FunctionTool实例批处理执行器中的竞态。0.12.0 / 0.11.0这两个版本均不引入破坏性变更官方指出主要功能新增请查看对应 GitHub Release 页面仓库内未重复罗列细节。0.10.0Responses API WebSocket 传输总述0.10.0不引入破坏性变更但为 OpenAI Responses 用户新增了重大功能面Responses API 的 WebSocket 传输支持。亮点逐条解析为 OpenAI Responses 模型新增 WebSocket 传输支持opt-inHTTP 仍是默认传输。新增responses_websocket_session()辅助函数 /ResponsesWebSocketSession用于跨多轮运行复用共享的 WebSocket 能力 provider 与RunConfig。新增 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 有两个可能需要迁移的运行时行为变化同步工具移至工作线程执行包装同步Python 可调用对象的FunctionTool实例现在通过asyncio.to_thread(...)在工作线程执行而不是在事件循环线程上运行。如果工具逻辑依赖线程局部状态或线程亲和资源请迁移到异步工具实现或在工具代码中显式处理线程亲和性。本地 MCP 工具失败处理可配置默认行为现在可返回模型可见的错误输出而不是使整个 run 失败。如果依赖 fail-fast 语义请设置mcp_config{failure_error_function: None}。server 级failure_error_function会覆盖 agent 级设置因此需要在每个有显式处理器的本地 MCP server 上设置failure_error_functionNone。0.7.0嵌套 handoff 历史改为 opt-in总述0.7.0 有若干会影响既有应用的行为变化嵌套 handoff 历史现在默认为 opt-in默认关闭。如果你依赖 v0.6.x 的默认嵌套行为请显式设置RunConfig(nest_handoff_historyTrue)。gpt-5.1/gpt-5.2的默认reasoning.effort从 SDK 默认配置的low改为none对应源码 src/agents/models/default_models.py 中的模式映射。如果提示词或质量/成本画像依赖low请在model_settings中显式设置。0.6.0handoff 历史打包为单条消息总述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.0SIP 支持与 run_sync 内部重构总述0.5.0 没有可见的破坏性变更但包含新功能与若干重大内部更新RealtimeRunner新增对 SIP 协议连接 的支持。为 Python 3.14 兼容性显著重构了Runner#run_sync的内部逻辑。0.4.0openai v1.x 不再支持总述0.4.0 起不再支持openai包 v1.x请与本 SDK 一起使用 openai v2.x。注意此后的 0.21.0 又将基线推进到 openai v3。0.3.0Realtime 迁移至 gpt-realtime GA总述0.3.0 中 Realtime API 支持迁移到 gpt-realtime 模型及其 API 接口GA 版本。0.2.0Agent参数类型改为AgentBase总述0.2.0 中若干原本接收Agent作为参数的位置改为接收AgentBase例如 MCP server 的list_tools()方法签名。这纯粹是类型层面的变化运行时仍会收到Agent对象。更新方式把类型错误中的Agent替换为AgentBase即可。0.1.0MCPServer.list_tools()新增参数总述0.1.0 中MCPServer.list_tools()新增两个参数run_context与agent。MCPServer子类中每个被覆盖的list_tools()方法都必须加上这两个参数。升级实战建议综合以上逐版本变更记录可以沉淀出几条实用的升级策略先看Y位0.Y.Z的Y递增是破坏性变更的风向标。升级前先对照本文变更日志重点检查涉及显式 client 参数冲突、类型收窄、线程执行语义、默认模型/默认设置变更、HTTP/MCP 依赖栈的条目。敏感时刻锁定版本不想承担破坏性变更时官方建议锁定0.0.x系列需要跟随新功能时可关注 Patch 版本Z的非破坏性更新。注意默认值漂移SDK 默认模型当前gpt-5.6-lunasrc/agents/models/default_models.py与默认reasoning.effort会随版本变化。对质量/成本敏感的生产应用在 agent 或 run config 上显式指定模型与model_settings或设置OPENAI_DEFAULT_MODEL环境变量。关注依赖基线openai v3 HTTPX20.21.0、MCP v1/v2 双栈0.20.0、Python 3.100.9.0是当前仓库 pyproject.toml 的实际基线迁移代码时以这三个约束为准。异常语义变化优先排查ModelRefusalError0.15.0、终态failed/incomplete抛ModelBehaviorError0.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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考