STARWARCLOUD STARWAR.AI
返回市场
MCP-AI代理

MCP-AI代理

作者：luuisotorres6 星标更新：2025-11-19
安装使用来源：spider==github.com

项目介绍

使用Google ADK、Google Maps和Opik的MCP AI代理

<p align="left"> <img src="https://img.shields.io/badge/Python-3.11-blue?logo=python&logoColor=white" alt="Python"> <img src="https://img.shields.io/badge/OpenAI-GPT--4o-ffbb00?logo=openai&logoColor=black" alt="OpenAI GPT-4o"> <img src="https://img.shields.io/badge/Google%20Maps-MCP%20Server-4285F4?logo=googlemaps&logoColor=white" alt="Google Maps MCP Server"> <img src="https://img.shields.io/badge/CometML-Opik-FF6F00?logo=comet&logoColor=white" alt="Opik / CometML"> <img src="https://img.shields.io/badge/ADK-Google%20Agent%20Development%20Kit-34A853?logo=google&logoColor=white" alt="Google ADK"> </p>

视频演示

<div align="center"> <a href="https://www.youtube.com/watch?v=fh0lkWitz2E"> <img src="https://img.youtube.com/vi/fh0lkWitz2E/maxresdefault.jpg" alt="观看演示" style="width:80%;"> </a> <br> <i>点击上方图片在YouTube上观看演示</i> </div> <br />

本项目展示了如何使用Google Agent Development Kit (ADK)、OpenAI的GPT-4o模型、Google Maps MCP服务器以及Opik与Comet.ml进行可观测性来创建一个AI代理。

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

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

目录

关键技术

Google Agent Development Kit (ADK)

ADK logo

Google Agent Development Kit (ADK)是一个旨在简化由大型语言模型(LLMs)驱动的AI代理开发的Python框架。它通过与LiteLlm库的集成，提供了访问工具、记忆、代理编排以及来自OpenAI、Anthropic、Cohere等提供商的LLMs的能力。ADK还包括一个用于与代理交互和调试的Web界面。

Opik & CometML

Opik是由Comet开发的一个开源LLM应用程序可观测解决方案。它允许您追踪、可视化和调试AI代理内的交互，包括LLM调用、工具使用和其他操作。 在这个项目中，Opik被配置为将跟踪发送到CometML，提供了一个丰富的UI来检查代理行为。

模型上下文协议(MCP)

MCP

模型上下文协议(MCP)是一种开放协议，标准化了应用程序如何向LLMs提供上下文并将其连接到不同的数据源和工具。它定义了工具描述、调用和响应的模式。这使得不同LLM系统和工具提供商之间可以互操作。

Google Maps MCP服务器

Google Maps MCP服务器是一个Node.js应用程序，它公开了Google Maps平台API作为MCP工具。这使得ADK代理能够轻松利用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平台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  # 创建虚拟环境（例如，.venv）
uv sync  # 安装pyproject.toml中的依赖项
source .venv/bin/activate # 或者在Windows上使用`.\.venv\Scripts\activate`

  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平台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项目名称。

运行代理

完成设置后，运行ADK Web界面：

uv run adk web

此命令将：

  1. 启动FastAPI服务器。
  2. 在http://127.0.0.1:8000提供一个Web界面，以便与您的代理交互。
  3. 当代理需要使用其工具时，agent.py中的MCPToolset会通过npx自动启动Google Maps MCP服务器。

截图及用法

ADK Web界面

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

(截图1：初始ADK Web界面屏幕，带有聊天输入框。) ADK Web界面 说明：ADK Web界面的主界面，您可以在其中向代理输入消息。

代理使用工具

代理可以理解使用来自Google Maps MCP服务器的工具的请求，例如方向、地点详情、海拔等。

示例：获取方向 代理响应“从圣保罗到坎皮纳斯怎么开车？”的问题，提供逐段导航。

(截图2：代理使用maps_directions工具。) 代理方向 说明：代理成功使用maps_directions工具在聊天界面上提供驾驶方向。

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

(截图3：代理使用maps_place_details获取埃菲尔铁塔评论。) 地点详情事件/UI 说明：代理获取并显示埃菲尔铁塔的评论，展示maps_place_details工具的使用和输出。

示例：获取海拔 代理可以提供给定坐标的海拔。

(截图4：代理使用maps_elevation工具。) 海拔工具UI 说明：代理使用maps_elevation工具提供指定坐标的海拔。

对话事件及工具调用

ADK Web界面提供了一个“事件”（或“跟踪”）标签页，您可以在其中检查对话流程。这包括代理执行的函数调用和从工具接收的响应。

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

(截图5：maps_reverse_geocode事件视图。) 逆地理编码事件 说明：事件视图详细记录了maps_reverse_geocode的functionCall，包括参数和元数据。

示例：maps_directions事件流 展示了当调用maps_directions工具时事件序列。

(截图6：maps_directions工具的事件视图。) 方向工具事件 说明：ADK UI中的“事件”标签页，显示maps_directions工具的调用细节。

Opik (CometML) 跟踪

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

Opik中的总体跟踪 列出项目捕获的所有交互。

(截图7：CometML中mcp-ai-agent项目的跟踪概述。) Opik跟踪概述 说明：CometML UI显示Opik捕获的不同代理交互的跟踪列表。

maps_direction_tool的具体Opik跟踪 显示LLM调用和maps_direction_tool调用的具体跟踪。

(截图8：涉及maps_directions工具的单个跟踪的详细视图。) Opik跟踪详情地图方向 说明：CometML中Opik跟踪的详细视图，显示maps_directions请求的操作序列，包括LLM调用和工具交互。

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

(截图9：Opik中maps_direction工具调用的输入/输出详情。) Opik跟踪YAML地图方向 说明：Opik跟踪中的输入/输出标签页，显示整个对话的请求和响应的YAML格式。

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

<b><i>注意：</i></b> 您可以在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

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

环境配置

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

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

代理定义

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

root_agent = LlmAgent(
    model=LiteLlm(model="openai/gpt-4o"),
    name="openai_agent",
    description="一个智能的地图助手，提供驾车、步行和公共交通路线……",
    instruction="当用户询问路线、旅行时间或位置之间的方向时……"

工具配置

这里我们定义与Google Maps MCP服务器的集成：

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

这告诉代理使用npx启动MCP服务器，使所有Google Maps工具对我们的代理可用。

可观测性回调

最后，我们附加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,
)

这使得每个由代理处理的交互都有深度可见性。

作者

Luis Fernando Torres

LinkedIn Medium ![Kaggle](https://img.sh shields.io/badge/Kaggle-20BEFF?style=for-the-badge&logo=kaggle&logoColor=white) Hugging Face

许可

本项目采用MIT许可证。详情见LICENSE文件。