智能体的 Google 搜索 Grounding¶

Supported in ADKPython v0.1.0TypeScript v0.2.0Java v0.1.0

Google 搜索 Grounding 工具是 Agent Development Kit (ADK) 中的一项强大功能，可将你的 AI 智能体直接连接到 Google 搜索。通过让你的智能体访问来自网络的实时、权威信息，它们可以回答有关近期事件、当前天气、股票价格或任何其他超出模型训练窗口的动态数据的问题。智能体会自动决定何时进行搜索，并无缝地将结果纳入其响应中，并附带适当的引用。

创建一个 Grounded 智能体¶

要启用 Google 搜索 Grounding，你需要在智能体定义中包含搜索工具。

PythonTypeScriptJava

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

import { LlmAgent, GOOGLE_SEARCH } from '@google/adk';

const rootAgent = new LlmAgent({
    name: "google_search_agent",
    model: "gemini-2.5-flash",
    instruction: "必要时使用 Google 搜索回答问题。始终引用来源。",
    description: "具有 Google 搜索能力的专业搜索助手",
    tools: [GOOGLE_SEARCH],
});

import com.google.adk.agents.LlmAgent;
import com.google.adk.tools.GoogleSearchTool;

LlmAgent rootAgent = LlmAgent.builder()
    .name("google_search_agent")
    .model("gemini-2.5-flash")
    .instruction("必要时使用 Google 搜索回答问题。始终引用来源。")
    .description("具有 Google 搜索能力的专业搜索助手")
    .tools(GoogleSearchTool.INSTANCE)
    .build();

Google 搜索 Grounding 的工作原理¶

Grounding 是将你的智能体连接到来自网络的实时信息的过程，使其能够生成更准确、更及时的响应。当用户的提示词需要模型未曾训练过的信息或具有时效性的信息时，智能体底层的系统级大语言模型（LLM）会智能地决定调用 google_search 工具来查找相关事实。

数据流图¶

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

详细描述¶

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

用户查询 (User Query)：终端用户通过提问或给出命令与你的智能体进行交互。
ADK 编排 (ADK Orchestration)：Agent Development Kit 编排智能体的行为，并将用户的消息传递给智能体的核心。
LLM 分析与工具调用 (LLM Analysis and Tool-Calling)：智能体的 LLM（例如 Gemini 模型）分析提示词。如果它确定需要外部、最新的信息，它会通过调用 google search 工具触发 Grounding 机制。这非常适合回答有关近期新闻、天气或模型训练数据中不存在的事实。
Grounding 服务交互 (Grounding Service Interaction)：google search 工具与内部 Grounding 服务交互，该服务制定并向 Google 搜索索引发送一个或多个查询。
上下文注入 (Context Injection)：Grounding 服务检索相关的网页和代码段。然后，它在生成最终响应之前将这些搜索结果整合到模型的上下文中。这一关键步骤允许模型根据真实的实时数据进行“推理”。
生成 Grounded 响应 (Grounded Response Generation)：LLM 在获得新鲜搜索结果的信息后，生成一个包含所检索信息的响应。
带来源的响应呈现 (Response Presentation with Sources)：ADK 接收最终的 Grounded 响应（包含必要的来源 URL 和 groundingMetadata），并将其连同归因呈现给用户。这允许终端用户验证信息，并建立对智能体回答的信任。

理解错误响应与 Grounding 元数据¶

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

Grounded 响应示例¶

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

最终答案文本：

"是的，国际迈阿密在国际足联俱乐部世界杯的最后一场比赛中获胜。他们在第二场小组赛中以 2-1 击败了波尔图足球俱乐部。他们在锦标赛中的第一场比赛是与阿赫利足球俱乐部 0-0 平局。国际迈阿密计划在 2025 年 6 月 23 日星期一与帕尔梅拉斯队进行第三场小组赛。"

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": { ... }
}

如何解读响应¶

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

groundingChunks: 这是模型参考的网页列表。每个区块都包含网页标题和指向来源的 uri。
groundingSupports: 此列表将最终答案中的特定句子连接回 groundingChunks。
segment: 此对象标识最终文本答案的一个特定部分，由其 startIndex、endIndex 和文本本身定义。
groundingChunkIndices: 此数组包含与 groundingChunks 中列出的来源相对应的索引号。例如，句子 "他们在第二场小组赛中以 2-1 击败了波尔图足球俱乐部..." 由索引为 0 和 1 的 groundingChunks 中的信息支持。

如何显示 Google 搜索的 Grounding 响应¶

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

显示搜索建议¶

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

来自 searchEntryPoint 的渲染 HTML：元数据提供了渲染搜索建议栏所需的 HTML 和 CSS，其中包括 Google 徽标和相关查询的磁贴。将此 HTML 直接集成到应用程序的前端将按预期显示建议。

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