Google ADK Python项目中MCP工具集的使用注意事项

Google ADK Python项目是一个用于构建和部署AI代理的开发工具包。在最新发布的1.0.0版本中，MCP(Model Context Protocol)工具的使用方式发生了重要变化，开发者需要特别注意这些变更以避免常见的运行时错误。

旧版代码的问题分析

在旧版本中，开发者通常会使用MCPToolset.from_server()方法来初始化MCP工具集。这种方式虽然简单，但在实际运行中容易出现协程未正确等待的问题，导致如下的典型错误：

AttributeError: 'coroutine' object has no attribute 'name'

这种错误通常发生在尝试访问异步函数返回的协程对象属性时，而没有先等待该协程完成。在ADK 1.0.0版本中，这种旧式用法已被弃用。

新版MCP工具集的正确用法

1.0.0版本引入了全新的MCP工具集初始化方式，开发者应当使用MCPToolset类直接实例化，并通过connection_params参数配置服务器连接。典型用法如下：

root_agent = LlmAgent(
    model='gemini-2.0-flash',
    name='enterprise_assistant',
    instruction="""帮助用户访问文件系统""",
    tools=[
        MCPToolset(
            connection_params=StdioServerParameters(
                command='npx',
                args=[
                    '-y',
                    '@modelcontextprotocol/server-filesystem',
                    '/allowed/path'
                ],
            ),
            tool_filter=[
                'read_file',
                'list_directory'
            ],
        )
    ],
)

关键改进点

1. 同步化设计：新版API采用同步调用方式，避免了异步协程带来的复杂性
2. 明确参数配置：通过connection_params清晰地指定服务器连接参数
3. 工具过滤机制：可以直接通过tool_filter参数限制可用的工具集

自定义UI开发的注意事项

对于需要开发自定义UI的开发者，同样需要遵循这一新的API设计模式。不再使用已被移除的from_server()方法，而是应该：

1. 明确指定所需的MCP工具
2. 正确配置服务器连接参数
3. 根据需要设置工具过滤器

这种设计变更虽然带来了短期内的迁移成本，但从长期来看提高了代码的可靠性和可维护性，使开发者能够更清晰地表达意图，减少异步编程带来的潜在问题。