使用 MCP 服务器为 BigQuery 和 Google 地图构建位置信息智能 ADK 代理

1. 简介

在此 Codelab 中，您将使用由 Gemini 3.5 Flash 提供支持的 ADK 构建一个智能体。该智能体将配备来自两个远程（Google 托管）MCP 服务器的工具，以安全地访问 BigQuery，获取人口统计数据、价格数据和销售数据；并访问 Google 地图，进行实际位置分析和验证。

该智能体协调用户与 Google Cloud 服务之间的请求，以解决与虚构的面包店数据集相关的业务问题。

82dd7bd2823a821b.png

实践内容

  • 设置数据：在 BigQuery 中创建基础烘焙店数据集。
  • 开发智能体：使用智能体开发套件 (ADK) 构建智能体。
  • 集成工具：通过 MCP 服务器为智能体配备 BigQuery 和 Maps 功能。
  • 分析市场：与代理互动，评估市场趋势和饱和度。

所需条件

  • 网络浏览器，例如 Chrome
  • 启用了结算功能的 Google Cloud 项目或 Gmail 账号。

本 Codelab 适合各种水平的开发者，包括新手。您将使用 Google Cloud Shell 中的命令行界面和 Python 代码进行 ADK 开发。您无需成为 Python 专家，但对如何读取代码有基本的了解将有助于您理解相关概念。

2. 准备工作

创建 Google Cloud 项目

  1. 在 Google Cloud 控制台的项目选择器页面上，选择或创建一个 Google Cloud 项目。

a3dd2e6dddc8f691.png

  1. 确保您的 Cloud 项目已启用结算功能。了解如何检查项目是否已启用结算功能。

启动 Cloud Shell

Cloud Shell 是在 Google Cloud 中运行的命令行环境，预加载了必要的工具。

  1. 点击 Google Cloud 控制台顶部的激活 Cloud Shell：

404e4cce0f23e5c5.png

  1. 连接到 Cloud Shell 后，运行以下命令以验证您在 Cloud Shell 中的身份验证：
gcloud auth list
  1. 运行以下命令，确认您的项目已配置为可与 gcloud 搭配使用：
gcloud config get project
  1. 确认项目符合预期，然后运行以下命令以设置项目 ID：
export PROJECT_ID=$(gcloud config get project)

3. 获取代码

克隆代码库

  1. 将代码库克隆到 Cloud Shell 环境：
git clone https://github.com/google/mcp.git
  1. 前往演示目录：
cd mcp/examples/launchmybakery

身份验证

运行以下命令以使用您的 Google Cloud 账号进行身份验证。ADK 需要此权限才能访问 BigQuery。

gcloud auth application-default login

按照提示完成身份验证流程。

4. 配置环境和 BigQuery

运行设置脚本

  1. 运行环境设置脚本。此脚本会启用 BigQuery 和 Google 地图 API，并创建一个包含您的项目 ID 和 Maps API 密钥的 .env 文件。
chmod +x setup/setup_env.sh
./setup/setup_env.sh
  1. 运行 BigQuery 设置脚本。此脚本可自动执行以下操作：创建 Cloud Storage 存储分区、上传数据，以及预配 BigQuery 数据集和表。
chmod +x ./setup/setup_bigquery.sh
./setup/setup_bigquery.sh

脚本完成后，系统应会创建 mcp_bakery 数据集，并使用以下表填充该数据集：

  • 人口统计信息 - 按邮政编码划分的人口普查数据和人口特征。
  • bakery_prices - 各种烘焙食品的竞品价格和产品详情。
  • sales_history_weekly - 按商店和商品划分的每周销售业绩（数量和收入）。
  • foot_traffic - 按邮政编码和一天中的时间段划分的估计实体店客流量得分。
  1. 如需验证是否已创建数据集和表，请在您的 Google Cloud 项目中访问 BigQuery 控制台：

6bd0a0cd7522dd11.jpeg

5. 安装 ADK

现在，基础架构已准备就绪，接下来我们来创建一个虚拟 Python 环境，并为 ADK 安装所需的软件包。

  1. 创建虚拟环境：
python3 -m venv .venv
  1. 激活此虚拟环境：
source .venv/bin/activate
  1. 安装 ADK：
pip install "google-adk[mcp]"
  1. 前往代理目录：
cd adk_agent/

6. 检查 ADK 应用

点击 Cloud Shell 中的打开编辑器按钮，打开 Cloud Shell 编辑器，并查看 mcp/examples/launchmybakery 目录下的克隆代码库。

a940b7eaf3c9f4b3.png

代理代码已在 adk_agent/ 目录中提供。下面我们来了解一下解决方案结构：

launchmybakery/
├── data/                        # Pre-generated CSV files for BigQuery
├── adk_agent/                   # AI Agent Application (ADK)
│   └── mcp_bakery_app/          # App directory
│       ├── agent.py             # Agent definition
│       ├── tools.py             # Custom tools for the agent
│       └── .env                 # Project configuration (created by setup script)
├── setup/                       # Infrastructure setup scripts
└── cleanup/                     # Infrastructure cleanup scripts

mcp_bakery_app 中的关键文件：

  • agent.py：定义代理、其工具和模型 (Gemini 3.5 Flash) 的核心逻辑。
  • tools.py：包含所有自定义工具定义。
  • .env：包含设置脚本创建的项目配置和密钥（例如 API 密钥）。

1. MCP 工具集初始化：

现在，在编辑器中打开 adk_agent/mcp_bakery_app/tools.py，了解如何初始化 MCP 工具集。

为了让我们的智能体能够与 BigQuery 和 Google 地图通信，我们需要配置 Model Context Protocol (MCP) 客户端。

该代码使用 StreamableHTTPConnectionParams 与 Google 的远程 MCP 服务器建立安全连接。

def get_maps_mcp_toolset():
    dotenv.load_dotenv()
    maps_api_key = os.getenv('MAPS_API_KEY', 'no_api_found')
    
    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=MAPS_MCP_URL,
            headers={    
                "X-Goog-Api-Key": maps_api_key
            }
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools


def get_bigquery_mcp_toolset():   
        
    credentials, project_id = google.auth.default(
            scopes=["https://www.googleapis.com/auth/bigquery"]
    )

    credentials.refresh(google.auth.transport.requests.Request())
    oauth_token = credentials.token
        
    HEADERS_WITH_OAUTH = {
        "Authorization": f"Bearer {oauth_token}",
        "x-goog-user-project": project_id
    }

    tools = MCPToolset(
        connection_params=StreamableHTTPConnectionParams(
            url=BIGQUERY_MCP_URL,
            headers=HEADERS_WITH_OAUTH
        )
    )
    print("MCP Toolset configured for Streamable HTTP connection.")
    return tools
  • 地图工具集：使用您的 API 密钥配置与地图 MCP 服务器的连接。
  • BigQuery Toolset：此函数用于配置与 BigQuery MCP 服务器的连接。它使用 google.auth 自动检索您的 Cloud 凭据，生成 OAuth Bearer 令牌，并将其注入到授权标头中。

2. 代理定义：

现在，在编辑器中打开 adk_agent/mcp_bakery_app/agent.py，查看智能体的定义方式。

LlmAgent 使用 gemini-3.5-flash 模型进行初始化。

maps_toolset = tools.get_maps_mcp_toolset()
bigquery_toolset = tools.get_bigquery_mcp_toolset()

root_agent = LlmAgent(
    model='gemini-3.5-flash',
    name='root_agent',
    instruction=f"""
                Help the user answer questions by strategically combining insights from two sources:
                
                1.  **BigQuery toolset:** Access demographic (inc. foot traffic index), product pricing, and historical sales data in the  mcp_bakery dataset. Do not use any other dataset.
                Run all query jobs from project id: {project_id}. 

                2.  **Maps Toolset:** Use this for real-world location analysis, finding competition/places and calculating necessary travel routes.
                    Include a hyperlink to an interactive map in your response where appropriate.
            """,
    tools=[maps_toolset, bigquery_toolset]
)
  • 系统指令：系统会向代理提供具体指令，要求其整合来自 BigQuery（用于数据）和 Google 地图（用于位置分析）的数据洞见。
  • 工具：maps_toolset 和 bigquery_toolset 都分配给了智能体，使其能够使用这两项服务的功能。

智能体会遵循代码库中定义的指令和工具。您可以随意更改指令，看看它会如何影响代理的行为。

7. 与您的代理聊天！

返回 Cloud Shell 中的终端，然后运行以下命令以前往 adk_agent 目录（如果您尚未执行此操作）：

cd adk_agent/

运行以下命令以启动 ADK Web 界面。此命令会启动一个轻量级 Web 服务器来托管聊天应用：

adk web --allow_origins 'regex:https://.*\.cloudshell\.dev'

服务器启动后，您会在 Cloud Shell 中看到以下内容：

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

您可以通过以下两种方式访问 ADK 界面：

选项 1：点击本地链接 点击 Cloud Shell 终端中显示的 http://127.0.0.1:8000 链接。

方法 2：使用网页预览

  1. 点击 Cloud Shell 右上角的网页预览按钮。
  2. 选择更改端口。
  3. 输入 8000 作为端口号，然后点击更改并预览。

有关如何打开 ADK 界面的屏幕截图

在网页界面中提出以下问题，与智能体互动。您应该会看到相关工具被调用。

  1. 查找社区（宏）：“我想在洛杉矶开一家面包店。找到早晨实体店客流量得分最高的邮政编码。

ADK Web 回答：找到早晨人流量最高的社区

代理应使用 get_table_info 和 execute_sql 等工具查询 BigQuery 中的 foot_traffic 表。

  1. 验证位置信息（微）：“您能否搜索该邮政编码中的‘面包店’，看看该邮政编码是否已饱和？”

ADK Web 响应 - 验证邮政编码 90403 的烘焙市场饱和度

代理应使用 Google 地图工具集中的 search places 工具来回答此问题。

快来试试吧！不妨试试以下示例问题，看看您的 ADK 智能体的实际应用：

  • “我打算在洛杉矶开设第四家面包店。我需要一个清晨就充满活力的社区。找到“上午”实体店客流量得分最高的邮政编码。
  • “您能否在该邮政编码范围内搜索‘面包店’，看看是否已饱和？如果太多，请查找“精品咖啡”店，这样我就可以在这些店附近找个位置，吸引客流量。”
  • “好的，我想将此品牌定位为高端品牌。洛杉矶都会区“酸面包”的最高价格是多少？
  • “现在，我想获得 2025 年 12 月的收入预测。查看我的销售记录，并从效果最佳的商店中提取“酸面包”的数据。运行 2025 年 12 月的预测，以估算我将售出的数量。然后，使用我们找到的略低于高价的价格（假设为 18 美元）计算预计总收入”
  • “这样就能支付我的房租了。最后，我们来验证物流。找到距离建议区域最近的“Restaurant Depot”，并确保每天的补货车程不超过 30 分钟。”

测试完智能体后，您可以在 Cloud Shell 终端中按 Ctrl+C 来终止 ADK 网页界面。

8. 清理

为避免系统向您的 Google Cloud 账号持续收取费用，请删除在此 Codelab 中创建的资源。

运行清理脚本。此脚本将删除在设置期间创建的 BigQuery 数据集、Cloud Storage 存储分区和 API 密钥。

chmod +x ../cleanup/cleanup_env.sh
./../cleanup/cleanup_env.sh

9. 恭喜

任务完成！您已成功使用智能体开发套件 (ADK) 构建了地理位置智能体。

通过弥合 BigQuery 中的“企业”数据与 Google 地图 中的真实世界位置背景信息之间的差距，您创建了一个能够进行复杂业务推理的强大工具，而这一切都由 Model Context Protocol (MCP) 和 Gemini 提供支持。

您完成的任务：

  • 基础设施即代码：您使用 Google Cloud CLI 工具预配了数据堆栈。
  • MCP 集成：您将 AI 智能体连接到两个不同的远程 MCP 服务器（BigQuery 和 Maps），而无需编写复杂的 API 封装容器。
  • 统一推理：您构建了一个能够战略性地整合来自两个不同领域的洞见来解决业务问题的单一智能体。

参考文档