理解 Google 搜索 Grounding

Google Search Grounding tool is a powerful feature in the Agent Development Kit (ADK) that enables AI agents to access real-time, authoritative information from the web. By connecting your agents to Google Search, you can provide users with up-to-date answers backed by reliable sources.

此功能对于需要当前信息的查询特别有价值，如天气更新、新闻事件、股票价格，或任何自模型训练数据截止以来可能发生变化的事实。当你的智能体确定需要外部信息时，它会自动执行网络搜索，并将结果适当归因地纳入其响应中。

你将学到什么

在本指南中，你将了解：

• 快速设置：如何从头开始创建和运行启用 Google 搜索的智能体
• Grounding 架构：网络 grounding 背后的数据流和技术过程
• 响应结构：如何解释 grounded 响应及其元数据
• 最佳实践：向用户显示搜索结果和引用的指南

Additional resource

As an additional resource, Gemini Fullstack Agent Development Kit (ADK) Quickstart has a great practical use of the Google Search grounding as a full stack application example.

Google Search Grounding Quickstart

本快速入门指导你创建一个具有 Google 搜索 grounding 功能的 ADK 智能体。本快速入门假设有本地 IDE（VS Code 或 PyCharm 等）和 Python 3.9+ 及终端访问。

1. 设置环境并安装 ADK

创建并激活虚拟环境：

# 创建
python -m venv .venv

# 激活（每个新终端）
# macOS/Linux: source .venv/bin/activate
# Windows CMD: .venv\Scripts\activate.bat
# Windows PowerShell: .venv\Scripts\Activate.ps1

安装 ADK：

pip install google-adk==1.4.2

2. 创建智能体项目

在项目目录下，运行以下命令：

# 步骤 1：为你的智能体创建一个新目录
mkdir google_search_agent

# 步骤 2：为智能体创建 __init__.py
echo "from . import agent" > google_search_agent/__init__.py

# 步骤 3：创建 agent.py（智能体定义）和 .env（Gemini 认证配置）
touch google_search_agent/agent.py .env

编辑 agent.py

将以下代码复制并粘贴到 agent.py 中：

google_search_agent/agent.py

from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="google_search_agent",
    model="gemini-2.5-flash",
    instruction="需要时使用 Google 搜索回答问题。始终引用来源。",
    description="具有 Google 搜索功能的专业搜索助手",
    tools=[google_search]
)

现在你应该有以下目录结构：

my_project/
    google_search_agent/
        __init__.py
        agent.py
    .env

3. 选择平台

要运行智能体，你需要选择智能体将用于调用 Gemini 模型的平台。从 Google AI Studio 或 Vertex AI 中选择一个：

Gemini - Google AI StudioGemini - Google Cloud Vertex AI

1. 从 Google AI Studio 获取 API 密钥。

2. 使用 Python 时，打开 .env 文件并复制粘贴以下代码。

   .env

   GOOGLE_GENAI_USE_VERTEXAI=FALSE
   GOOGLE_API_KEY=PASTE_YOUR_ACTUAL_API_KEY_HERE
   

3. 将 PASTE_YOUR_ACTUAL_API_KEY_HERE 替换为你的实际 API KEY。

1. 你需要一个现有的 Google Cloud 账户和一个 项目。
   • 设置一个 Google Cloud 项目
   • 设置 gcloud CLI
   • 从终端运行 gcloud auth login 认证到 Google Cloud。
   • 启用 Vertex AI API。

2. 使用 Python 时，打开 .env 文件并复制粘贴以下代码，更新项目 ID 和位置。

   .env

   GOOGLE_GENAI_USE_VERTEXAI=TRUE
   GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
   GOOGLE_CLOUD_LOCATION=LOCATION
   

4. 运行你的智能体

有多种方式与你的智能体交互：

开发 UI (adk web)终端 (adk run)

运行以下命令启动 开发 UI。

adk web

Windows 用户注意

当遇到 _make_subprocess_transport NotImplementedError 时，考虑使用 adk web --no-reload。

步骤 1： 直接在浏览器中打开提供的 URL（通常是 http://localhost:8000 或 http://127.0.0.1:8000）。

步骤 2。 在 UI 的左上角，你可以在下拉菜单中选择你的智能体。选择 "google_search_agent"。

故障排除

如果你在下拉菜单中看不到 "google_search_agent"，请确保你在智能体文件夹的 父文件夹中运行 adk web（即 google_search_agent 的父文件夹）。

步骤 3。 现在你可以使用文本框与你的智能体聊天。

运行以下命令，与你的天气智能体聊天。

adk run google_search_agent

要退出，使用 Cmd/Ctrl+C。

📝 可尝试的示例提示

通过这些问题，你可以确认智能体实际上在调用 Google 搜索 来获取最新的天气和时间信息。

• 纽约的天气如何？
• 纽约现在几点？
• 巴黎的天气如何？
• 巴黎现在几点？

你已经成功创建并与使用 ADK 的 Google 搜索智能体进行了交互！

Google 搜索 grounding 的工作原理

Grounding 是将你的智能体连接到来自网络的实时信息的过程，使其能够生成更准确和最新的响应。当用户的提示需要模型未经训练的信息，或时间敏感的信息时，智能体的底层大语言模型会智能地决定调用 google_search 工具来找到相关事实。

数据流图

此图说明了用户查询如何逐步产生 grounded 响应的过程。

详细描述

grounding 智能体使用图中描述的数据流来检索、处理和将外部信息纳入呈现给用户的最终答案中。

1. 用户查询：最终用户通过询问问题或给出命令与你的智能体交互。
2. ADK 编排：Agent Development Kit 编排智能体的行为，并将用户的消息传递给智能体的核心。
3. LLM 分析和工具调用：智能体的 LLM（例如，Gemini 模型）分析提示。如果它确定需要外部的最新信息，它通过调用 google_search 工具触发 grounding 机制。这对于回答关于最近新闻、天气或模型训练数据中不存在的事实的查询是理想的。
4. Grounding 服务交互：google_search 工具与内部 grounding 服务交互，该服务制定并向 Google 搜索索引发送一个或多个查询。
5. 上下文注入：grounding 服务检索相关的网页和片段。然后在生成最终响应之前，将这些搜索结果集成到模型的上下文中。这个关键步骤允许模型在事实性、实时数据上进行"推理"。
6. Grounded 响应生成：LLM 现在了解新鲜的搜索结果，生成包含检索信息的响应。
7. 带来源的响应呈现：ADK 接收最终的 grounded 响应，其中包括必要的来源 URL 和 groundingMetadata，并将其带归因地呈现给用户。这允许最终用户验证信息并建立对智能体答案的信任。

理解 Google 搜索 grounding 响应

当智能体使用 Google 搜索来 ground 响应时，它返回一组详细信息，不仅包括最终文本答案，还包括用于生成该答案的来源。此元数据对于验证响应和为原始来源提供归因至关重要。

Grounded 响应示例

以下是 grounded 查询后模型返回的内容对象示例。

最终答案文本：

"是的，Inter Miami 在 FIFA 俱乐部世界杯中赢了他们的上一场比赛。他们在第二场小组赛中以 2-1 击败了 FC Porto。他们在锦标赛中的第一场比赛是与 Al Ahly FC 0-0 平局。Inter Miami 计划在周一，2025 年 6 月 23 日与 Palmeiras 进行他们的第三场小组赛。"

Grounding 元数据片段：

"groundingMetadata": {
  "groundingChunks": [
    { "web": { "title": "mlssoccer.com", "uri": "..." } },
    { "web": { "title": "intermiamicf.com", "uri": "..." } },
    { "web": { "title": "mlssoccer.com", "uri": "..." } }
  ],
  "groundingSupports": [
    {
      "groundingChunkIndices": [0, 1],
      "segment": {
        "startIndex": 65,
        "endIndex": 126,
        "text": "他们在第二场小组赛中以 2-1 击败了 FC Porto。"
      }
    },
    {
      "groundingChunkIndices": [1],
      "segment": {
        "startIndex": 127,
        "endIndex": 196,
        "text": "他们在锦标赛中的第一场比赛是与 Al Ahly FC 0-0 平局。"
      }
    },
    {
      "groundingChunkIndices": [0, 2],
      "segment": {
        "startIndex": 197,
        "endIndex": 303,
        "text": "Inter Miami 计划在周一，2025 年 6 月 23 日与 Palmeiras 进行他们的第三场小组赛。"
      }
    }
  ],
  "searchEntryPoint": { ... }
}

如何解释响应

元数据提供了模型生成的文本与支持它的来源之间的链接。这里是逐步分解：

1. groundingChunks：这是模型咨询的网页列表。每个块包含网页的标题和链接到来源的 uri。
2. groundingSupports：此列表将最终答案中的特定句子连接回 groundingChunks。
3. segment：此对象标识最终文本答案的特定部分，由其 startIndex、endIndex 和文本本身定义。
4. groundingChunkIndices：此数组包含对应于 groundingChunks 中列出的来源的索引号。例如，句子"他们以 2-1 击败了 FC Porto..."由 groundingChunks 中索引 0 和 1 的信息支持（都来自 mlssoccer.com 和 intermiamicf.com）。

如何显示 Google 搜索的 grounding 响应

使用 grounding 的关键部分是正确显示信息，包括引用和搜索建议，给最终用户。这建立了信任并允许用户验证信息。

显示搜索建议

groundingMetadata 中的 searchEntryPoint 对象包含用于显示搜索查询建议的预格式化 HTML。如示例图片中所示，这些通常呈现为可点击的标签，允许用户探索相关主题。

来自 searchEntryPoint 的渲染 HTML： 元数据提供必要的 HTML 和 CSS 来渲染搜索建议栏，其中包括 Google 标志和相关查询的标签，如"下一届 FIFA 俱乐部世界杯何时举行"和"Inter Miami FIFA 俱乐部世界杯历史"。将此 HTML 直接集成到你的应用程序前端将按预期显示建议。

有关更多信息，请参阅 Vertex AI 文档中的使用 Google 搜索建议。

总结

Google 搜索 Grounding 将 AI 智能体从静态知识库转变为能够提供实时、准确信息的动态、网络连接助手。通过将此功能集成到你的 ADK 智能体中，你使它们能够：

• 访问超出其训练数据的当前信息
• 为透明度和信任提供来源归因
• 提供具有可验证事实的全面答案
• 通过相关搜索建议增强用户体验

grounding 过程无缝地将用户查询连接到 Google 的庞大搜索索引，用最新上下文丰富响应，同时保持对话流程。通过正确实施和显示 grounded 响应，你的智能体成为信息发现和决策制定的强大工具。