数据代理的集成模式

本页介绍了将数据代理体验嵌入到应用中的集成模式。这些模式的复杂程度各不相同，从嵌入式聊天组件到编排的多智能体系统不等。

本指南适用于设计生成式 AI 应用的云架构师和数据工程师。您应该对 Google Cloud 概念、Identity and Access Management 和 REST API 有基本的了解。您还应熟悉应用所使用的数据源的架构。

集成模式概览

本指南根据您的出发地分为以下主要轨道：

  • Looker 轨道：如果您想通过 Looker 嵌入、Looker API 或对话式分析 API 提供聊天功能，请选择此轨道。
  • BigQuery 和数据库轨道：如果您要构建使用 BigQuery、数据洞察或受支持的运营数据库的自定义应用，请选择此轨道。

下表总结了可用的集成模式：

集成模式 说明 数据源
Looker iframe 嵌入 只需极少的代码即可将标准聊天界面添加到应用中。 Looker
Looker API 和 SDK 构建使用 Looker API 进行身份验证的自定义聊天界面。 Looker
对话式分析 API（Looker 来源） 将 Looker 数据代理作为 Google Cloud 资源进行管理，这些资源可在多个平台和多代理系统中运行。 Looker
Direct API（单代理） 使用直接 API 集成来实现文本转答案流程。 BigQuery、数据库、Looker
直接 API（编排器） 通过函数调用在 API 和其他工具之间路由查询。 BigQuery、数据库、Looker
使用 BigQueryToolset 的 ADK（基于架构） 使用 ask_data_insights 工具根据表格引用快速生成数据洞见。 BigQuery
使用 DataAgentToolset 的 ADK（受监管） 查询使用 ask_data_agent 工具预配置的数据代理，以确保行为一致。 BigQuery、数据库、Looker
ADK（自定义流式传输） 支持使用自定义代理类实时流式传输图表和 SQL。 BigQuery、数据库、Looker
具有 McpToolset 或 ToolboxToolset 的 MCP 将应用连接到使用 Model Context Protocol (MCP) 的数据工具。 BigQuery Looker
A2A protocol 支持在不同系统上运行的专业代理之间进行安全协作。 依赖于框架

Looker 的集成选项

如果您使用 Looker，可以通过以下模式向用户提供 Looker 对话式分析：

Looker 集成模式摘要

下表总结了 Looker 的主要集成模式：

模式 适用场景 优点 注意事项
使用 iframe 嵌入：一种低代码方法，可快速将标准 Looker Chat 体验添加到应用中。 需要可用于生产用途的对话分析体验且自定义开发工作量极少的团队。
  • 只需植入极少的代码即可实现。
  • 自动强制执行现有的 Looker 安全模型。
  • 不需要单独的 Google Cloud 身份验证。
  • 支持 Looker Embed SDK，该 SDK 通过管理 iframe 生命周期和事件传递来加快开发速度。
  • 提供有限的界面自定义功能，并依赖于标准的 Looker Chat 界面。
  • 您的 Looker 实例必须由 Looker 托管。
使用 Looker API 和 SDK 构建：一种灵活的方法，可用于构建自定义聊天界面，同时将身份验证和代理管理保留在 Looker 中。 需要自定义聊天用户体验，但希望在 Looker 生态系统中保留用户身份验证和客服人员管理的团队。此模式非常适合已使用 Looker 嵌入或 API 的应用。
  • 提供单一身份验证层，并可完全控制用户界面。
  • 简化了现有 Looker 客户的架构。
  • 使用 Looker 语义层来提高查询准确性。
  • 不需要单独的 Google Cloud 身份验证。
  • 需要具备 Looker API 开发专业知识。
  • 仅限 Looker 数据源。
  • 代理在 Looker 中进行管理，无法迁移到其他 Google Cloud 服务。
使用对话式分析 API：直接与 API 集成，以将代理作为云级资源进行管理。 需要数据代理具有跨平台可移植性的 Looker 客户。
  • 确保数据代理可在所有 Google Cloud 平台之间移植。
  • 由 Identity and Access Management 集中管理。
  • 可让您将数据代理集成到 ADK 或 MCP 工作流中。
  • 要求您管理整个集成堆栈，包括 Google Cloud 和 Looker 身份验证。
  • 数据代理的运行独立于 Looker 界面。

使用 iframe 嵌入

您可以将对话式分析功能嵌入为 iframe，以便在 Looker 界面之外提供聊天体验。此模式可直接提供对话式分析功能，无需进行自定义界面开发、后端编排或 API 状态管理。如需使用此模式，您需要在应用中添加预先设置好格式的网址。

Looker Embed SDK 提供了一些工具，用于管理安全网址生成、iframe 生命周期管理以及主机应用与 iframe 之间的 JavaScript 事件传递等任务。您可以通过在应用中添加预先设置格式的网址，嵌入代理页面、对话页面或特定对话。

您可以针对嵌入式内容使用以下身份验证方法：

  • 私密嵌入：使用用户现有的 Looker 凭据对用户进行身份验证。当您将嵌入网址设置为 iframe 源时，用户会使用其 Looker 账号登录。此方法会自动强制执行现有角色、内容访问权限和数据级权限（例如访问过滤条件或访问授权），而无需额外的 Identity and Access Management 配置或令牌映射。
  • 已签名的嵌入：通过单点登录 (SSO) 使用您的应用对用户进行身份验证。您可以构建一个包含对话式分析内容路径的签名网址，以便动态指定要授予的确切权限。

使用 Looker API 和 SDK 进行构建

如需更灵活的聊天体验，您可以使用 Looker API 中的 ConversationalAnalytics 方法，也可以使用 Looker SDK 构建自定义应用。借助此方法，您可以构建直接与 Looker 端点通信的自定义前端。

与 Looker API 集成可带来以下好处：

  • 您只需管理 Looker 的身份验证。无需单独向对话式分析 API 进行身份验证。
  • 对于已使用 Looker 嵌入或 API 的应用，此模式可避免使用辅助身份验证机制，并省去管理外部数据代理的麻烦，从而简化项目架构。
  • 您可以完全控制聊天界面、对话流程以及应用呈现结果（例如图表和表格）的方式。

如需参考实现，请参阅 GitHub 上的对话式分析 Looker API 指南。

将对话式分析 API 与 Looker 数据搭配使用

如果您需要执行以下任何任务，可以直接与 geminidataanalytics.googleapis.com 的对话式分析 API 集成：

  • 在多个 Google Cloud 平台（例如自定义 Web 应用、Google Chat 和 Gemini Enterprise）之间共享同一数据代理
  • 在单个多代理系统中将 Looker 数据源与 BigQuery 或运营数据库源相结合
  • 将数据代理作为由 Identity and Access Management 而非 Looker 权限模型管理的云级资源进行管理

如需详细了解对话式分析 API 的常见架构模式，请参阅 BigQuery 和数据库的集成选项。

BigQuery 和数据库的集成选项

本部分介绍了使用 BigQuery、数据洞察或受支持的 Google Cloud 运营型数据库通过 Conversational Analytics API 构建自定义体验的应用的架构模式。

如果您将 对话式分析 API 与 Looker 数据源搭配使用，本部分中描述的模式也适用于您的集成。

对话式分析 API 提供了以下与数据互动的主要方法：

  • chat 方法：支持 BigQuery、Looker、数据洞察和运营型数据库。
  • queryData 方法：支持 AlloyDB、GoogleSQL for Spanner、Cloud SQL for MySQL 和 Cloud SQL for PostgreSQL 等运营型数据库。

构建自定义应用时，您可以使用以下一种或多种集成模式：

  • 直接 API 集成：一种自定义方法，可提供最大的灵活性，但需要您构建用于身份验证、对话管理和响应解析的基础设施。
  • 框架驱动的编排 (ADK)：一种使用智能体开发套件 (ADK) 进行多智能体路由、工具执行和状态管理的方法。
  • 垂直集成 (MCP)：一种使用 Model Context Protocol (MCP) 的方法，可提供一种统一的方式来将 AI 应用连接到不同环境中的工具和数据源。
  • 横向编排 (A2A)：一种使用 Agent-to-Agent (A2A) 协议的方法，可让不同系统上的专业代理安全地协作，而无需自定义集成代码。

BigQuery 和数据库集成模式摘要

下表总结了 BigQuery 和运营数据库的具体实现模式：

模式 适用场景 优点 注意事项
单代理集成（直接 API）：一种模式，其中您的应用直接调用 API 以从数据源返回数据分析。 需要直接控制每次 API 调用的单代理应用、原型或微服务。
  • 提供精细的控制，且没有框架依赖项。
  • 为单智能体应用场景提供最简单的架构。
  • 同时支持有状态模式和无状态模式。
  • 需要您构建用于身份验证、状态管理、响应解析、错误处理、流式传输和部署的所有基础设施。
  • 无法很好地扩展到多代理场景。
自定义编排程序（直接 API）：一种使用根代理和函数调用在对话式分析 API 与其他工具或服务之间路由查询的模式。 在单个对话流程中将数据查询与其他任务（例如电子邮件或文档）相结合的应用。
  • 提供最大的编排控制，且没有框架依赖项。
  • 可让您准确定义模型在工具之间的路由方式。
  • 适用于任何 Gemini 模型。
  • 需要您手动管理工具定义、对话循环、多轮状态、错误处理和部署。
  • 与使用 ADK 等框架相比，开发开销可能会变得繁重。
基于架构的与 BigQueryToolset (ADK) 的集成：一种使用表引用快速返回数据洞见的模式。 快速原型设计、数据治理不太重要的内部工具，或者数据洞见是 ADK 代理中的多项功能之一的场景。
  • 在 ADK 框架内提供最快的集成途径。
  • 无需预先配置数据代理。
  • 直接使用数据库表名称。
  • 缺乏语义治理，仅通过架构推理生成 SQL。
  • 在 API 级别以无状态模式运行。
  • 仅提供纯文本答案，不支持图表。
与 DataAgentToolset (ADK) 的受监管集成：一种通过引用预配置的数据代理的 ID 来查询该代理的模式。 需要一致数据访问权限的生产环境应用，或数据智能体是可信、可重用组件的多智能体系统。
  • 提供语义治理，并在所有消费者之间保持一致的行为。
  • 通过使用经过验证的查询和业务术语库来提高准确性。
  • 确保数据代理可在 ADK、MCP 和直接 API 集成中重复使用。
  • 需要您预先配置数据代理资源。
  • 在 API 级别以无状态模式运行。
  • 仅返回纯文本答案，不支持图表。
自定义子代理 (ADK)：一种使用自定义代理类直接连接到 API 并将数据块流式传输回用户的模式。 以低响应延迟为优先事项的用户界面应用，或数据检索可为下游代理提供信息的多代理流水线。
  • 提供实时流式反馈。
  • 访问所有类型的回答，例如图表、表格和 SQL。
  • 可通过会话状态与其他 ADK 代理组合。
  • 需要投入更多开发精力来构建自定义 ADK 代理类。
  • 需要您直接管理流式传输连接和响应解析。
Model Context Protocol (MCP)：一种使用开放标准将 AI 应用连接到不同环境中的数据源和工具的模式。 需要跨多个 AI 客户端和 IDE 实现工具互操作性的组织，或者需要从 ADK 框架、IDE 和自定义应用访问相同数据工具的团队。
  • 使用可与任何符合 MCP 标准的客户端搭配使用的通用工具标准。
  • 将工具实现与消费类应用分离。
  • 提供托管式服务器选项，例如 Google Cloud MCP 服务器。
  • 需要为工具箱服务器添加一个额外的基础架构层。
  • 与智能体开发套件 (ADK) 工具集相比，集成度较低。
  • 取决于不断发展的 MCP Toolbox 生态系统。
  • 以无状态模式运行，需要您在外部管理多轮对话状态。
Agent-to-Agent (A2A)：一种使用 A2A protocol 的模式，该协议是一种开放标准，可让不同系统上的专业代理安全地协作，而无需自定义集成代码。 高度分布式的企业环境，其中中央路由代理必须将任务委托给在不同系统或网络上运行的数据代理。
  • 减少了在不同框架之间使用自定义集成代码的需求。
  • 确保跨平台互操作性顺畅无缝。
  • 提供安全且标准化的功能发现。
  • 与内部子代理相比，引入的网络延迟时间较短。
  • 需要您配置 A2A 服务器设置。

直接 API 集成

直接 API 集成可让您精细控制应用的逻辑和架构，但需要您构建支持性基础架构。采用这种方法时，您需要负责身份验证、对话管理、响应解析和部署等任务。

本部分包含以下主题：

  • 单代理集成：一种模式，其中应用直接调用对话式分析 API 以从数据源返回数据分析。
  • 自定义编排器集成：一种高级模式，使用根代理和函数调用在对话式分析 API 之间路由查询。

单代理集成

通过单代理集成，您的后端可以使用 REST 或客户端库直接调用对话式分析 API，并传递用户的查询和上下文。此模式适用于低复杂度的应用，例如使用简单文本转答案流程的 Web 应用、内部聊天工具或微服务。您还可以使用此方法进行原型设计和概念验证工作。

此模式同时支持有状态聊天（Google 管理对话历史记录）和无状态聊天（您的应用管理历史记录）。

如需参考实现，请参阅 GitHub 上的 对话式分析 API 快速入门或 对话式分析 API 黄金版演示。

自定义编排器集成

采用这种方法，您可以构建一个充当应用主要入口点和协调器的根代理。根代理使用标准 Gemini 模型，该模型通过函数调用配备了工具。当用户提出与数据相关的问题时，根代理会向对话式分析 API 发出工具调用，接收结果，然后继续推理或调用下游的其他工具。

函数调用涉及以下阶段：

  1. 声明：将工具架构定义为包含参数定义的 FunctionDeclaration 对象。
  2. 调用：模型会返回包含函数名称和实参的结构化 functionCall 消息。
  3. 执行：您的应用执行 API 调用，并在 FunctionResponse 消息中返回结果。
  4. 合成：Gemini 模型使用结果生成最终答案或确定下一步行动。

这种方法适用于用户可能在执行其他任务的同时请求数据分析的应用。例如，用户可能会要求代理“显示销售数据，然后起草一封发送给销售团队的电子邮件”。根代理可以将数据问题路由到对话式分析 API，并使用其他工具来处理非数据任务。

如需查看参考实现，请参阅 GitHub 上对话式分析 API 黄金版演示中的 orchestrate 或 multimodal 页面。

框架驱动的编排 (ADK)

智能体开发套件 (ADK) 是一个代码优先的框架，用于构建 AI 智能体，可管理多智能体路由、工具执行和状态管理的复杂性。ADK 框架与 Gemini Enterprise 所用的框架相同。

通过使用 ADK，您可以将对话式分析 API 与其他工具和代理链接起来，以执行复杂的操作。

本部分包含以下主题：

基于架构与 BigQueryToolset 的集成

ADK 框架中的 BigQueryToolset 工具集包含预构建的 ask_data_insights 工具。如需使用此工具，您需要将表名称和用户的问题传递给该工具，然后该工具会使用内嵌上下文调用对话式分析 API。

当您调用该工具时，它会向对话式分析 API 发送包含指定 BigQuery 表引用的无状态请求。该 API 会推断数据库架构，生成并执行 SQL 查询，然后返回文本答案。然后，结果会作为工具响应传递回 ADK 代理。

此模式可用于快速向代理添加对话式分析功能。不过，由于对 API 的调用是无状态的，并且缺乏治理，因此 API 会完全根据表架构生成 SQL，而没有语义防护措施。这使得该模式的部署速度更快，但对于应用命名惯例、业务逻辑或访问控制的生产业务逻辑而言，风险更高。

受管控的与 DataAgentToolset 的集成

ADK 框架中的 DataAgentToolset 工具集提供了一种预构建的集成，可通过 ID 引用预配置的数据代理。ADK 代理会将用户的问题传递给 ask_data_agent 工具，该工具会使用指定的数据代理上下文调用对话式分析 API。

您可以使用对话式分析 API 以程序化方式创建数据代理，也可以通过 Google Cloud 控制台中的代理目录创建数据代理。数据代理配备了以下组件：

  • 知识来源：智能体可以查询的表、视图或用户定义函数 (UDF)
  • 结构化上下文：有助于智能体了解底层数据的表和列说明
  • 指令：为代理提供额外指导，以便其解读和查询数据源
  • 经过验证的查询：经过预验证的 SQL 查询，可作为常见问题的示例
  • 词汇表：有助于代理了解特定领域语言的业务术语定义

如需获取有关通过代理目录创建代理的深入指南，请参阅 BigQuery 中的对话式分析 Codelab。

由于代理被定义为受控单元，因此无论哪个应用或分代理调用它，它都使用相同的可信逻辑、上下文和安全措施。

通过自定义子代理实现高级用户体验集成

BigQueryToolset 和 DataAgentToolset 工具集在 API 请求完成处理之前不会向用户返回结果。由于 ADK 框架将 API 视为在完成之前会阻止响应的工具，因此长时间运行的查询可能会导致用户没有反馈。

对于响应延迟时间较短的应用或数据检索会为下游代理提供信息流的应用，您可以构建一个直接连接到对话式分析 API 的自定义 ADK 代理类，并以块的形式将数据异步流式传输回用户。此模式支持以下响应类型（在生成时）：

  • “思考”消息：数据智能体在解读问题时的推理过程。
  • 进度消息：数据源在数据检索期间的状态更新。
  • 查询生成：生成的 SQL 或 Looker 查询，以流式传输方式提供。
  • 数据：JSON 格式的数据结果。
  • 可视化图表：Vega-Lite 图表规范。
  • 摘要：最终的基于文本的回答。

如需查看返回的数据类型的完整列表，请参阅 API 参考文档中的 SystemMessage 类型。

这种异步方法可确保用户不必等待复杂的数据检索过程完全完成。当数据代理在查询过程中流动时，它会不断将增量更新（例如文本摘要、原始数据或图表配置）分享到临时共享工作区。然后，系统可以实时向用户呈现这些数据，并与专业子代理共享这些数据以执行其他任务。

如需查看包含根代理、数据分代理和可视化代理的参考实现，请参阅 GitHub 上的 ADK 流式传输演示。

垂直集成 (MCP)

Model Context Protocol (MCP) 是一种开放标准，可为 AI 应用提供一种统一的方式来连接到外部工具和数据源。MCP 可标准化 AI 模型与其所用工具之间的接口。

本部分包含以下主题：

MCP Toolbox for Databases

虽然没有专门的对话式分析 API MCP 服务器，但您可以通过 MCP Toolbox for Databases 服务器访问该 API。此开源服务器提供预构建的 MCP 兼容工具，这些工具可公开对话式分析 API 中的 chat 方法：

MCP 是一个互操作性层，可将分析能力作为工具向兼容 MCP 的客户端公开，而不是对话式分析 API 的单独执行模型。

独立架构和 ADK 架构的 MCP 实现模式

您可以通过以下模式实现 MCP：

模式 详细信息
独立 MCP（不含 ADK）

将 MCP Toolbox for Databases 服务器用作独立服务器，以连接到任何符合 MCP 标准的客户端。此模式通常用于以下任务：

  • IDE 集成：将 IDE（例如 Antigravity、Cursor 或 VS Code）连接到服务器，以便在编辑器中以对话方式查询数据。
  • 自定义 MCP 客户端：构建一个应用，该应用使用服务器在多个 AI 提供商之间提供统一的工具接口。
  • Gemini CLI：将该 CLI 用作基于终端的数据对话的 MCP 客户端。
ADK 中的 MCP

ADK 框架提供以下机制，用于将 MCP 服务器集成到代理工作流中：

  • ToolboxToolset：MCP Toolbox for Databases 服务器的专用变体，支持多种身份验证方法。
  • McpToolset：通过本地或远程 MCP 服务器连接将 ADK 代理连接到任何 MCP 服务器。自动发现服务器的工具并将其公开给代理。

您还可以使用 FastMCP 框架构建 MCP 服务器，以向任何符合 MCP 标准的客户端公开使用 ADK 框架构建的工具。此方法可让您的 ADK 智能体在其他生态系统中作为工具使用。

根据应用的具体架构要求选择集成模式：

  • 使用内置的智能体开发套件 (ADK) 工具集（例如 BigQueryToolset 或 DataAgentToolset）可实现更紧密的集成，而无需外部服务器依赖项。此方法非常适合完全在 ADK 框架内运行的系统。
  • 使用 MCP Toolbox 中的工具可实现符合 MCP 规范的客户端之间的互操作性。此方法非常适合必须为多个消费类应用或第三方 IDE 提供服务的数据工具。

横向编排 (A2A)

Agent-to-Agent (A2A) protocol 是一种开放标准，可让不同系统上的专业代理安全地通信和协作，而无需自定义集成代码。

随着系统规模的扩大，组织通常会部署基于不同框架或云基础架构构建的多个专业智能体。A2A 为这些自主代理建立了一个通用消息传递层。每个代理都会发布一个代理卡片，而不是使用自定义 API。代理卡片是一个可发现的个人资料，其中详细介绍了代理的功能、支持的数据格式和安全要求。

当中央编排器或对等代理需要分析数据时，它会通过结构化 A2A 消息将任务安全地委托给数据代理。数据代理会自主处理请求并返回发现结果，从而将执行逻辑与请求者分离。

选择集成模式

您可以使用下表比较每种集成模式的复杂性、治理和功能。

复杂程度的定义如下：

  • 低：需要最少的自定义代码，并依赖于预构建的界面或工具的模式。
  • 中等：需要自定义前端开发和 API 或 SDK 集成，但避免了复杂的后端编排基础架构的模式。
  • 高：需要全栈应用开发、对话状态管理、多个身份验证层或中级编排器基础架构的模式。
  • 可变：复杂程度取决于您选择的基础集成方法的模式。
集成模式 复杂性 自定义 智能体治理 访问权限控制 多智能体 流式 可移植性
Looker iframe 嵌入 低 低 通过 Looker 进行管理 Looker 否 内置 仅限 Looker
Looker API 和 SDK 中 高 通过 Looker 进行管理 Looker 否 内置 仅限 Looker
使用 Looker 源的对话式分析 API 不定 高 通过 API 进行管理 Looker 和 IAM 是 是 任何 Google Cloud 表面
单代理（直接 API） 中 高 通过 API 进行管理 IAM 否 是（支持） 任何 Google Cloud 表面
自定义编排程序 高 很高 通过 API 进行管理 IAM 手动 手动 任何 Google Cloud 表面
基于架构，使用 BigQueryToolset (ADK) 低 中 无（架构推理） IAM 是 (ADK) 否（阻塞） ADK 生态系统
由 DataAgentToolset (ADK) 管理 低 中 通过 API 进行管理 IAM 是 (ADK) 否（阻塞） ADK 生态系统
自定义流式分代理 (ADK) 高 很高 通过 API 进行管理 IAM 是 (ADK) 是（自定义） ADK 生态系统
独立 MCP 中 中 无（架构推理） IAM 否 否 任何 MCP 客户端
ADK 中的 MCP 中 高 无（架构推理） IAM 是 (ADK) 否 ADK 和 MCP 客户端
A2A 协议 高 高 依赖于框架 IAM 是 是 跨平台

后续步骤