KI-Datenagenten erstellen und mit Ihren Daten chatten

Wichtig: Die Data QnA API wird nicht mehr unterstützt. Wenn Sie von der Data QnA API migrieren, finden Sie in der Migrationsanleitung eine Übersicht über die wichtigsten Unterschiede und erforderlichen Migrationsschritte.

Mit der über geminidataanalytics.googleapis.com oder regionale Endpunkte aufrufbaren Conversational Analytics API können Entwickler eine auf künstlicher Intelligenz (KI) basierende Chat-Oberfläche oder einen Daten-Agenten erstellen. Die API verwendet natürliche Sprache, um Fragen zu strukturierten Daten in BigQuery, Looker, Data Studio und Datenbankdatenquellen (AlloyDB, GoogleSQL for Spanner, Cloud SQL for MySQL und Cloud SQL for PostgreSQL in der Vorabversion in v1beta) zu beantworten. Neben Unterhaltungen in mehreren Runden können Sie die Methode QueryData verwenden, um Single-Turn-Abfragen auszuführen.

Über die Conversational Analytics API stellen Sie Ihrem Daten-Agenten Informationen zum Unternehmen und Daten (Kontext) sowie Zugriff auf Tools wie SQL, Python und Bibliotheken zur Visualisierung zur Verfügung. Die Antworten des KI-Agenten werden dem Nutzer präsentiert und können von der Clientanwendung protokolliert werden, wodurch ein nahtloser Chat mit prüfbaren Daten entsteht.

Erfahren Sie, wann und wie Gemini für Google Cloud Ihre Daten verwendet

Da es sich bei Produkten von Gemini für Google Cloudum Technologie in einem frühen Entwicklungsstadium handelt, kann es zu Ergebnissen kommen, die zwar plausibel erscheinen, aber faktisch falsch sind. Ausgaben der Produkte von Gemini für Google Cloud sollten daher vor der Verwendung geprüft werden. Weitere Informationen finden Sie unter Gemini für Google Cloud und verantwortungsbewusste Anwendung von KI.

Erste Schritte mit der Conversational Analytics API

Bevor Sie die Conversational Analytics API verwenden, sollten Sie sich die folgende Dokumentation ansehen, um die verfügbaren Integrationsansätze und die wichtigsten Konzepte zu verstehen:

• Architektur und wichtige Konzepte: Hier erfahren Sie, wie Daten-Agenten Anfragen verarbeiten, welche Workflows für Ersteller und Nutzer von KI-Agenten gelten, welche Konversationsmodi es gibt und welche IAM-Rollen (Identity and Access Management) erforderlich sind.
• Integrationsmuster für Daten-Agents: Vergleichen Sie Architekturansätze, um die beste Verbindungsmethode für Ihre Anwendung zu ermitteln.
• Zustandsverwaltung: Informationen zu zustandsorientierten und zustandslosen Konversationsmodi, zur Verwaltung des Konversationsverlaufs durch die API und zu den ADK-Sitzungsstatusbereichen.
• Sicherheit, Datenschutz, Risiko und Compliance: Hier finden Sie Informationen zu den Sicherheits- und Compliance-Optionen für die Conversational Analytics API.
• Standorte der Conversational Analytics API: Hier finden Sie eine Übersicht über die regionalen oder multiregionalen API-Endpunkte, mit denen Sie den geografischen Standort der Ressourcen, Konfiguration und Daten Ihres KI-Agenten steuern können.

Führen Sie die Schritte in der Dokumentation zu Einrichtung und Voraussetzungen aus, um mit dem Erstellen von Daten-Agents zu beginnen. Anleitungen, Beispielanwendungen, SDKs und andere Entwicklungstools finden Sie unter Anleitungen, Demos und Tools für die Conversational Analytics API.

Einrichtung und Voraussetzungen

Führen Sie die folgenden Schritte aus, bevor Sie die API oder die Beispiele verwenden:

• Conversational Analytics API aktivieren: Hier werden die Voraussetzungen für die Aktivierung der Conversational Analytics API beschrieben.
• Zugriffssteuerung mit IAM: Beschreibt, wie Sie mit Identity and Access Management den Zugriff auf Daten-Agenten freigeben und verwalten.
• Bei einer Datenquelle authentifizieren und eine Verbindung herstellen: Hier finden Sie eine Anleitung zur Authentifizierung bei der API und zum Konfigurieren von Verbindungen zu Ihren BigQuery-, Lakehouse-, Looker-, Data Studio- und Datenbank-Datenquellen (AlloyDB, GoogleSQL for Spanner, Cloud SQL for MySQL und Cloud SQL for PostgreSQL).
• Verbindung zu BigQuery herstellen: Hier werden die erforderlichen Rollen und die Verbindung eines KI-Datenagenten mit BigQuery-Tabellen und ‑Grafiken beschrieben.
• Mit Looker verbinden: Hier wird beschrieben, wie Sie einen Daten-Agenten mit Looker-Explores verbinden und sich bei Ihrer Looker-Instanz authentifizieren.
• Kundenverwaltete Verschlüsselungsschlüssel (CMEK): Hier wird beschrieben, wie Sie Ihre eigenen Verschlüsselungsschlüssel in Cloud Key Management Service verwenden, um Daten-Agenten und Unterhaltungen zu schützen.
• Einschränkungen für Organisationsrichtlinien: Hier wird beschrieben, wie Sie vordefinierte Einschränkungen für Organisationsrichtlinien verwenden, um Ressourcen auf Organisations-, Ordner- oder Projektebene zu steuern.

Daten-Agenten erstellen und mit einem Daten-Agenten interagieren

Nachdem Sie die vorherigen Schritte ausgeführt haben, können Sie mit der Conversational Analytics API einen KI-Datenagenten erstellen und mit dem KI-Datenagenten interagieren. Gehen Sie dazu so vor:

• KI-Datenagenten mit HTTP erstellen: Hier finden Sie ein vollständiges Beispiel für das Erstellen und Interagieren mit einem KI-Datenagenten mithilfe direkter HTTP-Anfragen mit Python.
• Daten-KI-Agenten mit dem Python SDK erstellen: Hier finden Sie ein vollständiges Beispiel für das Erstellen und Interagieren mit einem Daten-KI-Agenten mit dem Python SDK.
• Daten-Agents mit A2A orchestrieren: Hier erfahren Sie, wie Sie agentische Funktionen ermitteln, analytische Abfragen delegieren und SQL-Abfragen und Diagrammvisualisierungen über Multi-Agenten-Systeme streamen.
• Verhalten von KI-Agenten mit selbst erstelltem Kontext steuern: Hier erfahren Sie, wie Sie selbst erstellten Kontext bereitstellen, um das Verhalten von KI-Agenten zu steuern und die Accuracy der Antworten zu verbessern. Beispiele für selbst erstellten Kontext finden Sie auch unter BigQuery-Datenquellen und Looker-Datenquellen.

• Eine Antwort eines Conversational Analytics API-Agenten als Visualisierung rendern: Hier finden Sie ein Beispiel für die Verarbeitung von Diagrammspezifikationen aus API-Antworten und das Rendern als Visualisierungen mit dem Python SDK und der Vega-Altair-Bibliothek.

  Hinweis: Das Rendern von Visualisierungen wird für Datenbankdatenquellen (AlloyDB, GoogleSQL for Spanner, Cloud SQL for MySQL und Cloud SQL for PostgreSQL) nicht unterstützt.

Best Practices

In den folgenden Anleitungen finden Sie Best Practices für die Verwendung der Conversational Analytics API:

• BigQuery-Kosten für Ihre KI-Agenten verwalten: Hier erfahren Sie, wie Sie die BigQuery-Kosten für Ihre Conversational Analytics API-Agenten überwachen und verwalten, indem Sie Ausgabenlimits auf Projekt-, Nutzer- und Abfrageebene festlegen.
• Effektive Fragen stellen: Hier erfahren Sie, wie Sie effektive Fragen für Ihre KI-Agenten formulieren, um die Conversational Analytics API optimal zu nutzen.
• Datenaufbewahrung und -löschung: Informationen zur Datenaufbewahrung und -löschung für Daten-Agents und Unterhaltungen der Conversational Analytics API.
• Kontingente und Limits: Informationen zu den Kontingenten und Limits für die Conversational Analytics API.
• Fehler bei der Conversational Analytics API beheben: Häufige Fehler der Conversational Analytics API beheben.
• Bekannte Einschränkungen: Hier finden Sie detaillierte Informationen zu bekannten Einschränkungen der Conversational Analytics API, einschließlich Einschränkungen bei Abfragen, Daten, Visualisierungen und Fragen.
• Agent-Antworten für Looker-Datenquellen rendern: Hier finden Sie Best Practices zum Rendern von Antworten der Conversational Analytics API in einer Benutzeroberfläche, wenn Sie Looker-Datenquellen verwenden.

API-Referenz und Clientbibliotheken

• REST-Referenz für Gemini Data Analytics: Hier finden Sie detaillierte Beschreibungen von API-Versionen, Methoden, Endpunkten und Typdefinitionen.
• SDKs und Entwicklungstools: Hier werden sprachspezifische Clientbibliotheken aufgeführt.

Wichtige API-Vorgänge

Die API bietet die folgenden Kernendpunkte zum Verwalten von KI-Datenagenten und Unterhaltungen: Die v1-Endpunkte in der folgenden Tabelle unterstützen BigQuery-, Looker- und Data Studio-Datenquellen. Da sich Datenbankdatenquellen in v1beta in der Vorabversion befinden, müssen Sie die entsprechenden /v1beta/-Pfade für Datenbankquellen angeben.

Ersetzen Sie beim Erstellen dieser Pfade (oder der entsprechenden SDK-Ressourcennamen) die Platzhalter (*) durch Ihre Projekt-ID, die Standortkennung (z. B. global oder us) und die Ressourcen-ID (z. B. die Agent-ID oder die Konversations-ID), falls zutreffend.

Wichtig: Der Standort im Anfragepfad muss mit dem Standort des Endpunkts übereinstimmen, den Sie aufrufen. Wenn Sie beispielsweise den Endpunkt geminidataanalytics.us.rep.googleapis.com aufrufen, geben Sie us im Anfragepfad an (z. B. /locations/us). Weitere Informationen zum Datenstandort und zur Endpunktkonfiguration finden Sie unter Datenstandort.

Vorgang	HTTP-Methode	Endpunkt	Beschreibung
KI-Agenten erstellen	POST	/v1/projects/*/locations/*/dataAgents	Erstellt einen neuen KI-Datenagenten.
Agent synchron erstellen	POST	/v1/projects/*/locations/*/dataAgents:createSync	Erstellt einen neuen KI-Datenagenten synchron.
KI-Agenten abrufen	GET	/v1/projects/*/locations/*/dataAgents/*	Ruft die Details zu einem bestimmten Daten-KI-Agenten ab.
Richtlinie für Identity and Access Management abrufen	POST	/v1/projects/*/locations/*/dataAgents/*:getIamPolicy	Ruft die Identity and Access Management-Berechtigungen ab, die den einzelnen Nutzern für einen bestimmten Daten-KI-Agenten zugewiesen sind. Nutzer mit der Rolle Data Agent Owner können diesen Endpunkt aufrufen und sich die entsprechende IAM-Richtlinie (Identity and Access Management) anschauen, bevor sie Daten-KI-Agenten über den setIAMpolicy-Endpunkt für andere Nutzer freigeben.
Identity and Access Management-Richtlinie festlegen	POST	/v1/projects/*/locations/*/dataAgents/*:setIamPolicy	Legt die Identity and Access Management-Richtlinie für einen bestimmten Daten-KI-Agenten fest. Nutzer mit der Rolle Data Agent Owner müssen diesen Endpunkt aufrufen, um einen Daten-KI-Agenten für andere Nutzer freizugeben. Dadurch werden die Identity and Access Management-Berechtigungen dieser Nutzer aktualisiert.
KI-Agenten aktualisieren	PATCH	/v1/projects/*/locations/*/dataAgents/*	Ändert einen vorhandenen KI-Datenagenten.
KI-Agenten synchron aktualisieren	PATCH	/v1/projects/*/locations/*/dataAgents/*:updateSync	Ändert einen vorhandenen KI-Datenagenten synchron.
KI-Agenten auflisten	GET	/v1/projects/*/locations/*/dataAgents	Listet die verfügbaren Daten-KI-Agenten in einem Projekt auf.
Verfügbare KI-Agenten auflisten	GET	/v1/projects/*/locations/*/dataAgents:listaccessible	Listet die verfügbaren Daten-KI-Agenten in einem Projekt auf. Ein Daten-KI-Agent gilt als verfügbar, wenn der Nutzer, der diese API aufruft, die Berechtigung get für den KI-Agent hat. Mit dem Feld creator_filter können Sie festlegen, welche KI-Agenten von dieser Methode zurückgegeben werden: NONE (Standard): Gibt alle Daten-KI-Agenten zurück, auf die der Nutzer zugreifen kann, unabhängig davon, wer die KI-Agenten erstellt hat. CREATOR_ONLY: Gibt nur die Daten-KI-Agenten zurück, auf die der Nutzer zugreifen kann und die von diesem Nutzer erstellt wurden. NOT_CREATOR_ONLY: Gibt nur die Daten-KI-Agenten zurück, auf die der Nutzer zugreifen kann und die von anderen erstellt wurden.
KI-Agenten löschen	DELETE	/v1/projects/*/locations/*/dataAgents/*	Entfernt einen KI-Datenagenten.
KI-Agenten synchron löschen	DELETE	/v1/projects/*/locations/*/dataAgents/*:deleteSync	Entfernt einen KI-Datenagenten synchron.
Unterhaltung erstellen	POST	/v1/projects/*/locations/*/conversations	Startet eine neue, dauerhafte Unterhaltung.
Mit Unterhaltungsverweis chatten	POST	/v1/projects/*/locations/*:chat	Setzt eine zustandsorientierte Unterhaltung fort, indem eine Chatnachricht gesendet wird, die auf eine vorhandene Unterhaltung und den zugehörigen KI-Agentenkontext verweist. Bei Multi-Turn-Unterhaltungen speichert und verwaltet Google Cloud den Unterhaltungsverlauf.
Mit KI-Datenagentenverweis chatten	POST	/v1/projects/*/locations/*:chat	Sendet eine zustandslose Chatnachricht, die zur Kontextualisierung auf einen gespeicherten KI-Datenagenten verweist. Bei Multi-Turn-Unterhaltungen muss Ihre Anwendung den Unterhaltungsverlauf verwalten und bei jeder Anfrage bereitstellen.
Mit Inline-Kontext chatten	POST	/v1/projects/*/locations/*:chat	Sendet eine zustandslose Chatnachricht, indem der gesamte Kontext direkt in der Anfrage angegeben wird, ohne einen gespeicherten KI-Datenagenten zu verwenden. Bei Multi-Turn-Unterhaltungen muss Ihre Anwendung den Unterhaltungsverlauf verwalten und bei jeder Anfrage bereitstellen.
Unterhaltung abrufen	GET	/v1/projects/*/locations/*/conversations/*	Ruft die Details zu einer bestimmten Unterhaltung ab.
Unterhaltungen auflisten	GET	/v1/projects/*/locations/*/conversations	Listet die Unterhaltungen in einem bestimmten Projekt auf.
Nachrichten in einer Unterhaltung auflisten	GET	/v1/projects/*/locations/*/conversations/*/messages	Listet Nachrichten in einer bestimmten Unterhaltung auf.
Unterhaltungen löschen	DELETE	/v1/projects/*/locations/*/conversations/*	Löscht eine bestimmte Unterhaltung. Zum Aufrufen dieses Endpunkts ist die IAM-Rolle (Identity and Access Management) Topic Admin oder mindestens die IAM-Berechtigung cloudaicompanion.topics.delete erforderlich.
Daten abfragen	POST	/v1beta/projects/*/locations/*/conversations:queryData	Fragt Daten aus AlloyDB-, GoogleSQL for Spanner-, Cloud SQL for MySQL- und Cloud SQL for PostgreSQL-Datenbanken in natürlicher Sprache ab.
Agentenkarte abrufen (A2A)	GET	/v1/a2a/projects/*/locations/*/agents/*/v1/card	Ruft die Funktionen, Skills und unterstützten Erweiterungen für einen integrierten oder benutzerdefinierten KI-Datenagenten mithilfe des A2A-Protokolls ab.
Nachricht senden (A2A)	POST	/v1/a2a/projects/*/locations/*/agents/*/v1/message:send	Sendet eine Nachricht an einen KI-Datenagenten über das A2A-Protokoll.
Streamingnachricht senden (A2A)	POST	/v1/a2a/projects/*/locations/*/agents/*/v1/message:stream	Sendet eine Streaming-Nachricht an einen Daten-Agenten über das A2A-Protokoll und gibt den Echtzeit-Fortschritt der Argumentation und strukturierte Artefakte (wie SQL-Abfragen und Diagrammvisualisierungen) zurück.

Support und Feedback

Wenn Sie Hilfe benötigen oder ein Problem melden möchten, wenden Sie sich an den Kundendienst. Folgen Sie der Anleitung unter Supportanfragen erstellen und verwalten, um eine Supportanfrage zu erstellen. Beachten Sie beim Erstellen des Falls die folgenden Richtlinien:

• Wenn Sie Support für die Conversational Analytics API mit BigQuery benötigen, wählen Sie in der Liste Produkt auswählen die Option BigQuery und im Feld Feature die Option KI und maschinelles Lernen::Conversational Analytics API in BigQuery aus.
• Wenn Sie Support für die Conversational Analytics API mit Looker benötigen, wählen Sie in der Liste Produkt auswählen die Option Looker (Original) und im Feld Funktion die Option Gemini in Looker::Conversational Analytics API aus.

Hinweis: Der Support für die Conversational Analytics API umfasst technische Probleme im Zusammenhang mit der Nutzung des API-Dienstes. Das Debugging von allgemeinem und benutzerdefiniertem Code ist nicht Gegenstand der Prüfung. Kunden sind für das Debugging ihres eigenen benutzerdefinierten Codes verantwortlich.

Wenn Sie allgemeines Feedback oder Fragen zur Conversational Analytics API haben, senden Sie eine E-Mail an [e-mail]. Wir können nicht garantieren, dass wir auf E-Mails antworten, aber wir lesen sie und berücksichtigen dieses Feedback bei der Planung der Roadmap.

Sie können auch einen Feature Request für neue Funktionen der Conversational Analytics API einreichen.