使用子智能体管理 MCP¶

你已经了解了如何使用直接 MCP 工具集成将你的智能体连接到外部资源，以及如何通过智能体暴露的 MCP 服务器把你的智能体提供给外部客户端。然而，随着你的 ADK 多智能体能力不断增长，你可能需要一种方式来隔离复杂的多步推理，而不会让单个模型的上下文窗口过载。

开始使用¶

import os
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.agent_tool 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

# 步骤 1：初始化你的 MCP 连接
mcp_connection = StdioConnectionParams(
    server_params=StdioServerParameters(
        command='npx',
        args=['-y', '@modelcontextprotocol/server-postgres', 'postgres://user:pass@localhost:5432/db'],
    )
)

# 步骤 2：创建子智能体并附加 McpToolset
database_sub_agent = LlmAgent(
    name="database_sub_agent",
    model="gemini-flash-latest",
    description="Delegates tasks to a database specialist...",
    instruction="你是一位 SQL 专家...",
    tools=[McpToolset(connection_params=mcp_connection, tool_filter=['query_db', 'list_tables'])]
)
database_tool = AgentTool(agent=database_sub_agent)


# 步骤 3：把 AgentTool 提供给你的主根智能体
root_agent = LlmAgent(
    name="primary_orchestrator",
    model="gemini-pro-latest",
    instruction="你是主助手。你可以访问专业智能体。将数据检索任务委派给你的数据库工具。",
    tools=[database_tool]
)

架构角色与工具适配¶

在 ADK 框架中，AgentTool 封装一个 LlmAgent，将其作为原生工具暴露给父编排器。子智能体通过 McpToolset 消费工具，McpToolset 会连接到底层的 MCP 服务器（通过 list_tools），把外部 MCP 工具定义转换成 ADK 兼容的 BaseTool 实例，并异步代理所有执行调用（call_tool）。

工具作用域与认知过滤（`tool_filter`）¶

将 McpToolset 分配给专业化子智能体时，你可以使用 tool_filter 参数限制该智能体可用的具体工具：

认知聚焦： 只暴露与子智能体职责相关的特定操作，例如 'read_file'、'list_directory'。
安全与沙箱化： 防止对 MCP 服务器暴露的危险工具的意外访问，把执行面与不可预测的输入隔离开来。

连接传输模式¶

子智能体的 McpToolset 必须根据部署架构配置为两种主要连接模式之一：

本地子进程（StdioConnectionParams）： 生成一个本地可执行文件或进程（例如通过 npx 或 python），通过标准输入/输出进行通信。最适合自包含的单容器环境。
远程网络（StreamableHTTPConnectionParams / SseConnectionParams）： 通过 HTTP/SSE 连接，并携带诸如 X-Goog-Api-Key 或 Authorization 之类的标头。最适合可扩展的、多租户的或独立管理的 MCP 后端。

定义与生命周期规则¶

生产环境需同步实例化： 部署多智能体方案（Cloud Run、GKE、Agent Engine）时，子智能体及其 McpToolset 都必须在 agent.py 中同步实例化，而不是放在异步工厂函数内部。
会话持久化与恢复： McpToolset 支持通过 getstate 和 setstate 进行序列化。虽然会话状态在生命周期事件之间得以保留，但当智能体进程恢复时，MCP socket/stdio 连接会被动态重新初始化。
清理管理： 在自定义运行时中于 adk web 之外运行时，通过 toolset.close() 或退出栈显式销毁，可以确保后台服务器子进程和网络连接被干净地终止。