AI导哈

AI代理开发工具

一个基于Google ADK、OpenAI GPT-4o和Google Maps MCP Server的AI代理开发工具，用于增强AI代理的功能，适用于地图服务、路线规划和地点查询等场景。

  • by luuisotorres
  • Python
  • 本地部署
  • 9 星标
  • 更新于
在 GitHub 查看 luuisotorres/mcp-ai-agent

使用说明

MCP AI代理与谷歌ADK、谷歌地图和Opik

视频演示


Click the image above to watch the demo on YouTube

该项目演示了如何创建 AI 代理 使用 谷歌代理开发工具包（ADK）, OpenAI的GPT-4o模型，the 谷歌地图MCP服务器，以及 Opik 为了可观察性 Comet.ml.

这个项目的主要目标是加深我对 代理开发原则，模型上下文协议在实践中的应用，以及如何将其工具和服务集成到 AI 代理 增强能力 除了训练数据。

这个项目的灵感主要来自Santiago Valdarrama在YouTube上的教程：

目录

关键技术

谷歌代理开发工具包（ADK）

这 谷歌代理开发工具包（ADK） 是一个Python框架，旨在简化开发 AI代理 由LLM供电。它提供了访问 工具, 记忆, 代理编排 通过与OpenAI、Anthropic、Cohere等许多提供商的整合，提供LLM LiteLlm 图书馆。ADK还包括 web用户界面 用于与代理交互和调试代理。

Opik&CometML

Opik 是Comet为LLM应用程序构建的开源可观察性解决方案。它允许你 痕迹, 可视化，以及 调试 您的AI代理内部的交互，包括 LLM电话, 工具使用以及其他操作。 在此项目中，Opik被配置为将跟踪发送到 CometML，提供丰富的UI来检查代理行为。

模型上下文协议（MCP）

这 模型上下文协议（MCP） 是一种开放协议，规范了应用程序如何向LLM提供上下文并将其连接到不同的LLM 数据源 和 工具它定义了一个模式 工具说明, 调用，以及 回复这允许不同LLM系统和工具提供商之间的互操作性。

谷歌地图MCP服务器

这 谷歌地图MCP服务器 是一个Node.js应用程序，它将谷歌地图平台API作为MCP工具公开。这允许 ADK代理 轻松利用谷歌地图功能提供更相关、上下文感知的响应。

  • 它是如何运行的： 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
  • 紫外线 （Python包和虚拟环境管理器）
  • Node.js 和 npm / npx （需要运行谷歌地图MCP服务器，ADK将通过该服务器启动 npx)
  • 谷歌地图平台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：您的谷歌地图平台API密钥。
    • 目的： 允许谷歌地图MCP服务器向谷歌地图API发出请求。
  • OPENAI_API_KEY：您的OpenAI API密钥。
    • 目的： 允许 LiteLlm 模型使用OpenAI的GPT模型。
  • COMET_API_KEY：您的CometML API密钥。
    • 目的： 让Opik向您的CometML项目发送跟踪。
  • COMET_WORKSPACE：您的CometML工作区。
  • COMET_PROJECT_NAME：将存储跟踪的CometML项目名称。

运行代理

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

uv run adk web

此命令将：

  1. 启动FastAPI服务器。
  2. 在以下位置提供web界面 http://127.0.0.1:8000 与您的代理人互动。
  3. 这 MCPToolset 在 agent.py 配置为通过以下方式启动Google Maps MCP服务器 npx 当代理需要使用其工具时自动执行。

截图和使用

ADK Web用户界面

跑步时 uv run adk web 并导航到 http://127.0.0.1:8000 （或终端中显示的端口），您将看到ADK Web UI。在这种情况下，您可以选择您的代理 mcp_agent，并开始对话。

（截图1：带有聊天输入的初始ADK Web UI屏幕。）

代理使用工具

代理可以使用 工具 从 谷歌地图MCP服务器.

示例：获取路线 客服在回答“我该如何从圣保罗开车到坎皮纳斯？”时，会给出详细的路线指引。

（截图2：代理使用 maps_directions 工具。)

示例：获取地点详细信息 代理可以获取地标的评论和其他信息。

（截图3：代理使用 maps_place_details 埃菲尔铁塔评论。)

示例：获取高程 代理可以为给定的坐标提供高程。

（截图4：代理使用 maps_elevation 工具。)

对话事件和工具调用

ADK Web UI提供了一个“事件”（或“跟踪”）选项卡，您可以在其中检查对话的流程。这包括代理进行的函数调用和从工具收到的响应。

例子： maps_reverse_geocode 事件 显示调用的代理 maps_reverse_geocode 工具。

（屏幕截图5：事件视图 maps_reverse_geocode.) 标题：事件视图，详细介绍 functionCall 为了 maps_reverse_geocode 随着 args 以及元数据。

例子： maps_directions 事件流程 说明事件发生时的顺序 maps_directions 工具被称为。

（屏幕截图6：事件视图 maps_directions 工具。) 描述：ADK UI中的“事件”选项卡，显示了 maps_directions 工具。

Opik（CometML）追踪

Opik与CometML集成，提供代理执行的详细跟踪，提供LLM调用、工具使用和整体性能的见解。

Opik中的总体痕迹 项目所有捕获交互的列表。

（截图7:CometML中的痕迹概述 mcp-ai-agent 项目。) 描述：CometML UI显示了Opik为不同代理交互捕获的跟踪列表。

详细的Opik跟踪 maps_direction_tool 显示LLM调用和 maps_direction_tool 调用。

（截图8：涉及 maps_directions 工具。) 描述：CometML中Opik跟踪的详细视图，显示了 maps_directions 请求，包括LLM调用和工具交互。

Opik中的输入/输出YAML LLM调用和工具交互的详细请求和响应数据，以YAML形式呈现。

（屏幕截图9：输入/输出详细信息 maps_direction Opik中的工具调用。) 描述：CometML中Opik跟踪内的输入/输出选项卡，以YAML格式显示整个对话的请求和响应。

这些跟踪对于调试、理解代理行为和优化性能非常宝贵。

注： 您可以在以下网址找到此对话的整个YAML文件 examples/agent_conversation.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

这为代理逻辑奠定了基础。

环境配置

在这里，我们加载API密钥并配置可观察性：

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

代理定义

我们初始化一个 ADK代理 随着 LlmAgent 使用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..."

工具配置

这就是我们定义与 谷歌地图MCP服务器:

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

这告诉代理使用 npx，使我们的代理可以使用所有谷歌地图工具。

可观察性回调

最后，我们附加Opik跟踪回调以捕获整个代理生命周期：

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,
)

这使得能够深入了解代理处理的每个交互。

作者

路易斯·费尔南多·托雷斯

许可证

该项目根据MIT许可证获得许可。请参阅 许可证 文件以获取详细信息。


相关 MCP