資料代理程式的整合模式

本頁面說明如何將資料代理程式體驗嵌入應用程式的整合模式。這些模式的複雜程度不一，從嵌入式聊天元件到自動調度管理的多代理系統都有。

本指南適用於設計生成式 AI 應用程式的雲端架構師和資料工程師。您應對 Google Cloud 概念、身分與存取權管理 (IAM) 和 REST API 有基本瞭解。您也應熟悉應用程式使用的資料來源架構。

整合模式總覽

本指南分為下列主要軌道，每個軌道都以您的起點為基礎：

  • Looker 軌：如要透過 Looker 嵌入、Looker API 或 Conversational Analytics API 提供即時通訊功能，請選取這個軌。
  • BigQuery 和資料庫軌：如果您要建構使用 BigQuery、數據分析或支援的運作資料庫的自訂應用程式，請選取這個軌。

下表列出可用的整合模式：

整合模式 說明 資料來源
Looker iframe 嵌入 在應用程式中加入標準即時通訊介面，所需程式碼極少。 Looker
Looker API 和 SDK 建構自訂聊天介面，並使用 Looker API 進行驗證。 Looker
對話式數據分析 API (Looker 來源) 以 Google Cloud 資源的形式管理 Looker 資料代理，可在多個平台和多代理系統中運作。 Looker
直接 API (單一代理程式) 使用直接 API 整合，進行文字轉語音流程。 BigQuery、資料庫、Looker
直接 API (協調器) 使用函式呼叫在 API 和其他工具之間傳送查詢。 BigQuery、資料庫、Looker
ADK (架構導向) 搭配 BigQueryToolset 使用 ask_data_insights 工具，從表格參照快速產生洞察資料。 BigQuery
ADK (受控) 搭配 DataAgentToolset 查詢使用 ask_data_agent 工具的預先設定資料代理程式，確保行為一致。 BigQuery、資料庫、Looker
ADK (自訂串流) 使用自訂代理程式類別，支援圖表和 SQL 的即時串流。 BigQuery、資料庫、Looker
MCP (搭配 McpToolset 或 ToolboxToolset) 將應用程式連結至使用 Model Context Protocol (MCP) 的資料工具。 BigQuery Looker
A2A 通訊協定 讓在不同系統上運作的專業代理安全協作。 架構相依

Looker 的整合選項

如果您使用 Looker，可以透過下列模式為使用者提供 Looker 對話式數據分析：

Looker 整合模式摘要

下表摘要說明 Looker 的主要整合模式：

模式 適用情境 優點 注意事項
使用 iframe 嵌入：這是一種低程式碼方法，可快速在應用程式中加入標準的 Looker 即時通訊體驗。 需要具備可供正式環境使用的對話式數據分析體驗，且自訂開發作業最少。
  • 導入時幾乎不需要編寫程式碼。
  • 自動強制執行現有的 Looker 安全性模型。
  • 不需要另外 Google Cloud 驗證。
  • 支援 Looker Embed SDK，可管理 iframe 生命週期和事件傳遞，加快開發速度。
  • 提供有限的 UI 自訂功能，且取決於標準的 Looker 即時通訊使用者介面。
  • Looker 執行個體必須由 Looker 代管。
使用 Looker API 和 SDK 建構：這種做法十分彈性，可建構自訂的即時通訊介面，同時在 Looker 中進行驗證和代理管理。 需要自訂即時通訊使用者體驗，但希望在 Looker 生態系統中保留使用者驗證和服務專員管理功能的團隊。這個模式非常適合已使用 Looker 嵌入或 API 的應用程式。
  • 提供單一驗證層，並完全控管使用者介面。
  • 簡化現有 Looker 客戶的架構。
  • 使用 Looker 語意層提高查詢準確度。
  • 不需要另外 Google Cloud 驗證。
  • 需要具備 Looker API 開發專業知識。
  • 僅限 Looker 資料來源。
  • 代理程式是在 Looker 中管理，無法移至其他 Google Cloud 服務。
使用 Conversational Analytics API：直接與 API 整合，將代理程式視為雲端層級資源進行管理。 需要資料代理程式跨平台可攜性的 Looker 客戶。
  • 確保資料代理程式可在所有 Google Cloud 介面之間轉移。
  • 由 IAM 集中管理。
  • 可將資料代理整合至 ADK 或 MCP 工作流程。
  • 您必須管理完整的整合堆疊，包括 Google Cloud 和 Looker 驗證。
  • 資料代理程式的管理方式與 Looker 使用者介面無關。

使用 iframe 嵌入

您可以嵌入對話式數據分析做為 iframe，在 Looker UI 以外提供即時通訊體驗。這種模式可直接提供對話式數據分析，不需要自訂 UI 開發、後端協調或 API 狀態管理。如要使用這種模式，請在應用程式中加入預先格式化的網址。

Looker Embed SDK 提供多種工具，可管理安全網址產生、iframe 生命週期管理，以及主機應用程式與 iframe 之間的 JavaScript 事件傳遞等工作。您可以在應用程式中加入預先格式化的網址，嵌入「代理程式」頁面、「對話」頁面或特定對話。

您可以使用下列驗證方法驗證嵌入內容：

  • 私密嵌入：使用現有的 Looker 憑證驗證使用者。將嵌入網址設為 iframe 來源時，使用者會登入 Looker 帳戶。這個方法會自動強制執行現有的角色、內容存取權和資料層級權限 (例如存取篩選器或存取授權)，無須額外進行 IAM 設定或權杖對應。
  • 簽署嵌入：透過單一登入 (SSO) 驗證應用程式中的使用者。您可建構包含對話式數據分析內容路徑的簽署網址，動態指定要授予的確切權限。

使用 Looker API 和 SDK 建構內容

如要進一步彈性調整對話體驗，您可以使用 Looker API 中的 ConversationalAnalytics 方法，或使用 Looker SDK 建構自訂應用程式。這種做法可讓您建構自訂前端，直接與 Looker 端點通訊。

整合 Looker API 的優點如下：

  • 您只需要管理 Looker 的驗證，不必另外驗證對話式數據分析 API。
  • 對於已使用 Looker 嵌入或 API 的應用程式，這個模式可避免使用次要驗證機制，並免除管理外部資料代理程式的需求，簡化專案架構。
  • 您可以完全掌控對話介面、對話流程，以及應用程式的結果呈現方式 (例如圖表和表格)。

如需參考實作方式，請參閱 GitHub 上的 Conversational Analytics Looker API 指南。

搭配 Looker 資料使用 Conversational Analytics API

如需執行下列任一工作，可以直接透過 geminidataanalytics.googleapis.com 整合 Conversational Analytics API：

  • 在多個 Google Cloud 介面 (例如自訂網頁應用程式、Google Chat 和 Gemini Enterprise) 中共用同一個資料代理。
  • 在單一多代理程式系統中，結合 Looker 資料來源與 BigQuery 或作業資料庫來源。
  • 將資料代理程式視為受 IAM 管控的雲端層級資源，而非 Looker 權限模型。

如要進一步瞭解 Conversational Analytics API 的常見架構模式，請參閱「BigQuery 和資料庫的整合選項」。

BigQuery、數據分析和資料庫的整合選項

本節說明應用程式的架構模式，這些應用程式使用 BigQuery、數據分析 或支援的 Google Cloud 作業資料庫，透過 Conversational Analytics API 建構自訂體驗。

如果您將 Conversational Analytics API 與 Looker 資料來源搭配使用，本節所述模式也適用於您的整合。

Conversational Analytics API 提供下列主要方法，可與資料互動：

  • chat 方法：支援 BigQuery、Looker、數據分析和作業資料庫。
  • queryData 方法：支援作業資料庫，例如 AlloyDB、GoogleSQL for Spanner、MySQL 適用的 Cloud SQL，以及 PostgreSQL 適用的 Cloud SQL。

建構自訂應用程式時，您可以使用下列一或多個整合模式：

  • 直接整合 API：這種自訂做法的彈性最高，但您必須建構驗證、對話管理和回應剖析的基礎架構。
  • 以架構為導向的自動調度管理 (ADK)：這種方法使用 Agent Development Kit (ADK) 進行多代理路徑設定、工具執行和狀態管理。
  • 垂直整合 (MCP)：這種方法使用 Model Context Protocol (MCP)，為 AI 應用程式提供統一的連結方式，方便連結不同環境中的工具和資料來源。
  • 水平協調 (A2A)：這種做法會使用 Agent-to-Agent (A2A) 通訊協定，讓不同系統上的專用代理安全地協作，無須自訂整合代碼。

BigQuery 和資料庫整合模式摘要

下表列出 BigQuery 和作業資料庫的特定實作模式：

模式 適用情境 優點 注意事項
單一代理程式整合 (直接 API)：應用程式直接呼叫 API，從資料來源傳回洞察資料。 需要直接控管每項 API 呼叫的單一代理程式應用程式、原型或微服務。
  • 提供精細的控制選項，且不依附任何架構。
  • 為單一代理程式應用情境提供最簡單的架構。
  • 支援有狀態和無狀態模式。
  • 您必須建構所有基礎架構，包括驗證、狀態管理、回應剖析、錯誤處理、串流和部署。
  • 無法在多個代理程式的情境中妥善擴充。
自訂協調器 (直接 API)：這種模式會使用根代理程式和函式呼叫，在 Conversational Analytics 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 生態系統的發展而定。
  • 以無狀態模式運作，因此您必須在外部管理多輪對話狀態。
Agent2Agent (A2A)：這項模式使用 A2A 通訊協定 (開放標準)，讓不同系統的專用代理安全地協作，不需要自訂整合程式碼。 高度分散的企業環境，中央路由代理程式必須將工作委派給在不同系統或網路上運作的資料代理程式。
  • 減少不同架構之間自訂整合代碼的需求。
  • 確保跨平台互通性。
  • 提供安全且標準化的功能探索機制。
  • 與內部子代理相比，網路延遲時間較短。
  • 您必須設定 A2A 伺服器設定。

直接整合 API

直接整合 API 可精細控管應用程式的邏輯和架構，但您必須建構支援基礎架構。採用這種做法時，您要負責驗證、管理對話、剖析回覆及部署等工作。

本節涵蓋下列主題：

  • 單一代理程式整合：應用程式直接呼叫 Conversational Analytics API，從資料來源傳回洞察資訊。
  • 自訂協調器整合：進階模式，使用根代理程式和函式呼叫，在 Conversational Analytics API 之間傳送查詢。

單一代理程式整合

透過單一代理程式整合，後端會使用 REST 或用戶端程式庫直接呼叫對話式數據分析 API，並傳遞使用者的查詢和背景資訊。這個模式適用於低複雜度的應用程式，例如網頁應用程式、內部即時通訊工具或微服務，這些應用程式使用簡單的文字轉答案流程。您也可以使用這個方法進行原型設計和概念驗證工作。

這個模式支援有狀態和無狀態的對話。有狀態的對話由 Google 管理對話記錄，無狀態的對話則由應用程式管理記錄。

如需參考實作方式，請參閱 GitHub 上的 Conversational Analytics API 快速入門導覽課程或 Conversational Analytics API 黃金示範。

自訂自動調度管理工具整合

採用這種做法時，您會建構根層級代理，做為應用程式的主要進入點和協調器。根代理會使用標準 Gemini 模型，並透過函式呼叫功能配備工具。當使用者提出與資料相關的問題時，根代理程式會向對話式數據分析 API 發出工具呼叫、接收結果，然後繼續推論或呼叫其他下游工具。

函式呼叫包含下列階段：

  1. 宣告：將工具結構定義定義為包含參數定義的 FunctionDeclaration 物件。
  2. 叫用：模型會傳回包含函式名稱和引數的結構化 functionCall 訊息。
  3. 執行：應用程式會執行 API 呼叫，並在 FunctionResponse 訊息中傳回結果。
  4. 綜合：Gemini 模型會根據結果生成最終答案，或決定下一個動作。

如果應用程式的使用者可能會在執行其他工作時要求取得資料洞察，就適合採用這種做法。舉例來說，使用者可能會要求代理程式「顯示銷售資料，然後草擬一封電子郵件給銷售團隊」。根代理程式可以將資料問題傳送至 Conversational Analytics API，並使用其他工具執行非資料工作。

如需參考實作方式，請參閱 GitHub 上 Conversational Analytics API golden demo 中的 orchestrate 或 multimodal 頁面。

以架構為基礎的自動化調度管理 (ADK)

Agent Development Kit (ADK) 是以程式碼為優先的框架，用於建構 AI 代理，可管理多代理路徑、工具執行和狀態管理作業的複雜度。ADK 框架與 Gemini Enterprise 採用的框架相同。

使用 ADK 時，您可以將 Conversational Analytics API 與其他工具和代理串連，執行複雜動作。

本節涵蓋下列主題：

透過結構定義與 BigQueryToolset 整合

ADK 架構中的 BigQueryToolset 工具集包含預先建構的 ask_data_insights 工具。如要使用這項工具，請將資料表名稱和使用者的問題傳遞給工具，然後工具會使用內嵌內容呼叫 Conversational Analytics API。

呼叫工具時，系統會將包含指定 BigQuery 資料表參照的無狀態要求傳送至 Conversational Analytics API。API 會推斷資料庫結構定義、產生並執行 SQL 查詢，然後傳回文字答案。接著，結果會以工具回應的形式傳回 ADK 代理程式。

這種模式可有效率地為代理程式快速新增對話式分析功能。不過，由於 API 呼叫是無狀態，且缺乏控管機制，因此 API 會完全根據資料表結構產生 SQL，沒有語意防護措施。這種模式的部署速度較快，但如果適用命名慣例、業務邏輯或存取控制項，則在生產業務邏輯中會比較危險。

與 DataAgentToolset 的受控整合

ADK 架構中的 DataAgentToolset 工具集提供預先建構的整合功能，可透過 ID 參照預先設定的資料代理程式。ADK 代理程式會將使用者的問題傳遞至 ask_data_agent 工具，該工具會使用指定的資料代理程式環境呼叫 Conversational Analytics API。

您可以透過程式輔助方式使用 Conversational Analytics API 建立資料代理程式，也可以在 Google Cloud 控制台的「代理程式目錄」中建立。資料代理程式包含下列元件：

  • 知識來源：代理程式可查詢的資料表、檢視區塊或使用者定義函式 (UDF)
  • 結構化背景資訊：資料表和資料欄的說明，可協助代理瞭解基礎資料
  • 指令：提供給代理的額外指引，協助解讀及查詢資料來源
  • 已驗證的查詢：預先驗證的 SQL 查詢，可做為常見問題的範例
  • 詞彙表：業務字詞定義，有助於代理程式瞭解特定領域的語言

如需透過 Agent Catalog 建立代理程式的深入指南，請參閱 BigQuery 中的對話式數據分析程式碼實驗室。

由於代理程式定義為受控單元，因此無論哪個應用程式或子代理程式呼叫代理程式，都會使用相同的信任邏輯、環境和防護措施。

透過自訂子代理程式進階整合使用者體驗

BigQueryToolset 和 DataAgentToolset 工具組不會將結果傳回給使用者，直到 API 要求處理完畢為止。由於 ADK 框架會將 API 視為工具，在完成前會封鎖回應，因此執行時間較長的要求可能會導致使用者沒有收到回饋。

如果應用程式優先考量回應延遲時間，或資料擷取作業會提供給下游代理程式，您可以建立自訂 ADK 代理程式類別，直接連線至 Conversational Analytics API，並以非同步方式將資料分塊串流回使用者。這個模式支援以下回應類型：

  • 想法訊息：資料代理程式解讀問題時的推論過程。
  • 進度訊息：資料來源在擷取資料時的狀態更新。
  • 查詢生成：生成的 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 用戶端，而非 Conversational Analytics 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 代理在其他生態系統中做為工具使用。

選擇符合應用程式特定架構需求的整合模式：

  • 使用內建的 Agent Development Kit (ADK) 工具集 (例如 BigQueryToolset 或 DataAgentToolset)，可提供更緊密的整合，且沒有外部伺服器依附元件。這種方法非常適合完全位於 ADK 架構內的系統。
  • 使用 MCP Toolbox 中的工具，可確保符合 MCP 規範的用戶端之間互通性。如果資料工具必須為多個消費者應用程式或第三方 IDE 提供服務，這個方法就非常適合。

水平調度 (A2A)

Agent-to-Agent (A2A) 通訊協定是一項開放標準，可讓不同系統的專業代理安全地通訊及協作，不必編寫自訂整合代碼。

隨著系統擴充，機構通常會部署多個專用代理，這些代理是根據不同架構或雲端基礎架構建構而成。A2A 會為這些自主代理建立通用訊息層。每個代理會發布代理卡 (可探索的設定檔，詳細說明代理的功能、支援的資料格式和安全性需求)，而非使用自訂 API。

當中央調度器或同層級代理程式需要分析資料時，會透過結構化 A2A 訊息，將工作安全地委派給資料代理程式。資料代理程式會自主處理要求並傳回結果，將執行邏輯與要求者分離。

選擇整合模式

請參閱下表，比較各整合模式的複雜度、管理方式和功能。

複雜度等級定義如下：

  • 低：需要最少的自訂程式碼，並依賴預先建構的使用者介面或工具。
  • 中等：需要自訂前端開發和 API 或 SDK 整合，但可避免複雜的後端協調基礎架構。
  • 高：需要全堆疊應用程式開發、對話狀態管理、多個驗證層，或中繼自動調度管理基礎架構的模式。
  • 不一：複雜度取決於您選擇的基本整合方法。
整合模式 複雜度 自訂 代理治理 存取控管 多代理 串流 可攜性
Looker iframe 嵌入 低 低 透過 Looker 管理 Looker 否 內建 僅限 Looker
Looker API 和 SDK 中 高 透過 Looker 管理 Looker 否 內建 僅限 Looker
對話式數據分析 API (Looker 來源) 因解決方案而異 高 透過 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 是 是 跨平台

後續步驟