adk-python 实战用 AgentTool 把 Stdio 模式的 MCP 工具集封装成可调用的子 Agent【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python本篇以 adk-python 仓库中的示例mcp_in_agent_tool_stdio为主体讲清一个常见组合拳如何把基于 MCPModel Context Protocolstdio 连接的McpToolset挂到一个子 Agent 上再用AgentTool将该子 Agent 整体封装为主 Agent 的一个工具。读完后你能掌握 stdio 与 SSE 两种 MCP 连接模式的选择依据、StdioConnectionParams的关键参数含义以及Agent 套 Agent的委派链路在源码层面是如何运作的。1. 这个示例解决什么问题在真实系统中主 Agent 往往只需要一个帮我抓取网页的能力入口而不希望把 MCP 服务器的每个工具声明都直接暴露在自身的工具列表里。adk-python 仓库中的示例 contributing/samples/mcp/mcp_in_agent_tool_stdio/README.md 正是为此设计的子 Agentmcp_helper持有McpToolset直接访问 MCP 工具子 Agent 被AgentTool包装后成为主 Agentmain_agent眼中的一个普通工具MCP 服务器以stdio 子进程方式运行无需预先安装或手动启动。整个示例只有两个核心文件contributing/samples/mcp/mcp_in_agent_tool_stdio/agent.py 和上文提到的 README下面逐层拆解。2. Stdio 与 SSE 模式为什么选 stdioREADME 首先对比了两种 MCP 连接模式。本示例使用stdio 模式即 MCP 服务器作为子进程运行具有以下特点特性stdio 模式本示例SSE 模式远程服务器部署复杂度更简单无需启动独立服务器需要单独运行 HTTP 服务器启动方式Agent 运行时自动拉起需手动启动通信通道stdin/stdoutHTTP / Server-Sent Events对于 SSE远程服务器版本仓库提供了对应的姊妹示例 mcp_in_agent_tool_remote其 MCP 服务器需在独立终端以--transport sse --port 3000启动。本文聚焦 stdio 版本。零安装uvx 自动拉起 MCP 服务器README 强调No installation required运行 Agent 时stdio 连接会自动执行以下命令来从 MCP Python SDK 仓库的子目录拉取并运行simple-tool服务器uvx --from githttps://github.com/modelcontextprotocol/python-sdk.git#subdirectoryexamples/servers/simple-tool \ mcp-simple-tool这条命令由 stdio 连接在 Agent 启动时自动执行服务器暴露的核心工具是一个Website Fetcher网页抓取器。3. 示例代码逐段解析以下是 agent.py 的完整结构与要点为便于讲解添加了参数说明注释与仓库源码一致3.1 创建 stdio 连接的 McpToolsetfrom google.adk.agents import Agent from google.adk.tools import AgentTool from google.adk.tools.mcp_tool import McpToolset from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams from mcp import StdioServerParameters # 使用 stdio 连接创建 MCP 工具集 # 服务器会在 Agent 启动时通过 uvx 自动拉起 mcp_toolset McpToolset( connection_paramsStdioConnectionParams( server_paramsStdioServerParameters( commanduvx, # 启动命令 args[ --from, githttps://github.com/modelcontextprotocol/python-sdk.git#subdirectoryexamples/servers/simple-tool, mcp-simple-tool, ], ), timeout10.0, # 建立连接的最长等待时间秒示例中放宽到 10 秒 ) )这里有两个值得注意的参数细节均可在源码中确认StdioConnectionParams的timeout默认值为 5.0 秒其字段定义见 src/google/adk/tools/mcp_tool/mcp_session_manager.pyserver_params为必填的StdioServerParameterstimeout是建立 stdio 连接的超时时间。示例显式传入10.0是为了给uvx首次从 git 仓库拉取并安装simple-tool留出时间——首次冷启动下载依赖时5 秒默认值往往不够。McpToolset也接受裸的StdioServerParameters见 src/google/adk/tools/mcp_tool/mcp_toolset.py 的构造函数文档说明但该形式不支持超时参数官方建议在需要超时时使用StdioConnectionParams——这正是本示例的写法。McpToolset还支持示例未用到的多个可选参数可按需扩展tool_filter按工具名列表或谓词函数过滤暴露给 Agent 的 MCP 工具tool_name_prefix为工具名添加前缀避免多个工具集重名tool_list_cache_ttl_seconds缓存服务器tools/list响应若干秒减少重复列举开销require_confirmation为工具调用开启人工确认Human-in-the-loop。3.2 持有 MCP 工具的子 Agentsub_agent Agent( namemcp_helper, descriptionA helpful assistant with access to MCP tools for fetching websites., instructionYou are a helpful assistant with access to MCP tools. ...指示其说明可用工具、按需调用、给出清晰回复 You have access to a website fetcher tool via MCP. Use it to fetch and return website content., tools[mcp_toolset], )name与description不只是元信息AgentTool会用它们直接生成工具声明见第 4 节所以子 Agent 的 description 实际上就是主 Agent 看到的工具说明应写清楚它能干什么。3.3 用 AgentTool 包装子 Agent# 把子 Agent 包装成工具主 Agent 即可调用它 mcp_agent_tool AgentTool(agentsub_agent)3.4 主 Agentroot_agent Agent( namemain_agent, descriptionMain agent that can delegate to a sub-agent with MCP tools., instructionYou are a helpful assistant. You have access to a sub-agent (mcp_helper) that has MCP tools for fetching websites. - If they need to fetch a website, call the mcp_helper tool - Otherwise, respond directly, tools[mcp_agent_tool], )两个 Agent 都没有指定model因此使用 ADK 的默认模型README 原话The agents do not set a model, so they use the ADK default。4. AgentTool 的底层机制子 Agent 如何变成一个工具从源码 src/google/adk/tools/agent_tool.py 可以确认AgentTool的关键行为命名与描述继承自 Agent构造时执行super().__init__(nameagent.name, descriptionagent.description)。所以本示例中主 Agent 的工具列表里出现的工具名就是mcp_helper描述就是子 Agent 的 description——这就是 README 中让用户执行 Use the mcp_helper to fetch ... 提示词的原因。默认输入 schema 是一个request字符串当被包装的 Agent 没有定义input_schema时AgentTool._get_declaration()会生成一个只含request: string且为必填参数的函数声明非 Gemini API 变体还会补充 response 类型。因此主 Agent 调用时只需传一段自然语言任务描述子 Agent 会在独立上下文中自主完成多轮工具调用后返回结果。结构化 I/O 的支持若子 Agent 定义了input_schema/output_schema声明会相应地基于 schema 构建。源码文档同时提示若只是想让父LlmAgent把子 Agent 作为内联工具暴露更推荐的方式是给子 Agent 设置modesingle_turn并通过sub_agents挂载由框架自动暴露为工具、并在父会话内联运行直接包装AgentTool的场景如本示例更多是为了获得独立的执行上下文与委派隔离。5. 架构总览README 给出的调用链如下与源码完全对应main_agent (root_agent) │ └── AgentTool wrapping: │ └── mcp_helper (sub_agent) │ └── McpToolset (stdio connection) │ └── MCP Server (subprocess via uvx) │ └── uvx --from git...#subdirectory... mcp-simple-tool │ └── Website Fetcher Tool即用户请求 → 主 Agent 决策是否委派 → 以request文本调用mcp_helper工具 → 子 Agent 通过 stdio 管道与 uvx 拉起的 MCP 子进程通信 → 调用 Website Fetcher 工具取回网页内容 → 结果逐层返回。6. 运行演示并验证6.1 启动 adk webadk web contributing/samples/mcp在 Agent 列表中选择mcp_in_agent_tool_stdio即可交互。无需任何预装步骤MCP 服务器会在首次连接时自动通过uvx拉起。6.2 推荐的两条验证提示词README 给出了两条验证用 prompt检查可用工具What tools do you have access to?抓取并总结 JSON Schema 规范Use the mcp_helper to fetch https://json-schema.org/specification and summarize the key features of JSON Schema第二条能同时验证三层链路主 Agent 是否正确委派给了mcp_helper、stdio 子进程是否成功启动、Website Fetcher 工具是否真实取回了网页内容。7. 已知问题与延伸阅读README 的 Related 一节明确记录了两个与本模式相关的上游 Issue仓库中不再重复给出链接按编号即可检索Issue #1112在adk web之外将 Agent 作为工具使用时进程无法干净退出doesnt exit cleanly。因此本示例推荐通过adk web运行若在脚本中直接Runner驱动该结构需留意 stdio 子进程的生命周期管理必要时可调用工具集的close()手动关闭连接McpToolset文档说明中亦提到Cleanup is handled automatically by the agent framework. But you can also manually close if needed。Issue #929LiteLLM 配合 OpenAI 模型访问部分 MCP 服务器如 Grafana时报错的案例提示在非 Gemini 模型栈上使用时需额外关注函数调用格式兼容性。延伸学习路径均为仓库内文件SSE 远程版本示例contributing/samples/mcp/mcp_in_agent_tool_remote/README.md可对照第 2 节的模式差异工具集实现src/google/adk/tools/mcp_tool/mcp_toolset.py连接参数与会话管理src/google/adk/tools/mcp_tool/mcp_session_manager.py其中除StdioConnectionParams外还有SseConnectionParams与StreamableHTTPConnectionParamsAgent 封装工具实现src/google/adk/tools/agent_tool.py。8. 小结本示例展示了一套可直接复制的集成范式McpToolsetstdio StdioConnectionParams负责接入任意可用uvx/npx命令拉起的 MCP 服务器子 Agent 负责封装具体工具能力AgentTool负责委派主从 Agent 间的调用边界。三个组件各司其职既避免了主 Agent 工具列表膨胀又利用 stdio 的免安装特性把 MCP 生态即插即用地接入了 ADK 的 Agent 体系。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 adk-python 实战：用 AgentTool 把 Stdio 模式的 MCP 工具集封装成可调用的子 Agent
adk-python 实战用 AgentTool 把 Stdio 模式的 MCP 工具集封装成可调用的子 Agent【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python本篇以 adk-python 仓库中的示例mcp_in_agent_tool_stdio为主体讲清一个常见组合拳如何把基于 MCPModel Context Protocolstdio 连接的McpToolset挂到一个子 Agent 上再用AgentTool将该子 Agent 整体封装为主 Agent 的一个工具。读完后你能掌握 stdio 与 SSE 两种 MCP 连接模式的选择依据、StdioConnectionParams的关键参数含义以及Agent 套 Agent的委派链路在源码层面是如何运作的。1. 这个示例解决什么问题在真实系统中主 Agent 往往只需要一个帮我抓取网页的能力入口而不希望把 MCP 服务器的每个工具声明都直接暴露在自身的工具列表里。adk-python 仓库中的示例 contributing/samples/mcp/mcp_in_agent_tool_stdio/README.md 正是为此设计的子 Agentmcp_helper持有McpToolset直接访问 MCP 工具子 Agent 被AgentTool包装后成为主 Agentmain_agent眼中的一个普通工具MCP 服务器以stdio 子进程方式运行无需预先安装或手动启动。整个示例只有两个核心文件contributing/samples/mcp/mcp_in_agent_tool_stdio/agent.py 和上文提到的 README下面逐层拆解。2. Stdio 与 SSE 模式为什么选 stdioREADME 首先对比了两种 MCP 连接模式。本示例使用stdio 模式即 MCP 服务器作为子进程运行具有以下特点特性stdio 模式本示例SSE 模式远程服务器部署复杂度更简单无需启动独立服务器需要单独运行 HTTP 服务器启动方式Agent 运行时自动拉起需手动启动通信通道stdin/stdoutHTTP / Server-Sent Events对于 SSE远程服务器版本仓库提供了对应的姊妹示例 mcp_in_agent_tool_remote其 MCP 服务器需在独立终端以--transport sse --port 3000启动。本文聚焦 stdio 版本。零安装uvx 自动拉起 MCP 服务器README 强调No installation required运行 Agent 时stdio 连接会自动执行以下命令来从 MCP Python SDK 仓库的子目录拉取并运行simple-tool服务器uvx --from githttps://github.com/modelcontextprotocol/python-sdk.git#subdirectoryexamples/servers/simple-tool \ mcp-simple-tool这条命令由 stdio 连接在 Agent 启动时自动执行服务器暴露的核心工具是一个Website Fetcher网页抓取器。3. 示例代码逐段解析以下是 agent.py 的完整结构与要点为便于讲解添加了参数说明注释与仓库源码一致3.1 创建 stdio 连接的 McpToolsetfrom google.adk.agents import Agent from google.adk.tools import AgentTool from google.adk.tools.mcp_tool import McpToolset from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams from mcp import StdioServerParameters # 使用 stdio 连接创建 MCP 工具集 # 服务器会在 Agent 启动时通过 uvx 自动拉起 mcp_toolset McpToolset( connection_paramsStdioConnectionParams( server_paramsStdioServerParameters( commanduvx, # 启动命令 args[ --from, githttps://github.com/modelcontextprotocol/python-sdk.git#subdirectoryexamples/servers/simple-tool, mcp-simple-tool, ], ), timeout10.0, # 建立连接的最长等待时间秒示例中放宽到 10 秒 ) )这里有两个值得注意的参数细节均可在源码中确认StdioConnectionParams的timeout默认值为 5.0 秒其字段定义见 src/google/adk/tools/mcp_tool/mcp_session_manager.pyserver_params为必填的StdioServerParameterstimeout是建立 stdio 连接的超时时间。示例显式传入10.0是为了给uvx首次从 git 仓库拉取并安装simple-tool留出时间——首次冷启动下载依赖时5 秒默认值往往不够。McpToolset也接受裸的StdioServerParameters见 src/google/adk/tools/mcp_tool/mcp_toolset.py 的构造函数文档说明但该形式不支持超时参数官方建议在需要超时时使用StdioConnectionParams——这正是本示例的写法。McpToolset还支持示例未用到的多个可选参数可按需扩展tool_filter按工具名列表或谓词函数过滤暴露给 Agent 的 MCP 工具tool_name_prefix为工具名添加前缀避免多个工具集重名tool_list_cache_ttl_seconds缓存服务器tools/list响应若干秒减少重复列举开销require_confirmation为工具调用开启人工确认Human-in-the-loop。3.2 持有 MCP 工具的子 Agentsub_agent Agent( namemcp_helper, descriptionA helpful assistant with access to MCP tools for fetching websites., instructionYou are a helpful assistant with access to MCP tools. ...指示其说明可用工具、按需调用、给出清晰回复 You have access to a website fetcher tool via MCP. Use it to fetch and return website content., tools[mcp_toolset], )name与description不只是元信息AgentTool会用它们直接生成工具声明见第 4 节所以子 Agent 的 description 实际上就是主 Agent 看到的工具说明应写清楚它能干什么。3.3 用 AgentTool 包装子 Agent# 把子 Agent 包装成工具主 Agent 即可调用它 mcp_agent_tool AgentTool(agentsub_agent)3.4 主 Agentroot_agent Agent( namemain_agent, descriptionMain agent that can delegate to a sub-agent with MCP tools., instructionYou are a helpful assistant. You have access to a sub-agent (mcp_helper) that has MCP tools for fetching websites. - If they need to fetch a website, call the mcp_helper tool - Otherwise, respond directly, tools[mcp_agent_tool], )两个 Agent 都没有指定model因此使用 ADK 的默认模型README 原话The agents do not set a model, so they use the ADK default。4. AgentTool 的底层机制子 Agent 如何变成一个工具从源码 src/google/adk/tools/agent_tool.py 可以确认AgentTool的关键行为命名与描述继承自 Agent构造时执行super().__init__(nameagent.name, descriptionagent.description)。所以本示例中主 Agent 的工具列表里出现的工具名就是mcp_helper描述就是子 Agent 的 description——这就是 README 中让用户执行 Use the mcp_helper to fetch ... 提示词的原因。默认输入 schema 是一个request字符串当被包装的 Agent 没有定义input_schema时AgentTool._get_declaration()会生成一个只含request: string且为必填参数的函数声明非 Gemini API 变体还会补充 response 类型。因此主 Agent 调用时只需传一段自然语言任务描述子 Agent 会在独立上下文中自主完成多轮工具调用后返回结果。结构化 I/O 的支持若子 Agent 定义了input_schema/output_schema声明会相应地基于 schema 构建。源码文档同时提示若只是想让父LlmAgent把子 Agent 作为内联工具暴露更推荐的方式是给子 Agent 设置modesingle_turn并通过sub_agents挂载由框架自动暴露为工具、并在父会话内联运行直接包装AgentTool的场景如本示例更多是为了获得独立的执行上下文与委派隔离。5. 架构总览README 给出的调用链如下与源码完全对应main_agent (root_agent) │ └── AgentTool wrapping: │ └── mcp_helper (sub_agent) │ └── McpToolset (stdio connection) │ └── MCP Server (subprocess via uvx) │ └── uvx --from git...#subdirectory... mcp-simple-tool │ └── Website Fetcher Tool即用户请求 → 主 Agent 决策是否委派 → 以request文本调用mcp_helper工具 → 子 Agent 通过 stdio 管道与 uvx 拉起的 MCP 子进程通信 → 调用 Website Fetcher 工具取回网页内容 → 结果逐层返回。6. 运行演示并验证6.1 启动 adk webadk web contributing/samples/mcp在 Agent 列表中选择mcp_in_agent_tool_stdio即可交互。无需任何预装步骤MCP 服务器会在首次连接时自动通过uvx拉起。6.2 推荐的两条验证提示词README 给出了两条验证用 prompt检查可用工具What tools do you have access to?抓取并总结 JSON Schema 规范Use the mcp_helper to fetch https://json-schema.org/specification and summarize the key features of JSON Schema第二条能同时验证三层链路主 Agent 是否正确委派给了mcp_helper、stdio 子进程是否成功启动、Website Fetcher 工具是否真实取回了网页内容。7. 已知问题与延伸阅读README 的 Related 一节明确记录了两个与本模式相关的上游 Issue仓库中不再重复给出链接按编号即可检索Issue #1112在adk web之外将 Agent 作为工具使用时进程无法干净退出doesnt exit cleanly。因此本示例推荐通过adk web运行若在脚本中直接Runner驱动该结构需留意 stdio 子进程的生命周期管理必要时可调用工具集的close()手动关闭连接McpToolset文档说明中亦提到Cleanup is handled automatically by the agent framework. But you can also manually close if needed。Issue #929LiteLLM 配合 OpenAI 模型访问部分 MCP 服务器如 Grafana时报错的案例提示在非 Gemini 模型栈上使用时需额外关注函数调用格式兼容性。延伸学习路径均为仓库内文件SSE 远程版本示例contributing/samples/mcp/mcp_in_agent_tool_remote/README.md可对照第 2 节的模式差异工具集实现src/google/adk/tools/mcp_tool/mcp_toolset.py连接参数与会话管理src/google/adk/tools/mcp_tool/mcp_session_manager.py其中除StdioConnectionParams外还有SseConnectionParams与StreamableHTTPConnectionParamsAgent 封装工具实现src/google/adk/tools/agent_tool.py。8. 小结本示例展示了一套可直接复制的集成范式McpToolsetstdio StdioConnectionParams负责接入任意可用uvx/npx命令拉起的 MCP 服务器子 Agent 负责封装具体工具能力AgentTool负责委派主从 Agent 间的调用边界。三个组件各司其职既避免了主 Agent 工具列表膨胀又利用 stdio 的免安装特性把 MCP 生态即插即用地接入了 ADK 的 Agent 体系。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考