ADK-Python项目中MCP工具在非Web环境下的使用问题解析

背景介绍

Google的ADK-Python项目是一个用于构建AI代理的开发工具包，其中MCP工具集(MCPToolset)是一个重要组件，用于与外部服务进行交互。在最新版本中，开发者报告了在非Web环境下使用MCP工具时无法正常退出的问题。

问题现象

开发者在使用MCPToolset时发现，当在非ADK Web环境(如独立脚本)中使用这些工具时，程序无法正常退出。这主要表现在：

1. 程序执行完毕后仍然保持运行状态
2. 需要手动终止进程
3. 资源无法正常释放

技术分析

在ADK-Python 1.0.0版本之前，开发者需要通过配置退出栈(exit stack)来管理资源。但在新版本中，这一机制被移除，导致开发者在使用MCP工具时缺乏明确的资源管理方案。

解决方案演进

初始解决方案

早期文档建议使用MCPToolset.from_server()方法配合退出栈管理资源，但随着版本更新，这种方法已被弃用。

当前最佳实践

项目维护者推荐采用以下方式：

1. 使用Runner类的异步上下文管理器
2. 在async with块中运行代理
3. 确保所有资源在退出时被正确释放

核心代码结构应如下：

async with Runner(agent=agent, app_name=app_name, session_service=session_service) as runner:
    async for event in runner.run_async(...):
        # 处理事件

实现细节

1. Runner类改进：最新版本中，Runner类已经内置了资源管理功能
2. 会话管理：需要正确初始化会话服务(InMemorySessionService)
3. 工具配置：MCPToolset需要正确配置连接参数(StdioServerParameters)

使用示例

以下是一个完整的正确使用示例：

import asyncio
from google.adk.agents.llm_agent import LlmAgent
from google.adk.tools.mcp_tool.mcp_toolset import MCPToolset, StdioServerParameters
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai.types import Content, Part

async def main():
    # 初始化工具和代理
    local_tool = MCPToolset(
        connection_params=StdioServerParameters(
            command='npx',
            args=["-y", "puppeteer-vision-mcp-server"],
            env={"OPENAI_API_KEY": "your_api_key"},
        )
    )
    
    agent = LlmAgent(
        model='gemini-2.5-flash-preview-04-17',
        tools=[local_tool],
        instruction="You are a web agent."
    )
    
    # 初始化服务
    session_service = InMemorySessionService()
    await session_service.create_session(app_name="web_agent", user_id="user1", session_id="session1")
    
    # 使用Runner运行代理
    async with Runner(
        agent=agent,
        app_name="web_agent",
        session_service=session_service
    ) as runner:
        user_message = Content(role="user", parts=[Part(text="Summarize Wikipedia Paris page")])
        async for event in runner.run_async(
            user_id="user1",
            session_id="session1",
            new_message=user_message
        ):
            print(event.content)

asyncio.run(main())

注意事项

1. 环境变量：确保所有必要的环境变量已正确设置
2. 依赖版本：使用最新版本的ADK-Python和相关依赖
3. 异步上下文：必须在异步环境中运行
4. 资源清理：避免在工具使用过程中手动终止进程

总结

ADK-Python项目中的MCP工具在非Web环境下使用时，开发者应当使用Runner类的上下文管理器模式来确保资源的正确管理和释放。这种方法比早期的退出栈方案更加简洁和可靠，是当前推荐的最佳实践。

对于更复杂的场景，如多代理协作系统，开发者可以参考项目提供的完整示例来构建自己的解决方案。随着项目的持续发展，预计会有更多简化工具使用的辅助函数被引入，进一步降低使用门槛。