MCP AI Agent with Google ADK, Google Maps, and Opik

使用 Google ADK、Google Maps 和 Opik 构建 MCP AI Agent

视频演示

本项目演示了如何使用 Google Agent Development Kit (ADK)、OpenAI 的 GPT-4o 模型、Google Maps MCP 服务，以及用于借助 Comet.ml 实现可观测性的 Opik，来创建一个 AI Agent。

本项目的主要目标是加深我对Agent 开发原则、Model Context Protocol 的实际应用，以及如何将其工具和服务集成到 AI Agent 中以增强其训练数据之外能力的理解。

本项目主要受到 Santiago Valdarrama 在 YouTube 上发布的教程启发：

• 视频： 使用 Google Agent Development Kit (ADK) 构建 AI Agent
• 代码库： svpino/google-adk-sample

目录

• 关键技术
  • Google Agent Development Kit (ADK)
  • Opik 和 CometML
  • Model Context Protocol (MCP)
  • Google Maps MCP 服务
• 项目结构
• 项目设置和安装
  • 先决条件
  • 安装步骤
  • 环境变量
  • 运行 Agent
• 截图和用法
  • ADK Web UI
  • Agent 使用工具（路线）
  • 对话事件和工具图
  • Opik (CometML) 跟踪
• 代码深入解析（agent.py）
  • 导入和设置
  • Agent 定义
  • 工具配置
  • 可观测性回调
• 作者
• 许可证

关键技术

Google Agent Development Kit (ADK)

Google Agent Development Kit (ADK) 是一个 Python 框架，旨在简化由大模型驱动的 AI Agent 的开发。通过与 LiteLlm 库集成，它可以使用来自 OpenAI、Anthropic、Cohere 等许多提供商的大模型，并提供对工具、记忆和Agent 编排的支持。ADK 还包含一个用于与 Agent 交互和调试的 Web UI。

Opik & CometML

Opik 是由 Comet 构建的开源大模型应用可观测性解决方案。它可以让你对 AI Agent 中的交互进行追踪、可视化和调试，包括 大模型调用、工具使用及其他操作。 在本项目中，Opik 配置为将追踪数据发送到 CometML，并提供丰富的 UI 来检查 Agent 的行为。

模型上下文协议（MCP）

模型上下文协议（MCP） 是一种开放协议，用于规范应用向大模型提供上下文以及将其连接到不同数据源和工具的方式。它定义了工具描述、调用和响应的架构。这使不同的大模型系统和工具提供方能够实现互操作。

Google Maps MCP 服务

Google Maps MCP 服务 是一个 Node.js 应用，可将 Google Maps Platform API 作为 MCP 工具提供。这样，ADK Agent 就可以轻松利用 Google Maps 功能，提供更相关且能结合上下文的响应。

• 运行方式： 如本项目中的配置所示，如果服务器尚未运行，ADK 的 MCPToolset 可以使用 npx 自动启动它。
• 提供的主要工具：
  • maps_directions：获取驾车、步行或骑行路线。
  • maps_geocode：将地址转换为地理坐标。
  • maps_reverse_geocode：将地理坐标转换为地址。
  • maps_elevation：获取指定坐标的海拔。
  • maps_search_places：搜索地点（例如餐厅、地标）。
  • maps_place_details：获取特定地点的详细信息。
  • maps_distance_matrix：计算多个出发地和目的地之间的行程时间和距离。

项目结构

.
├── assets
│   └── screenshots
│       ├── interface.png
│       ├── maps_direction_tool_input_output.png
│       ├── maps_direction_tool_opik.png
│       ├── maps_direction_tool.png
│       ├── maps_directions_tool_events.png
│       ├── maps_elevation_tool.png
│       ├── maps_place_details_event.png
│       ├── maps_reverse_geocode_event.png
│       ├── opik_overall_input_output.png
|       ├── adk.png
|       ├── mcp.png
│       └── opik_traces.png
├── examples
│   └── agent_conversation.yaml
├── LICENSE
├── mcp_agent
│   ├── __init__.py
│   └── agent.py
├── pyproject.toml
├── README.md
└── uv.lock

项目设置与安装

先决条件

• Python 3.11
• uv（Python 软件包和虚拟环境管理器）
• Node.js 和 npm / npx（运行 Google Maps MCP 服务所需；ADK 将通过 npx 启动该服务）
• Google Maps Platform API 密钥？
• OpenAI API 密钥。
• CometML API 密钥、项目 ID 和工作区。

安装步骤

1. 克隆仓库：

   git clone https://github.com/luuisotorres/mcp-ai-agent.git
   cd mcp-ai-agent
   

2. 使用 UV 创建并同步虚拟环境：

   uv venv  # Create a virtual environment (e.g., .venv)
   uv sync  # Install dependencies from pyproject.toml
   source .venv/bin/activate # Or `.\.venv\Scripts\activate` on Windows
   

3. 设置环境变量： 复制示例环境文件并填入你的凭据：

   cp .env.example .env
   

   然后，在 .env 中填写实际的 API 密钥。

环境变量

GOOGLE_MAPS_PLATFORM_API_KEY="your-google-maps-api-key"
OPENAI_API_KEY="your-openai-api-key"
COMET_API_KEY="your-comet-api-key"
COMET_WORKSPACE="your-comet-workspace"
COMET_PROJECT_NAME="your-comet-project-name"

.env 文件应包含：

• GOOGLE_MAPS_PLATFORM_API_KEY：你的 Google Maps Platform API 密钥。
  • 用途： 允许 Google Maps MCP 服务向 Google Maps API 发出请求。
• OPENAI_API_KEY：你的 OpenAI API 密钥。
  • 用途： 允许 LiteLlm 模型使用 OpenAI 的 GPT 模型。
• COMET_API_KEY：你的 CometML API 密钥。
  • 用途： 让 Opik 将追踪数据发送到你的 CometML 项目。
• COMET_WORKSPACE：你的 CometML 工作区。
• COMET_PROJECT_NAME：用于存储追踪数据的 CometML 项目名称。

运行 Agent

完成设置后，运行 ADK Web UI：

uv run adk web

此命令将：

1. 启动 FastAPI 服务。
2. 在 http://127.0.0.1:8000 提供 Web 界面，以便与你的 Agent 交互。
3. agent.py 中的 MCPToolset 已配置为在 Agent 需要使用工具时，通过 npx 自动启动 Google Maps MCP server。

截图与用法

ADK Web UI

运行 uv run adk web 并访问 http://127.0.0.1:8000（或终端中显示的端口）后，你会看到 ADK Web UI。你可以选择 Agent，此处为 mcp_agent，并开始对话。

（截图 1：ADK Web UI 初始界面，包含聊天输入框。） 说明：ADK Web UI 的主界面，可在此输入消息与你的 Agent 对话。

Agent 使用工具

Agent 可以借助 Google Maps MCP Server 的 工具理解路线、地点详情、海拔等相关请求。

示例：获取路线 对于“如何从 São Paulo 开车到 Campinas？”这一问题，Agent 会提供逐步路线指引。

（截图 2：Agent 使用 maps_directions 工具。） 说明：Agent 成功使用 maps_directions 工具，在聊天界面中提供驾车路线指引。

示例：获取地点详情 Agent 可以获取地标的评价和其他信息。

（截图 3：Agent 使用 maps_place_details 获取埃菲尔铁塔的评价。） 说明：Agent 获取并显示埃菲尔铁塔的评价，展示了 maps_place_details 工具的用法和输出。

示例：获取海拔 Agent 可以提供指定坐标的海拔。

（截图 4：Agent 使用 maps_elevation 工具。） 说明：Agent 使用 maps_elevation 工具提供指定坐标的海拔。

对话事件与工具调用

ADK Web UI 提供了一个“Events”（或“Trace”）选项卡，可供你检查对话流程，其中包括 Agent 发起的函数调用以及从工具收到的响应。

示例：maps_reverse_geocode 事件 展示 Agent 调用 maps_reverse_geocode 工具。

（截图 5：maps_reverse_geocode 的事件视图。） 说明：事件视图详细显示了 maps_reverse_geocode 的 functionCall，以及对应的 args 和 Metadata。

示例：maps_directions 事件流程 展示调用 maps_directions 工具时的事件顺序。

（截图 6：maps_directions 工具的事件视图。） 说明：ADK UI 中的“Events”选项卡，显示了调用 maps_directions 工具的详细信息。

Opik（CometML）追踪

Opik 与 CometML 集成，可详细追踪 Agent 的执行过程，让你深入了解大模型调用、工具使用情况和整体性能。

Opik 中的整体追踪记录 项目中捕获的所有交互记录列表。

（截图 7：CometML 中 mcp-ai-agent 项目的追踪记录概览。） 说明：CometML 界面显示了 Opik 为不同 Agent 交互捕获的追踪记录列表。

maps_direction_tool 的 Opik 详细追踪记录 一条展示大模型调用和 maps_direction_tool 调用过程的具体追踪记录。

（截图 8：涉及 maps_directions 工具的单条追踪记录详细视图。） 说明：CometML 中 Opik 追踪记录的详细视图，展示了 maps_directions 请求的操作顺序，包括大模型调用和工具交互。

Opik 中的输入／输出 YAML 以 YAML 格式呈现大模型调用和工具交互的详细请求与响应数据。

（截图 9：Opik 中 maps_direction 工具调用的输入／输出详情。） 说明：CometML 中 Opik 追踪记录的“输入／输出”标签页，以 YAML 格式显示整个对话的请求与响应。

这些追踪记录对于调试、理解 Agent 行为和优化性能都非常有价值。

注意：你可以在 examples/agent_conversation.yaml 中找到此对话的完整 YAML 文件。

代码深入解析（agent.py）

导入和设置

首先导入 ADK、环境配置和可观测性所需的软件包：

from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
from google.adk.tools.mcp_tool.mcp_toolset import (
    MCPToolset,
    StdioServerParameters
)
import os
from dotenv import load_dotenv
import opik
from opik.integrations.adk import OpikTracer

这为 Agent 逻辑奠定了基础。

环境配置

在这里加载 API 密钥并配置可观测性：

load_dotenv()
opik.configure(use_local=False)
tracer = OpikTracer()
GOOGLE_MAPS_API_KEY = os.getenv("GOOGLE_MAPS_PLATFORM_API_KEY")

Agent 定义

我们使用 LlmAgent 初始化一个 ADK Agent，采用 OpenAI 的 GPT-4o 模型，并使用 LiteLlm 库实现 ADK <> OpenAI 集成：

root_agent = LlmAgent(
    model=LiteLlm(model="openai/gpt-4o"),
    name="openai_agent",
    description="An intelligent mapping assistant that provides driving, walking, and public transportation directions...",
    instruction="When the user asks for routes, travel times, or directions between locations..."

工具配置

我们在这里定义与 Google Maps MCP Server 的集成：

tools=[
    MCPToolset(
        connection_params=StdioServerParameters(
            command="npx",
            args=[
                "-y",
                "@modelcontextprotocol/server-google-maps"
            ],
            env={
                "GOOGLE_MAPS_API_KEY": GOOGLE_MAPS_API_KEY
            },
        ),
    )
],

这会让 Agent 使用 npx 启动 MCP 服务，从而为 Agent 提供所有 Google Maps 工具。

可观测性回调

最后，附加 Opik 追踪回调，以捕获 Agent 的完整生命周期：

before_agent_callback=tracer.before_agent_callback,
after_agent_callback=tracer.after_agent_callback,
before_model_callback=tracer.before_model_callback,
after_model_callback=tracer.after_model_callback,
before_tool_callback=tracer.before_tool_callback,
after_tool_callback=tracer.after_tool_callback,
)

这样即可深入了解 Agent 处理的每一次交互。

作者

Luis Fernando Torres

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。