OpenAI Agents SDK 兼容 MCP Python SDK v1 与 v2 有哪些差异【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python如果你的应用通过 OpenAI Agents SDKopenai-agents-python连接本地 MCP 服务器环境中的mcpPython 包可能解析到 v1 也可能解析到 v2SDK 声明的依赖范围是mcp1.19.0,3见 pyproject.toml且带python_version 3.10条件。对绝大多数应用来说升级不需要改代码但有两类配置在 v1 与 v2 之间行为不同。本文列出这些差异并给出升级前后的验证方式。先区分两个“版本”文档中反复出现的版本其实有两个不要混用已安装的mcpPython 包的主版本号v1 或 v2由你的依赖解析结果决定与 MCP 服务器协商的 MCP 协议版本由握手过程决定。两者相互独立。Agents SDK 会检测已安装mcp包的主版本号并自动适配 stdio、SSE、Streamable HTTP 三种本地连接普通的服务器配置不需要任何版本开关。检测与适配逻辑集中在 src/agents/mcp/_compat.py它读取mcp分发的版本号得到MCP_V2标记并在两个主版本之间转换字段命名如inputSchema与input_schema、nextCursor与next_cursor、isError与is_error和异常结构。业务代码对这部分差异是透明的。v2 下的连接行为先探测失败则回退安装 MCP Python SDK v2 后SDK 会围绕你配置的本地传输创建mcp.Clientmodeauto。客户端先用已安装 SDK 支持的最新协议版本发送server/discover探测现代服务器应答探测客户端采用探测结果旧服务器不支持server/discover时客户端回退到传统initialize握手并使用该握手协商出的协议版本。因此安装 v2 并不会把所有连接都推到最新的 MCP 协议版本。这条行为由 docs/release.md 中 0.20.0 的发布说明确认v2 支持在该版本引入同时通过mcp1.19.0,3保持 v1 兼容0.21.0 则说明本地 MCP 的 HTTP 自定义“继续遵循已安装的 MCP 包”v1 使用传统httpxv2 使用httpx2。真正需要留意的三处差异以下差异只影响自定义了 HTTP 层或特定参数的应用来源是 docs/mcp.md 的 “MCP Python SDK v1 and v2” 一节定制项MCP Python SDK v1MCP Python SDK v2params[auth]httpx.Authhttpx2.Authparams[httpx_client_factory]返回值httpx.AsyncClienthttpx2.AsyncClientMCPServerStreamableHttp的params[ignore_initialized_notification_failure] True支持不支持会在连接建立前被拒绝要点优先使用Authorization请求头传递凭据。请求头在两个主版本下行为一致不涉及httpx/httpx2类型问题。如果你通过params[auth]或params[httpx_client_factory]提供了自定义值这些值的类型必须与已安装mcp包主版本对应的 HTTP 类型匹配要么把它们迁移到httpx2要么固定mcp2留在 v1。使用了ignore_initialized_notification_failure True的应用必须保持mcp2或在升级前移除该选项。HostedMCPTool不受这些本地依赖要求影响远程 MCP 连接由 OpenAI Responses API 持有本地mcp包不参与。锁定主版本两条显式约束命令大多数应用应让依赖解析器自己选择兼容版本。如果你的应用必须固定在某个主版本在openai-agents之外再添加一条显式约束# MCP Python SDK v1 pip install mcp1.19.0,2 # MCP Python SDK v2 pip install mcp2,3升级决策可以按一条简单路径走检查你的代码是否使用了上表中的params[auth]、params[httpx_client_factory]或ignore_initialized_notification_failure。没有使用则直接升级使用过auth/factory 的把对应值迁移到httpx2使用了ignore_initialized_notification_failure且短期无法改造的用mcp2固定住 v1。验证两个主版本下的兼容性行为先确认当前环境装的是哪个主版本。项目的打包集成测试用importlib.metadata做同一检查见 integration_tests/packaging/test_mcp_compat.py你可以用同样的方式查看python -c from importlib.metadata import version; print(version(mcp))输出为1.x即 v12.x即 v2。要验证 SDK 在两个主版本下都能连上旧式服务器可以直接复用仓库自带的旧式 stdio 服务器 tests/mcp/servers/legacy.py。该服务器对server/discover返回 JSON-RPC 错误code: -32601, Method not found只对initialize、tools/list、tools/call做应答正好覆盖“v2 探测失败后回退传统握手”这条路径。下面的脚本改编自 tests/mcp/test_mcp_version_compat.pyimport asyncio import sys from pathlib import Path from agents.mcp import MCPServerStdio from agents.mcp._compat import MCP_V2, result_is_error # 替换为你本地 openai-agents-python 仓库中 tests/mcp/servers/legacy.py 的绝对路径 LEGACY_SERVER_PATH Path(/absolute/path/to/openai-agents-python/tests/mcp/servers/legacy.py) async def main() - None: server MCPServerStdio( namelegacy-test-server, params{command: sys.executable, args: [str(LEGACY_SERVER_PATH)]}, ) async with server: tools await server.list_tools() result await server.call_tool(legacy_tool, {}) protocol_version getattr(server.session, protocol_version, None) print(MCP v2 installed:, MCP_V2) print(tools:, [tool.name for tool in tools]) print(protocol:, protocol_version) print(is_error:, result_is_error(result)) asyncio.run(main())判断标准以项目测试中的断言为准两个主版本下都应列出[legacy_tool]调用结果为文本legacy-result且错误标记为False在MCP_V2为True即安装了 v2时断言protocol_version 2025-06-18且server.server_initialize_result is not None——这说明回退到了传统initialize握手并保留了其结果is_error通过result_is_error()读取该函数在_compat.py中屏蔽了 v1 的isError与 v2 的is_error字段差异。若想在 CI 中固化这个检查打包测试的运行方式可以参考 integration_tests/packaging/test_mcp_compat.py它断言已安装的mcp版本与环境变量OPENAI_AGENTS_INTEGRATION_MCP_VERSION一致后再执行同样的连接与调用。限制上述自动适配只覆盖 SDK 创建的本地 MCP 连接stdio、SSE、Streamable HTTP。HostedMCPTool走 Responses API不受本地mcp包版本影响。SSE 传输本身已被 MCP 项目标记为弃用文档建议新集成优先使用 Streamable HTTP 或 stdioSSE 仅用于遗留服务器如果你正在做 v1 到 v2 的迁移这也是考虑更换传输的时机。本文涉及的主版本行为断言均来自 docs/mcp.md、docs/release.md 与仓库测试如果你的环境依赖解析到了mcp3.x 或低于 1.19.0 的版本已超出 SDK 声明的1.19.0,3范围文档没有给出该范围的兼容承诺。【免费下载链接】openai-agents-pythonA lightweight, powerful framework for multi-agent workflows项目地址: https://gitcode.com/GitHub_Trending/op/openai-agents-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考