Integrationsmuster für Data Agents

Auf dieser Seite werden Integrationsmuster zum Einbetten von Daten-Agent-Funktionen in Ihre Anwendungen beschrieben. Die Komplexität dieser Muster reicht von einer eingebetteten Chatkomponente bis hin zu einem orchestrierten Multi-Agenten-System.

Dieser Leitfaden richtet sich an Cloud-Architekten und Data Engineers, die generative KI-Anwendungen entwerfen. Sie sollten ein grundlegendes Verständnis von Google Cloud -Konzepten, Identity and Access Management (IAM) und REST APIs haben. Außerdem sollten Sie mit der Architektur der Datenquelle vertraut sein, die Ihre Anwendung verwendet.

Übersicht über Integrationsmuster

Dieser Leitfaden ist in die folgenden Hauptbereiche unterteilt, die jeweils auf Ihrem Ausgangspunkt basieren:

  • Looker-Track: Wählen Sie diesen Track aus, wenn Sie Chatfunktionen über die Looker-Einbettung, die Looker API oder die konversationelle Analyse API bereitstellen möchten.
  • BigQuery- und Datenbank-Track: Wählen Sie diesen Track aus, wenn Sie eine benutzerdefinierte Anwendung erstellen, die BigQuery, Data Studio oder eine unterstützte operative Datenbank verwendet.

In der folgenden Tabelle sind die verfügbaren Integrationsmuster zusammengefasst:

Integrationsmuster Beschreibung Datenquelle
Looker-iFrame-Einbettung Fügt einer Anwendung die Standard-Chat-Oberfläche hinzu, die nur minimalen Code erfordert. Looker
Looker API und SDKs Erstellt eine benutzerdefinierte Chat-Oberfläche, die die Looker API zur Authentifizierung verwendet. Looker
API für konversationelle Analyse (Looker-Quelle) Verwaltet Looker-Daten-Agents als Google Cloud -Ressourcen, die auf mehreren Oberflächen und in Multi-Agenten-Systemen funktionieren. Looker
Direkte API (einzelner Agent) Verwendet eine direkte API-Integration für Text-zu-Antwort-Abläufe. BigQuery, Datenbanken, Looker
Direkte API (Orchestrator) Leitet Abfragen zwischen der API und anderen Tools mithilfe von Funktionsaufrufen weiter. BigQuery, Datenbanken, Looker
ADK (schemagesteuert) mit BigQueryToolset Generiert mit dem ask_data_insights-Tool schnelle Insights aus Tabellenreferenzen. BigQuery
ADK (verwaltet) mit DataAgentToolset Fragt vorkonfigurierte Daten-Agents ab, die das ask_data_agent-Tool verwenden, um ein konsistentes Verhalten zu gewährleisten. BigQuery, Datenbanken, Looker
ADK (benutzerdefiniertes Streaming) Unterstützt das Echtzeit-Streaming von Diagrammen und SQL mithilfe einer benutzerdefinierten Agent-Klasse. BigQuery, Datenbanken, Looker
MCP mit McpToolset oder ToolboxToolset Verbindet Anwendungen mit Datentools, die das Model Context Protocol (MCP) verwenden. BigQuery, Looker
Remote-MCP-Server für die konversationelle Analyse-API Bietet ein einheitliches, sicheres Gateway, über das Root-Agenten in KI-Plattformen von Drittanbietern und von Google verwalteten Plattformen (z. B. Gemini Enterprise) spezialisierte Daten-Agenten in Google Clouderkennen und mit ihnen kommunizieren können. BigQuery, Datenbanken, Looker
A2A-Protokoll Ermöglicht die sichere Zusammenarbeit zwischen spezialisierten Agenten, die auf verschiedenen Systemen ausgeführt werden. Framework-abhängig

Integrationsoptionen für Looker

Wenn Sie Looker verwenden, können Sie Ihren Nutzern Looker konversationelle Analyse über die folgenden Muster zur Verfügung stellen:

Zusammenfassung der Looker-Integrationsmuster

In der folgenden Tabelle sind die primären Integrationsmuster für Looker zusammengefasst:

Muster Optimal für Vorteile Hinweise
Mit iFrames einbetten: Eine Low-Code-Methode, um einer Anwendung schnell die Standard-Looker-Chat-Funktion hinzuzufügen. Teams, die eine produktionsreife konversationelle Analyse mit minimalem benutzerdefiniertem Entwicklungsaufwand benötigen.
  • Für die Implementierung ist nur minimaler Code erforderlich.
  • Erzwingt automatisch das vorhandene Looker-Sicherheitsmodell.
  • Keine separate Google Cloud Authentifizierung erforderlich.
  • Unterstützt das Looker Embed SDK, das die Entwicklung durch die Verwaltung von iFrame-Lebenszyklen und die Ereignisweitergabe beschleunigt.
  • Bietet nur eingeschränkte Anpassungsmöglichkeiten für die Benutzeroberfläche und ist von der Standard-Chat-Benutzeroberfläche von Looker abhängig.
  • Ihre Looker-Instanz muss von Looker gehostet werden.
Mit der Looker API und den SDKs erstellen: Ein flexibler Ansatz zum Erstellen einer benutzerdefinierten Chatoberfläche, bei dem die Authentifizierung und die Agentenverwaltung in Looker verbleiben. Teams, die eine benutzerdefinierte Chat-Nutzererfahrung benötigen, aber die Nutzerauthentifizierung und Agentenverwaltung im Looker-Ökosystem beibehalten möchten. Dieses Muster ist ideal für Anwendungen, die bereits Looker-Einbettungen oder die API verwenden.
  • Bietet eine einzige Authentifizierungsebene und vollständige Kontrolle über die Benutzeroberfläche.
  • Vereinfacht die Architektur für bestehende Looker-Kunden.
  • Verwendet die semantische Ebene von Looker, um die Genauigkeit von Abfragen zu verbessern.
  • Keine separate Google Cloud Authentifizierung erforderlich.
  • Erfordert Fachwissen in der Looker API-Entwicklung.
  • Beschränkt auf Looker-Datenquellen.
  • KI-Agenten werden in Looker verwaltet und können nicht auf andere Dienste von Google Cloud übertragen werden.
Conversational Analytics API verwenden: Direkte Integration in die API, um Agenten als Ressourcen auf Cloud-Ebene zu verwalten. Looker-Kunden, die plattformübergreifende Portabilität für ihre Daten-Agents benötigen.
  • Sorgt dafür, dass der Daten-Agent auf allen Google Cloud -Oberflächen portabel ist.
  • Zentral über IAM verwaltet.
  • Ermöglicht die Integration von Daten-Agents in ADK- oder MCP-Workflows.
  • Erfordert, dass Sie den gesamten Integrationsstack verwalten, einschließlich der Authentifizierung von Google Cloud und Looker.
  • Daten-Agents werden unabhängig von der Looker-Benutzeroberfläche verwaltet.

Mit iFrames einbetten

Sie können konversationelle Analyse als iFrame einbetten, um die Chat-Funktion außerhalb der Looker-Benutzeroberfläche bereitzustellen. Dieses Muster ist eine direkte Möglichkeit, konversationelle Analyse bereitzustellen, ohne dass eine benutzerdefinierte UI-Entwicklung, eine Backend-Orchestrierung oder eine API-Zustandsverwaltung erforderlich ist. Wenn Sie dieses Muster verwenden möchten, fügen Sie Ihrer Anwendung eine vorformatierte URL hinzu.

Das Embed SDK von Looker bietet Tools zum Verwalten von Aufgaben wie der sicheren URL-Generierung, der Verwaltung des iFrame-Lebenszyklus und der Weitergabe von JavaScript-Ereignissen zwischen der gehosteten Anwendung und dem iFrame. Sie können die Seite Agents, die Seite Unterhaltungen oder eine bestimmte Unterhaltung einbetten, indem Sie eine vorformatierte URL in Ihre Anwendung einfügen.

Für eingebettete Inhalte können Sie die folgenden Authentifizierungsmethoden verwenden:

  • Private Einbettung: Authentifiziert Nutzer mit ihren vorhandenen Looker-Anmeldedaten. Wenn Sie die Einbettungs-URL als iFrame-Quelle festlegen, melden sich Nutzer mit ihren Looker-Konten an. Bei dieser Methode werden vorhandene Rollen, der Zugriff auf Inhalte und Berechtigungen auf Datenebene wie Zugriffsfilter oder Zugriffserteilungen automatisch erzwungen, ohne dass eine zusätzliche IAM-Konfiguration oder Tokenzuordnung erforderlich ist.
  • Signierte Einbettung: Authentifiziert Nutzer über Ihre Anwendung mithilfe der Einmalanmeldung (SSO). Sie erstellen eine signierte URL, die den Inhaltspfad für konversationelle Analysen enthält. So können Sie dynamisch genau angeben, welche Berechtigungen gewährt werden sollen.

Mit der Looker API und den SDKs entwickeln

Wenn Sie mehr Flexibilität bei der Chat-Nutzung wünschen, können Sie die ConversationalAnalytics-Methoden in der Looker API oder ein Looker SDK verwenden, um eine benutzerdefinierte Anwendung zu erstellen. Mit diesem Ansatz können Sie ein benutzerdefiniertes Frontend erstellen, das direkt mit Looker-Endpunkten kommuniziert.

Die Integration in die Looker API bietet folgende Vorteile:

  • Sie verwalten die Authentifizierung nur mit Looker. Eine separate Authentifizierung bei der API für konversationelle Analyse ist nicht erforderlich.
  • Bei Anwendungen, die bereits Looker-Einbettungen oder die API verwenden, vereinfacht dieses Muster die Projektarchitektur, da keine sekundären Authentifizierungsmechanismen erforderlich sind und keine externen Daten-Agents verwaltet werden müssen.
  • Sie haben die volle Kontrolle über die Chatoberfläche, den Gesprächsverlauf und die Darstellung der Ergebnisse (z. B. Diagramme und Tabellen) in der Anwendung.

Eine Referenzimplementierung finden Sie im Looker API-Leitfaden mit ConversationalAnalytics-Methoden auf GitHub.

Konversationelle Analyse API mit Looker-Daten verwenden

Sie können die konversationelle Analyse API unter geminidataanalytics.googleapis.com direkt einbinden, wenn Sie eine der folgenden Aufgaben ausführen müssen:

  • Sie können denselben KI-Datenagenten auf mehreren Google Cloud -Oberflächen verwenden, z. B. in benutzerdefinierten Webanwendungen, Google Chat und Gemini Enterprise.
  • Looker-Datenquellen mit BigQuery- oder operativen Datenbankquellen in einem einzigen Multi-Agenten-System kombinieren.
  • Verwalten Sie Ihren Daten-Agenten als Ressource auf Cloud-Ebene, die IAM unterliegt und nicht dem Looker-Berechtigungsmodell.

Weitere Informationen zu gängigen Architekturmustern für die konversationelle Analyse-API finden Sie unter Integrationsoptionen für BigQuery und Datenbanken.

Integrationsoptionen für BigQuery, Data Studio und Datenbanken

In diesem Abschnitt werden Architekturmuster für Anwendungen beschrieben, die BigQuery, Data Studio oder unterstützte operative Datenbanken von Google Cloud verwenden, um mit der Conversational Analytics API benutzerdefinierte Funktionen zu erstellen.

Wenn Sie die konversationelle Analyse API mit einer Looker-Datenquelle verwenden, gelten die in diesem Abschnitt beschriebenen Muster auch für Ihre Integration.

Die Conversational Analytics API bietet die folgenden primären Methoden für die Interaktion mit Daten:

  • chat-Methode: Unterstützt BigQuery, Looker, Data Studio und operative Datenbanken.
  • queryData-Methode: Unterstützt operative Datenbanken wie AlloyDB, GoogleSQL for Spanner, Cloud SQL for MySQL und Cloud SQL for PostgreSQL.

Wenn Sie eine benutzerdefinierte Anwendung erstellen, können Sie eines oder mehrere der folgenden Integrationsmuster verwenden:

  • Direkte API-Integration: Ein benutzerdefinierter Ansatz, der die größte Flexibilität bietet, aber erfordert, dass Sie die Infrastruktur für Authentifizierung, Konversationsverwaltung und Antwortparsing selbst erstellen.
  • Framework-gesteuerte Orchestrierung (ADK): Ein Ansatz, bei dem das Agent Development Kit (ADK) für das Multi-Agenten-Routing, die Toolausführung und die Zustandsverwaltung verwendet wird.
  • Vertikale Integration (MCP): Ein Ansatz, der das Model Context Protocol (MCP) verwendet, um eine einheitliche Möglichkeit zu bieten, KI-Anwendungen mit Tools und Datenquellen in verschiedenen Umgebungen zu verbinden.
  • Horizontale Orchestrierung (A2A): Ein Ansatz, bei dem das Agent-to-Agent-Protokoll (A2A) verwendet wird, um spezialisierten Agenten auf verschiedenen Systemen die sichere Zusammenarbeit zu ermöglichen, ohne dass benutzerdefinierter Integrationscode erforderlich ist.

Zusammenfassung der BigQuery- und Datenbankintegrationsmuster

In der folgenden Tabelle sind die spezifischen Implementierungsmuster für BigQuery und operative Datenbanken zusammengefasst:

Muster Optimal für Vorteile Hinweise
Integration mit einem einzelnen Agenten (direkte API): Ein Muster, bei dem Ihre Anwendung die API direkt aufruft, um Statistiken aus Ihren Datenquellen zurückzugeben. Anwendungen mit einem einzelnen Agenten, Prototypen oder Mikrodienste, die eine direkte Kontrolle über jeden API-Aufruf erfordern.
  • Bietet eine detaillierte Steuerung ohne Framework-Abhängigkeiten.
  • Bietet die einfachste Architektur für Anwendungsfälle mit einem einzelnen Agenten.
  • Unterstützt sowohl zustandsorientierte als auch zustandslose Modi.
  • Sie müssen die gesamte Infrastruktur für Authentifizierung, Zustandsverwaltung, Antwortparsing, Fehlerbehandlung, Streaming und Bereitstellung selbst erstellen.
  • Nicht gut skalierbar für Multi-Agent-Szenarien.
Benutzerdefinierter Orchestrator (direkte API): Ein Muster, bei dem ein Root-Agent und Funktionsaufrufe verwendet werden, um Abfragen zwischen der konversationellen Analyse-API und anderen Tools oder Diensten weiterzuleiten. Anwendungen, die Datenabfragen mit anderen Aufgaben wie E‑Mails oder Dokumenten in einem einzigen konversationellen Ablauf kombinieren.
  • Bietet maximale Orchestrierungssteuerung ohne Framework-Abhängigkeiten.
  • Damit können Sie genau festlegen, wie das Modell-Routing zwischen Tools erfolgt.
  • Funktioniert mit jedem Gemini-Modell.
  • Erfordert, dass Sie Tooldefinitionen, Unterhaltungsschleifen, Multi-Turn-Status, Fehlerbehandlung und Bereitstellung manuell verwalten.
  • Der Entwicklungsaufwand kann im Vergleich zur Verwendung eines Frameworks wie dem ADK hoch sein.
Schemagesteuerte Integration mit BigQueryToolset (ADK): Ein Muster, das Tabellenreferenzen verwendet, um schnell Datenerkenntnisse zu liefern. Rapid Prototyping, interne Tools, bei denen die Data Governance weniger kritisch ist, oder Szenarien, in denen Dateneinblicke eine von mehreren Funktionen eines ADK-Agenten sind.
  • Bietet den schnellsten Integrationspfad im ADK-Framework.
  • Keine Vorkonfiguration des Daten-Agents erforderlich.
  • Arbeitet direkt mit Datenbanktabellennamen.
  • Keine semantische Governance und Generierung von SQL nur aus Schemainferenz.
  • Arbeitet auf API-Ebene im zustandslosen Modus.
  • Liefert nur Textantworten und unterstützt keine Diagramme.
Gesteuerte Integration mit DataAgentToolset (ADK): Ein Muster, das einen vorkonfigurierten KI-Datenagenten abfragt, indem es auf die ID des KI-Agenten verweist. Produktionsanwendungen, die einen konsistenten Datenzugriff erfordern, oder Multi-Agenten-Systeme, in denen der Daten-Agent eine vertrauenswürdige, wiederverwendbare Komponente ist.
  • Bietet semantische Governance und konsistentes Verhalten für alle Nutzer.
  • Verbessert die Genauigkeit durch die Verwendung verifizierter Abfragen und eines Unternehmensglossars.
  • Sorgt dafür, dass Daten-Agents in ADK-, MCP- und direkten API-Integrationen wiederverwendet werden können.
  • Erfordert, dass Sie Daten-Agent-Ressourcen vorkonfigurieren.
  • Arbeitet auf API-Ebene im zustandslosen Modus.
  • Gibt nur Textantworten zurück und unterstützt keine Diagramme.
Benutzerdefinierte Sub-Agenten (ADK): Ein Muster, das eine benutzerdefinierte Agentenklasse verwendet, um eine direkte Verbindung zur API herzustellen und Datenblöcke an den Nutzer zurückzugeben. Für Nutzer sichtbare Anwendungen, bei denen eine niedrige Antwortlatenz Priorität hat, oder Multi-Agent-Pipelines, bei denen der Datenabruf nachgelagerte Agenten versorgt.
  • Feedback zum Streaming in Echtzeit
  • Greift auf alle Antworttypen zu, z. B. Diagramme, Tabellen und SQL.
  • Über den Sitzungsstatus mit anderen ADK-Agenten kombinierbar.
  • Erfordert mehr Entwicklungsaufwand, um eine benutzerdefinierte ADK-Agentenklasse zu erstellen.
  • Sie müssen die Streamingverbindung und das Parsen der Antwort direkt verwalten.
Model Context Protocol (MCP): Ein Muster, das einen offenen Standard verwendet, um KI-Anwendungen mit Datenquellen und Tools in verschiedenen Umgebungen zu verbinden. Unternehmen, die Tool-Interoperabilität über mehrere KI-Clients und IDEs hinweg benötigen, oder Teams, die dieselben Datentools über das ADK-Framework, IDEs und benutzerdefinierte Anwendungen zugänglich machen müssen.
  • Verwendet einen universellen Toolstandard, der mit jedem MCP-kompatiblen Client funktioniert.
  • Entkoppelt die Tool-Implementierung von Nutzeranwendungen.
  • Bietet Optionen für verwaltete Server, z. B. den MCP-Server von Google Cloud .
  • Erfordert eine zusätzliche Infrastrukturebene für den Toolbox-Server.
  • Bietet eine weniger enge Integration als ADK-Toolsets.
  • Abhängig vom sich entwickelnden Ökosystem der MCP Toolbox.
  • Arbeitet in einem zustandslosen Modus, bei dem Sie den Multi-Turn-Status extern verwalten müssen.
Agent-to-Agent (A2A): Ein Muster, das das A2A-Protokoll verwendet, einen offenen Standard, der es spezialisierten Agenten auf verschiedenen Systemen ermöglicht, sicher zusammenzuarbeiten, ohne dass benutzerdefinierter Integrationscode erforderlich ist. Stark verteilte Unternehmensumgebungen, in denen ein zentraler Router-Agent Aufgaben an Daten-Agenten delegieren muss, die auf verschiedenen Systemen oder in verschiedenen Netzwerken arbeiten.
  • Reduziert den Bedarf an benutzerdefiniertem Integrationscode zwischen unterschiedlichen Frameworks.
  • Sorgt für eine nahtlose plattformübergreifende Interoperabilität.
  • Bietet eine sichere und standardisierte Funktionserkennung.
  • Verursacht im Vergleich zu internen Sub-Agenten eine geringe Netzwerklatenz.
  • Erfordert die Konfiguration von A2A-Servereinstellungen.

Direkte API-Verknüpfung

Die direkte API-Integration bietet eine detaillierte Kontrolle über die Logik und Architektur Ihrer Anwendung, erfordert jedoch, dass Sie die unterstützende Infrastruktur selbst erstellen. Bei diesem Ansatz sind Sie für Aufgaben wie Authentifizierung, Unterhaltungsverwaltung, Antwortparsen und Bereitstellung verantwortlich.

In diesem Abschnitt werden die folgenden Themen behandelt:

  • Single-agent integration: Ein Muster, bei dem Ihre Anwendung die Conversational Analytics API direkt aufruft, um konversationelle Analysen aus Ihren Datenquellen zurückzugeben.
  • Benutzerdefinierte Orchestrator-Integration: Ein erweitertes Muster, bei dem ein Root-Agent und Funktionsaufrufe verwendet werden, um Abfragen zwischen der konversationellen Analyse API weiterzuleiten.

Integration eines einzelnen KI-Agenten

Bei einer Integration mit einem einzelnen Agent ruft Ihr Backend die konversationelle Analyse API direkt über REST oder eine Clientbibliothek auf und übergibt die Anfrage und den Kontext des Nutzers. Dieses Muster eignet sich für Anwendungen mit geringer Komplexität, z. B. Webanwendungen, interne Chat-Tools oder Mikrodienste, die einen einfachen Text-zu-Antwort-Ablauf verwenden. Sie können diesen Ansatz auch für Prototyping und Proof of Concept verwenden.

Dieses Muster unterstützt sowohl zustandsorientierte Chats, bei denen Google den Unterhaltungsverlauf verwaltet, als auch zustandslose Chats, bei denen Ihre Anwendung den Verlauf verwaltet.

Referenzimplementierungen finden Sie in der Kurzanleitung zur konversationellen Analyse API oder in der konversationellen Analyse API Golden Demo auf GitHub.

Benutzerdefinierte Orchestrator-Integration

Bei diesem Ansatz erstellen Sie einen Root-Agenten, der als primärer Einstiegspunkt und Koordinator für Ihre Anwendung dient. Der Stamm-Agent verwendet ein Standard-Gemini-Modell, das über Funktionsaufrufe mit Tools ausgestattet ist. Wenn ein Nutzer eine datenbezogene Frage stellt, sendet der Root-Agent einen Toolaufruf an die konversationelle Analyse API, empfängt das Ergebnis und kann dann weitere Schlussfolgerungen ziehen oder andere Tools aufrufen.

Funktionsaufrufe umfassen die folgenden Phasen:

  1. Deklarieren: Definieren Sie Tool-Schemas als FunctionDeclaration-Objekte, die Parameterdefinitionen enthalten.
  2. Aufrufen: Das Modell gibt eine strukturierte functionCall-Nachricht zurück, die den Funktionsnamen und die Argumente enthält.
  3. Ausführen: Ihre Anwendung führt den API-Aufruf aus und gibt das Ergebnis in einer FunctionResponse-Nachricht zurück.
  4. Synthetisieren: Das Gemini-Modell verwendet das Ergebnis, um eine endgültige Antwort zu generieren oder die nächste Aktion zu bestimmen.

Dieser Ansatz eignet sich für Anwendungen, bei denen Nutzer neben anderen Aufgaben auch nach Dateneinblicken fragen können. Ein Nutzer könnte den Agenten beispielsweise bitten: „Zeige mir die Verkaufszahlen und entwirf dann eine E‑Mail an das Vertriebsteam.“ Der Root-Agent kann die Datenfrage an die Conversational Analytics API weiterleiten und andere Tools für Aufgaben verwenden, die nicht mit Daten zu tun haben.

Eine Referenzimplementierung finden Sie auf den Seiten orchestrate oder multimodal in der konversationellen Analyse API Golden Demo auf GitHub.

Framework-gesteuerte Orchestrierung (ADK)

Das Agent Development Kit (ADK) ist ein codeorientiertes Framework zum Erstellen von KI-Agenten, das die Komplexität von Multi-Agenten-Routing, Toolausführung und Zustandsverwaltung bewältigt. Das ADK-Framework ist dasselbe Framework, das auch Gemini Enterprise unterstützt.

Mit dem ADK können Sie die konversationelle Analyse API mit anderen Tools und Agenten verketten, um komplexe Aktionen auszuführen.

In diesem Abschnitt werden die folgenden Themen behandelt:

Schemagesteuerte Integration mit BigQueryToolset

Das BigQueryToolset-Toolset im ADK-Framework enthält ein vordefiniertes ask_data_insights-Tool. Wenn Sie dieses Tool verwenden möchten, übergeben Sie Tabellennamen und die Frage des Nutzers an das Tool, das dann die konversationelle Analyse API mit Inline-Kontext aufruft.

Wenn Sie das Tool aufrufen, wird eine zustandslose Anfrage mit den angegebenen BigQuery-Tabellenreferenzen an die API für konversationelle Analyse gesendet. Die API leitet das Datenbankschema ab, generiert und führt die SQL-Abfrage aus und gibt eine Textantwort zurück. Das Ergebnis wird dann als Tool-Antwort an den ADK-Agenten zurückgegeben.

Dieses Muster ist eine effektive Möglichkeit, einem Agenten schnell konversationelle Analysen hinzuzufügen. Da der Aufruf der API jedoch zustandslos ist und keine Governance hat, generiert die API SQL, das vollständig auf dem Tabellenschema basiert, ohne semantische Guardrails. Dieses Muster lässt sich schneller bereitstellen, ist aber riskanter für die Produktionsgeschäftslogik, wenn Namenskonventionen, Geschäftslogik oder Zugriffssteuerungen gelten.

Gesteuerte Integration mit DataAgentToolset

Das Toolset DataAgentToolset im ADK-Framework bietet eine vordefinierte Integration, die über die ID auf einen vorkonfigurierten KI-Datenagenten verweist. Der ADK-Agent leitet die Frage des Nutzers an das ask_data_agent-Tool weiter, das die konversationelle Analyse API mit dem angegebenen Daten-Agent-Kontext aufruft.

Sie können einen Daten-Agent programmatisch über die konversationelle Analyse API oder über den Agentenkatalog in der Google Cloud Console erstellen. Ein KI-Datenagent ist mit den folgenden Komponenten ausgestattet:

  • Wissensquellen: Tabellen, Ansichten oder benutzerdefinierte Funktionen (UDFs), die der Agent abfragen kann
  • Strukturierter Kontext: Beschreibungen für Tabellen und Spalten, die dem KI-Agenten helfen, die zugrunde liegenden Daten zu verstehen
  • Anweisungen: Zusätzliche Anleitungen für den Agenten, um die Datenquellen zu interpretieren und abzufragen
  • Verifizierte Abfragen: Vorab validierte SQL-Abfragen, die als Beispiele für häufige Fragen dienen
  • Glossar: Definitionen von Geschäftsbegriffen, die dem KI-Agenten helfen, fachspezifische Sprache zu verstehen

Eine ausführliche Anleitung zum Erstellen von KI-Agenten über den Agentenkatalog finden Sie im Codelab Konversationelle Analysen in BigQuery.

Da der KI-Agent als verwaltete Einheit definiert ist, verwendet er dieselbe vertrauenswürdige Logik, denselben Kontext und dieselben Guardrails, unabhängig davon, von welcher Anwendung oder welchem Sub-Agenten er aufgerufen wird.

Erweiterte UX-Integration mit benutzerdefinierten Sub-Agents

Die Toolsets BigQueryToolset und DataAgentToolset geben erst dann Ergebnisse an den Nutzer zurück, wenn die API-Anfrage verarbeitet wurde. Da das ADK-Framework die API als Tool behandelt, das Antworten bis zum Abschluss blockiert, erhalten Nutzer bei länger dauernden Abfragen möglicherweise kein Feedback.

Als Alternative für Anwendungen, bei denen eine niedrige Antwortlatenz Priorität hat oder bei denen der Datenabruf nachgelagerte Agenten speist, können Sie eine benutzerdefinierte ADK-Agentenklasse erstellen, die sich direkt mit der Conversational Analytics API verbindet und Daten asynchron in Blöcken an den Nutzer zurückstreamt. Dieses Muster unterstützt die folgenden Antworttypen, während sie erstellt werden:

  • Gedankennachrichten: Der Reasoning-Prozess des KI-Datenagenten bei der Interpretation der Frage.
  • Fortschrittsmeldungen: Statusaktualisierungen während des Datenabrufs für Datenquellen.
  • Abfragegenerierung: Die generierte SQL- oder Looker-Abfrage, die während der Erstellung gestreamt wird.
  • Daten: Die Datenergebnisse im JSON-Format.
  • Visualisierung: Vega-Lite-Diagrammspezifikationen.
  • Zusammenfassung: Die endgültige textbasierte Antwort.

Eine vollständige Liste der zurückgegebenen Datentypen finden Sie in der API-Referenzdokumentation unter dem Typ SystemMessage.

Dieser asynchrone Ansatz sorgt dafür, dass Nutzer nicht warten müssen, bis ein komplexer Datenabrufprozess vollständig abgeschlossen ist. Während der Daten-Agent den Abfrageprozess durchläuft, gibt er kontinuierlich inkrementelle Aktualisierungen wie Textzusammenfassungen, Rohdaten oder Diagrammkonfigurationen in einem temporären, freigegebenen Arbeitsbereich frei. Diese Daten können dann in Echtzeit für den Nutzer gerendert und an spezialisierte Sub-Agenten weitergegeben werden, um zusätzliche Aufgaben auszuführen.

Eine Referenzimplementierung mit einem Root-Agenten, einem Daten-Sub-Agenten und einem Visualisierungs-Agenten finden Sie in der ADK-Streaming-Demo auf GitHub.

Vertikale Integration (MCP)

Das Model Context Protocol (MCP) ist ein offener Standard, der eine einheitliche Möglichkeit für KI-Anwendungen bietet, sich mit externen Tools und Datenquellen zu verbinden. Das MCP standardisiert die Schnittstelle zwischen KI-Modellen und den von ihnen verwendeten Tools.

In diesem Abschnitt werden die folgenden Themen behandelt:

Remote-MCP-Server für die konversationelle Analyse-API

Die API für konversationelle Analyse bietet einen Remote-MCP-Server unter https://geminidataanalytics.googleapis.com/mcp, der vom verwalteten MCP-Server von Google unterstützt wird. Dieses Gateway bietet eine einheitliche, sichere HTTP- und SSE-Schnittstelle (Server-Sent Events), über die Root-Agenten auf KI-Plattformen von Drittanbietern und von Google verwalteten Plattformen (z. B. Gemini Enterprise) spezialisierte Daten-Agenten in Google Clouderkennen und mit ihnen kommunizieren können.

Übersicht über die Kommunikation des Stamm-KI-Agenten

Die Kommunikation zwischen einem externen oder von Google verwalteten Root-Agenten und der Conversational Analytics API umfasst drei verschiedene Rollen:

  1. Datenoperatoren erstellen und konfigurieren bereichsbezogene Daten-Agenten auf allen konversationellen Analyse-Oberflächen, schreiben klare Beschreibungen der Datenquellen, auf die jeder Agent zugreifen kann, und der Fragen, die er beantworten kann, und geben diese Agenten für geschäftliche Nutzer frei.
  2. Plattformadministratoren registrieren eine benutzerdefinierte MCP-Verbindung in ihrer agentischen Plattform, die auf den https://geminidataanalytics.googleapis.com/mcp-Endpunkt verweist. Administratoren konfigurieren OAuth 2.0-Clientanmeldedaten (Client-ID und Clientschlüssel) mit dem Google-Autorisierungsendpunkt (https://accounts.google.com/o/oauth2/v2/auth), dem Token-Endpunkt (https://oauth2.googleapis.com/token) und den erforderlichen Autorisierungsbereichen (https://www.googleapis.com/auth/geminidataanalytics und https://www.googleapis.com/auth/bigquery.readonly).
  3. Geschäftliche Nutzer stellen Fragen in natürlicher Sprache auf der agentischen Plattform. Anstatt Rohdatenbanken direkt abzufragen, kommuniziert der Root-Agent der Plattform (das Orchestrator-LLM) mit dem Remote-MCP-Server der konversationellen Analyse API, um relevante Daten-Agenten zu finden, die Frage des Nutzers an den entsprechenden Daten-Agenten weiterzuleiten und die zusammengefasste Antwort zurückzugeben.
Identitätsweitergabe

Damit die Data Governance des Unternehmens gewahrt bleibt, wenn Anfragen von Drittanbieter- oder externen Root-Agenten stammen, erzwingt der Remote-MCP-Server die End-to-End-Identitätsweitergabe:

  • Vom Nutzer delegierte Authentifizierung: Wenn ein geschäftlicher Nutzer mit dem Root-Agenten interagiert, authentifiziert die agentische Plattform den Nutzer über einen 3-Legged-OAuth 2.0-Vorgang und fügt das vom Nutzer delegierte OAuth-Zugriffstoken in die HTTP-Header der Anfragen ein, die an das MCP-Gateway gesendet werden.
  • Weiterleitung von Endnutzer-Anmeldedaten (EUC): Der Remote-MCP-Server validiert das Token und leitet die Endnutzer-Anmeldedaten über die konversationelle Analyse API-Ebene an die zugrunde liegenden Daten-Engines wie BigQuery, Spanner, AlloyDB und Cloud SQL weiter.
  • Gesteuerter Datenzugriff: Da Abfragen mit der Identität des authentifizierten Nutzers und nicht mit einem freigegebenen Dienstkonto ausgeführt werden, werden die zugrunde liegenden Datenquellen automatisch durch vorhandene IAM-Berechtigungen, Sicherheitsrichtlinien auf Zeilen- und Spaltenebene und gesteuerte Datenzugriffsgrenzen geschützt. Nutzer können nur Daten-Agents finden und Datasets abfragen, auf die sie bereits Zugriff haben.
  • Looker-Modell mit zwei Identitäten: Bei BigQuery und operativen Datenbanken werden Abfragen mit den weitergeleiteten Google OAuth-Anmeldedaten des einzelnen Nutzers ausgeführt. Bei Looker-basierten Daten-Agents wird für die Authentifizierung ein Modell mit zwei Identitäten verwendet: Das Google OAuth-Token des Nutzers autorisiert den Zugriff auf den Daten-Agent in Google IAM, die Abfrage wird jedoch in Looker mit den Anmeldedaten eines Looker API-Nutzers ausgeführt, die im Anmeldedatenblock des Chat-Tools übergeben werden. Der Zugriff auf Looker-Modelle, Berechtigungen und Regeln auf Zeilenebene spiegeln diesen konfigurierten API-Nutzer wider, nicht die Looker-Identität des einzelnen Endnutzers.
Wie Root-Agenten auf API-Methoden zugreifen

Wenn ein MCP-Client eine Verbindung zu https://geminidataanalytics.googleapis.com/mcp herstellt, ruft er die Standard-MCP-Methode tools/list auf, um die von der konversationellen Analyse API bereitgestellten Toolschemas dynamisch zu importieren. Der Root-Agent interagiert dann mit der API für konversationelle Analyse, indem er diese MCP-Tools und ‑Ressourcen aufruft, die direkt den zugrunde liegenden REST API-Methoden zugeordnet sind:

MCP-Tool oder ‑Ressource Zugeordnete konversationelle Analyse API-Methode So verwendet der Stamm-Agent die Funktion
list_data_agents projects.locations.dataAgents.list

Sucht nach verfügbaren Daten-Agenten. Der Root-Agent übergibt das Ziel PROJECT_ID (und LOCATION) und erhält eine Liste der aktiven Daten-KI-Agenten, auf die der Nutzer zugreifen darf, einschließlich der ID und Beschreibung jedes KI-Agenten. Der Stamm-Agent wertet diese Beschreibungen aus, um zu bestimmen, welcher Daten-Agent die Frage des Nutzers beantworten kann.

Tipp: Fügen Sie die Ziel-PROJECT_ID in die benutzerdefinierten Systemanweisungen des Root-Agenten ein, damit der Root-Agent geschäftliche Nutzer nicht auffordert, eine Projekt-ID anzugeben.

get_data_agent

(oder die MCP-Ressource gda://agents/AGENT_ID)

 projects.locations.dataAgents.get

Prüft die Metadaten und den Kontext eines bestimmten KI-Datenagenten. Der Root-Agent übergibt das Ziel-AGENT_ID, um Konfigurationsdetails wie verbundene BigQuery-Tabellen, Systemanweisungen, Glossare oder verifizierte Abfragen abzurufen, wenn die Agentenbeschreibungen allein nicht ausreichen, um einen komplexen Prompt weiterzuleiten.
chat projects.locations.chat

Dient als Ausführungsproxy für konversationelle Abfragen. Um einen erkannten KI-Datenagenten abzufragen, übergibt der Root-Agent data_agent_context mit dem vollständigen Ressourcennamen des KI-Agenten (projects/PROJECT_ID/locations/LOCATION/dataAgents/AGENT_ID) und der Nachricht des Nutzers in natürlicher Sprache in messages. Bei zustandslosen Ad-hoc-Anfragen kann der Root-Agent stattdessen inline_context übergeben. Das Tool gibt Antworten in natürlicher Sprache, generierte SQL-Abfragen, Ergebniszeilen, Vega-Lite-Diagrammspezifikationen und die Schlussfolgerungen des KI-Agenten zurück.

MCP Toolbox for Databases

Sie können auch über den Open-Source-Server MCP Toolbox for Databases auf die API für konversationelle Analyse zugreifen. Dieser Server bietet vordefinierte, MCP-kompatible Tools, die die Methode chat in der konversationellen Analyse API bereitstellen:

MCP ist eine Interoperabilitätsebene, die Analysefunktionen als Tools für MCP-kompatible Clients bereitstellt, und kein separates Ausführungsmodell der konversationellen Analyse-API.

MCP-Implementierungsmuster für eigenständige und ADK-Architekturen

Sie können MCP mit den folgenden Mustern implementieren:

Muster Details
Eigenständiges MCP (ohne ADK)

Verwenden Sie den MCP Toolbox for Databases-Server als eigenständigen Server, um eine Verbindung zu einem beliebigen MCP-kompatiblen Client herzustellen. Dieses Muster wird häufig für die folgenden Aufgaben verwendet:

  • IDE-Integration: Verbinden Sie eine IDE wie Antigravity, Cursor oder VS Code mit dem Server, um Daten im Editor im Dialog abzufragen.
  • Benutzerdefinierter MCP-Client: Erstellen Sie eine Anwendung, die den Server verwendet, um eine einheitliche Tool-Schnittstelle für mehrere KI-Anbieter bereitzustellen.
  • Gemini CLI: Verwenden Sie die CLI als MCP-Client für terminalbasierte Datenkonversationen.
MCP im ADK

Das ADK-Framework bietet die folgenden Mechanismen zum Einbinden von MCP-Servern in Agenten-Workflows:

  • ToolboxToolset: Eine spezielle Variante für den MCP Toolbox for Databases-Server, die mehrere Authentifizierungsmethoden unterstützt.
  • McpToolset: Verbindet einen ADK-Agenten über lokale oder Remote-MCP-Serververbindungen mit einem beliebigen MCP-Server. Erkennt automatisch die Tools des Servers und stellt sie dem Agenten zur Verfügung.

Sie können auch MCP-Server mit dem FastMCP-Framework erstellen, um Tools, die mit dem ADK-Framework erstellt wurden, für jeden MCP-kompatiblen Client verfügbar zu machen. Bei diesem Ansatz werden Ihre ADK-Agenten als Tools in anderen Ökosystemen verfügbar gemacht.

Wählen Sie ein Integrationsmuster aus, das den spezifischen Architekturanforderungen Ihrer Anwendung entspricht:

  • Die Verwendung integrierter ADK-Toolsets (Agent Development Kit) wie BigQueryToolset oder DataAgentToolset ermöglicht eine engere Integration ohne Abhängigkeiten von externen Servern. Dieser Ansatz ist ideal für Systeme, die vollständig im ADK-Framework vorhanden sind.
  • Die Verwendung der Tools in der MCP Toolbox ermöglicht die Interoperabilität zwischen MCP-kompatiblen Clients. Dieser Ansatz ist ideal für Datentools, die mehrere Verbraucheranwendungen oder IDEs von Drittanbietern bedienen müssen.

Horizontale Orchestrierung (A2A)

Das Agent-to-Agent-Protokoll (A2A) ist ein offener Standard, der es spezialisierten Agenten auf verschiedenen Systemen ermöglicht, sicher zu kommunizieren und zusammenzuarbeiten, ohne dass benutzerdefinierter Integrationscode erforderlich ist.

Wenn Systeme skaliert werden, stellen Unternehmen häufig mehrere spezialisierte Agenten bereit, die auf verschiedenen Frameworks oder Cloud-Infrastrukturen basieren. A2A richtet eine universelle Messaging-Ebene für diese autonomen Agenten ein. Anstatt benutzerdefinierte APIs zu verwenden, veröffentlicht jeder Agent eine Agentenkarte. Das ist ein auffindbares Profil, in dem die Funktionen, unterstützten Datenformate und Sicherheitsanforderungen des Agenten aufgeführt sind.

Wenn ein zentraler Orchestrator oder ein Peer-Agent analytische Daten benötigt, delegiert er die Aufgabe über strukturierte A2A-Nachrichten sicher an einen Daten-Agenten. Der Daten-Agent verarbeitet die Anfrage autonom und gibt die Ergebnisse zurück. Dadurch wird die Ausführungslogik vom Anfragenden entkoppelt.

Informationen zum Entdecken von Daten-Agent-Karten, Senden von Nachrichten und Streamen strukturierter Artefakte mit dem A2A-Protokoll finden Sie unter Daten-Agenten mit A2A orchestrieren.

Integrationsmuster auswählen

In der folgenden Tabelle werden die Komplexität, die Governance und die Funktionen der einzelnen Integrationsmuster verglichen.

Die Komplexitätsstufen sind so definiert:

  • Niedrig: Muster, die nur minimalen benutzerdefinierten Code erfordern und auf vordefinierten Benutzeroberflächen oder Tools basieren.
  • Mittel: Muster, die eine benutzerdefinierte Frontend-Entwicklung und API- oder SDK-Integration erfordern, aber keine komplexe Backend-Orchestrierungsinfrastruktur.
  • Hoch: Muster, die eine Full-Stack-Anwendungsentwicklung, die Verwaltung des Konversationsstatus, mehrere Authentifizierungsebenen oder eine Zwischeninfrastruktur für die Orchestrierung erfordern.
  • Variiert: Muster, bei denen die Komplexität von der zugrunde liegenden Integrationsmethode abhängt, die Sie auswählen.
Integrationsmuster Komplexität Anpassung KI-Agenten-Governance Zugriffssteuerung Mehrere KI-Agenten Streaming Portabilität
Looker-iFrame-Einbettung Niedrig Niedrig Über Looker verwaltet Looker Nein Integriert Nur Looker
Looker API und SDKs Mittel Hoch Über Looker verwaltet Looker Nein Integriert Nur Looker
Konversationelle Analyse API mit Looker-Quelle Variabel Hoch Über die API verwaltet Looker und IAM Ja Ja Beliebige Google Cloud Oberfläche
Einzelner Agent (direkte API) Mittel Hoch Über die API verwaltet IAM Nein Ja (unterstützt) Beliebige Google Cloud Oberfläche
Benutzerdefinierter Orchestrator Hoch Sehr hoch Über die API verwaltet IAM Manuell Manuell Beliebige Google Cloud Oberfläche
Schemagesteuert mit BigQueryToolset (ADK) Niedrig Mittel Keine (Schema-Inferenz) IAM Ja (ADK) Nein (blockierend) ADK-Ökosystem
Mit DataAgentToolset (ADK) verwaltet Niedrig Mittel Über die API verwaltet IAM Ja (ADK) Nein (blockierend) ADK-Ökosystem
Benutzerdefinierter Streaming-Sub-Agent (ADK) Hoch Sehr hoch Über die API verwaltet IAM Ja (ADK) Ja (benutzerdefiniert) ADK-Ökosystem
Eigenständiger MCP Mittel Mittel Keine (Schema-Inferenz) IAM Nein Nein Beliebiger MCP-Client
MCP im ADK Mittel Hoch Keine (Schema-Inferenz) IAM Ja (ADK) Nein ADK- und MCP-Clients
A2A-Protokoll Hoch Hoch Framework-abhängig IAM Ja Ja Plattformübergreifend

Nächste Schritte