資料代理程式的整合模式

本頁面說明如何整合資料代理程式體驗，將其嵌入應用程式。這些模式的複雜程度不一，從嵌入式即時通訊元件到協調式多代理系統都有。

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

整合模式總覽

本指南會根據您的起點，分為下列主要軌道：

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

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

整合模式 說明 資料來源
Looker iframe 嵌入 在應用程式中加入標準的即時通訊介面，所需程式碼極少。 Looker
Looker API 和 SDK 建構自訂聊天介面，並使用 Looker API 進行驗證。 Looker
對話式數據分析 API (Looker 來源) 管理 Looker 資料代理程式，做為跨多個平台和多代理程式系統運作的 Google Cloud 資源。 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 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 UI 以外提供對話體驗。這個模式可直接提供對話式數據分析，不需要自訂 UI 開發、後端自動化調度管理或 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 指南。

搭配 Looker 資料使用對話式數據分析 API

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

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

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

BigQuery 和資料庫的整合選項

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

如果您搭配 Looker 資料來源使用對話式數據分析 API，本節所述模式也適用於您的整合。

對話式數據分析 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)：這種模式會使用根代理程式和函式呼叫，在對話式數據分析 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 伺服器。
  • 需要工具箱伺服器的額外基礎架構層。
  • 與 Agent Development Kit (ADK) 工具組相比，整合程度較低。
  • 視 MCP Toolbox 生態系統的發展而定。
  • 以無狀態模式運作，因此您必須在外部管理多輪對話狀態。
Agent-to-Agent (A2A)：這項模式使用 A2A 通訊協定 (開放標準)，讓不同系統的專用代理安全地協作，不需要自訂整合代碼。 高度分散的企業環境，中央路由代理程式必須將工作委派給在不同系統或網路上運作的資料代理程式。
  • 減少不同架構之間自訂整合代碼的需求。
  • 確保跨平台互通性。
  • 提供安全且標準化的功能探索機制。
  • 與內部子代理相比，網路延遲時間較短。
  • 您必須設定 A2A 伺服器設定。

直接整合 API

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

本節涵蓋下列主題：

單一代理程式整合

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

這個模式支援有狀態的即時通訊 (由 Google 管理對話記錄) 和無狀態的即時通訊 (由應用程式管理記錄)。

如需參考實作方式，請參閱 GitHub 上的 對話式數據分析 API 快速入門導覽課程或 對話式數據分析 API 黃金示範。

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

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

函式呼叫包含下列階段：

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

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

如需參考實作方式，請參閱 GitHub 上 對話式數據分析 API golden demo 中的 orchestrate 或 multimodal 頁面。

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

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

使用 ADK 時，您可以將對話式數據分析 API 與其他工具和代理串連，執行複雜動作。

本節涵蓋下列主題：

透過結構定義與 BigQueryToolset 整合

ADK 架構中的 BigQueryToolset 工具組包含預先建構的 ask_data_insights 工具。如要使用這項工具，請將資料表名稱和使用者的問題傳遞給工具，然後工具會使用內嵌情境呼叫對話式數據分析 API。

呼叫工具時，系統會傳送無狀態要求，其中包含指定 BigQuery 資料表參照至對話式數據分析 API。API 會推斷資料庫結構定義、產生及執行 SQL 查詢，並傳回文字答案。結果隨後會以工具回應的形式傳回 ADK 代理程式。

這個模式可有效率地將對話式數據分析功能快速新增至代理程式。不過，由於 API 呼叫是無狀態，且缺乏控管機制，因此 API 會完全根據資料表結構定義產生 SQL，沒有語意防護措施。這樣一來，模式的部署速度會更快，但如果適用命名慣例、商業邏輯或存取控管，則正式版商業邏輯的風險會更高。

與 DataAgentToolset 的受控整合

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

您可以透過程式輔助方式使用對話式數據分析 API 建立資料代理程式，也可以在 Google Cloud 控制台的「代理程式目錄」中建立。資料代理程式配備下列元件：

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

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

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

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

API 要求處理完成後，BigQueryToolset 和 DataAgentToolset 工具組才會將結果傳回給使用者。由於 ADK 框架會將 API 視為工具，在完成前封鎖回應，因此如果查詢時間較長，使用者可能會沒有收到回饋。

如果應用程式優先考量低回應延遲，或資料擷取作業會提供給下游代理程式，您可以建構自訂 ADK 代理程式類別，直接連線至對話式數據分析 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 的用戶端使用，而不是對話式數據分析 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 代理在其他生態系統中做為工具使用。

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

  • 使用 BigQueryToolset 或 DataAgentToolset 等內建 Agent Development Kit (ADK) 工具組，可實現更緊密的整合，且沒有外部伺服器依附元件。這種方法非常適合完全位於 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
透過 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 是 是 跨平台

後續步驟