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

1. 简介

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

该代理会协调用户与 Google Cloud 服务之间的请求，以解决与虚构的烘焙店数据集相关的业务问题。

82dd7bd2823a821b.png

实践内容

  • 设置数据：在 BigQuery 中创建基础烘焙店数据集。
  • 开发智能体：使用智能体开发套件 (ADK) 构建智能体。
  • 集成工具：通过 MCP 服务器为智能体配备 BigQuery 和 Google 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
  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.0 Pro 预览版）的核心逻辑。
  • tools.py：包含所有自定义工具定义。
  • .env：包含设置脚本创建的项目配置和 Secret（例如 API 密钥）。

1. MCP 工具集初始化：

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

为了让我们的代理能够与 BigQuery 和 Google 地图通信，我们需要配置模型上下文协议 (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 密钥配置与 Maps MCP 服务器的连接。
  • BigQuery Toolset：此函数用于配置与 BigQuery MCP 服务器的连接。它使用 google.auth 自动检索您的 Cloud 凭据，生成 OAuth Bearer 令牌，并将其注入到授权标头中。

2. 代理定义：

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

LlmAgent 使用 gemini-3-pro-preview 模型进行初始化。

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

root_agent = LlmAgent(
    model='gemini-3-pro-preview',
    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

服务器启动后，您可以点击提供的网址启动 ADK Web 界面，与代理聊天。

与代理互动，提出以下问题。您应该会看到相关工具被调用。

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

5f2a48bebfc49709.png

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

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

32796c9a8cefca7.png

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

快来试试吧！不妨试试以下示例问题，看看您的 ADK 智能体如何运作：

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

8. 清理

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

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

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

9. 恭喜

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

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

您取得的成就：

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

参考文档