KI-Datenagenten mit HTTP und Python erstellen

Auf dieser Seite wird beschrieben, wie Sie mit Python HTTP-Anfragen an die Conversational Analytics API (Zugriff über geminidataanalytics.googleapis.com) senden.

Das Python-Codebeispiel auf dieser Seite zeigt, wie Sie die folgenden Aufgaben ausführen:

• Erste Einstellungen und Authentifizierung konfigurieren
• Mit einer Looker-, BigQuery-, Data Studio-, AlloyDB for PostgreSQL-, Cloud SQL- oder Spanner-Datenquelle verbinden
• Daten-Agenten erstellen
• Unterhaltung erstellen
• KI-Datenagenten und Unterhaltungen verwalten
• API zum Stellen von Fragen verwenden
• Zustandslose Multi-Turn-Unterhaltung erstellen
• Hilfsfunktionen definieren

Tipp: Sie können die Codebeispiele auf dieser Seite im interaktiven Colaboratory-Notebook für die Conversational Analytics API ausführen.

Erste Einstellungen und Authentifizierung konfigurieren

Mit dem folgenden Python-Beispielcode werde diese Aufgaben ausgeführt:

• Importiert die erforderlichen Python-Bibliotheken.
• Über die Google Cloud CLI ein Zugriffstoken für die HTTP-Authentifizierung abrufen
• Definiert Variablen für das Abrechnungsprojekt, den Standort und die Systemanweisungen.
• Legt den API-Endpunkt basierend auf der Variable location fest.

import json
import json as json_lib
import textwrap

import altair as alt
import google.auth
from google.auth.transport.requests import Request
import IPython
from IPython.display import display, HTML
import pandas as pd
from pygments import highlight, lexers, formatters
import requests

from google.colab import auth
auth.authenticate_user()

access_token = !gcloud auth application-default print-access-token
headers = {
        "Authorization": f"Bearer {access_token[0]}",
        "Content-Type": "application/json",
        "x-server-timeout": "300", # Custom timeout up to 600s
}

billing_project = "BILLING_PROJECT"
location = "LOCATION"
system_instruction = "SYSTEM_INSTRUCTIONS"

# Set the base URL based on location.
if not location or location == "global":
  base_url = "https://geminidataanalytics.googleapis.com"
elif "-" in location:
  # Regional endpoints
  base_url = f"https://geminidataanalytics-{location}.googleapis.com"
else:
  # Multi-regional endpoints
  base_url = f"https://geminidataanalytics.{location}.rep.googleapis.com"

Ersetzen Sie die Beispielwerte so:

• BILLING_PROJECT: Die ID des Google Cloud -Projekts, in dem Sie die erforderlichen APIs aktiviert haben.

• LOCATION: Der Standort, an dem Ihre Ressourcen gespeichert sind. Wenn Sie den globalen Endpunkt verwenden möchten, geben Sie global an. Wenn Sie die Anforderungen an den Datenstandort erfüllen möchten, geben Sie eine unterstützte einzelne Region (z. B. us-east4) oder eine Multiregion (z. B. eu oder us) an. Weitere Informationen finden Sie unter Datenstandort.

  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).

• SYSTEM_INSTRUCTIONS: die Systemanweisungen, um das Verhalten des KI-Agenten zu steuern und an Ihre Datenanforderungen anzupassen. Sie können beispielsweise Systemanweisungen verwenden, um geschäftliche Begriffe zu definieren, die Länge der Antworten zu steuern oder die Datenformatierung festzulegen. Am besten definieren Sie die Systemanweisungen im empfohlenen YAML-Format, das unter Effektive Systemanweisungen schreiben beschrieben wird, um detaillierte und strukturierte Anleitungen festzulegen.

Bei Looker authentifizieren

Wenn Sie eine Looker-Datenquelle verbinden möchten, müssen Sie sich bei der Looker-Instanz authentifizieren.

API-Schlüssel verwenden

Das folgende Python-Codebeispiel zeigt, wie Sie Ihren KI-Agenten mithilfe von API-Schlüsseln bei einer Looker-Instanz authentifizieren.

looker_credentials = {
    "oauth": {
        "secret": {
            "client_id": "CLIENT_ID",
            "client_secret": "CLIENT_SECRET",
        }
    }
}

Ersetzen Sie die Beispielwerte folgendermaßen:

• CLIENT_ID: die Client-ID Ihres generierten Looker API-Schlüssels.
• CLIENT_SECRET: der Clientschlüssel Ihres generierten Looker API-Schlüssels.

Zugriffstokens verwenden

Das folgende Python-Codebeispiel zeigt, wie Sie Ihren KI-Agenten mithilfe von Zugriffstokens bei einer Looker-Instanz authentifizieren.

looker_credentials = {
    "oauth": {
        "token": {
            "access_token": "ACCESS_TOKEN",
        }
    }
}

Ersetzen Sie die Beispielwerte so:

• ACCESS_TOKEN: der access_token-Wert, den Sie zur Authentifizierung bei Looker generieren.

Tipp: Speichern Sie das Looker-Zugriffstoken (access_token) aus Sicherheitsgründen als Umgebungsvariable.

Bei AlloyDB for PostgreSQL authentifizieren

Wenn Sie eine Verbindung zu einer AlloyDB-Datenquelle herstellen möchten, verwenden Sie die gcloud CLI, um sich bei der AlloyDB-Instanz zu authentifizieren.

1. Aktivieren Sie die IAM-Authentifizierung (Identity and Access Management) in AlloyDB, indem Sie das Flag alloydb.iam_authentication für die AlloyDB-Instanz aktivieren.
2. Weisen Sie IAM-Rollen zu. Das Hauptkonto (Nutzer- oder Dienstkonto), das die Conversational Analytics API aufruft, benötigt die entsprechenden IAM-Berechtigungen in Ihrem Projekt inGoogle Cloud . Dazu gehören in der Regel Rollen wie alloydb.databaseUser.
3. Erstellen Sie einen entsprechenden Datenbanknutzer. Erstellen Sie einen AlloyDB-Nutzer, der das IAM-Hauptkonto widerspiegelt. Verwenden Sie dazu die E-Mail-Adresse des Nutzers oder Dienstkontos als Nutzernamen.

Weitere Informationen finden Sie unter IAM-Datenbankauthentifizierung.

Bei Cloud SQL for MySQL und Cloud SQL for PostgreSQL authentifizieren

Wenn Sie eine Verbindung zu einer Cloud SQL for MySQL- oder Cloud SQL for PostgreSQL-Datenquelle herstellen möchten, müssen Sie sich bei der Cloud SQL-Instanz authentifizieren.

1. Aktivieren Sie die IAM-Datenbankauthentifizierung. Achten Sie darauf, dass das Flag cloudsql.iam_authentication in Ihrer Cloud SQL for MySQL-Instanz auf on gesetzt ist. Sie können diese Angabe beim Erstellen einer Instanz oder beim Patchen einer vorhandenen Instanz hinzufügen.

   gcloud sql instances patch INSTANCE_NAME --database-flags
   cloudsql.iam_authentication=on
   

2. Weisen Sie die erforderlichen IAM-Rollen zu.

   Das Hauptkonto (Nutzer- oder Dienstkonto), das versucht, eine Verbindung herzustellen, benötigt die IAM-Berechtigungen cloudsql.instances.login und cloudsql.instances.connect für das Projekt. So weisen Sie diese Rollen und Berechtigungen zu:

   1. Weisen Sie die Rolle roles/cloudsql.instanceUser zu. Dazu gehören Berechtigungen zum Anmelden bei der Instanz (cloudsql.instances.login) und zum Herstellen einer Verbindung über den Proxy (cloudsql.instances.connect).
   2. Alternativ können Sie eine benutzerdefinierte Rolle mit mindestens cloudsql.instances.login und cloudsql.instances.connect zuweisen.

3. Fügen Sie das IAM-Hauptkonto als Datenbanknutzer hinzu. Erstellen Sie in der Cloud SQL-Instanz einen Nutzer, der der E-Mail-Adresse des IAM-Hauptkontos entspricht.

   Führen Sie für ein Dienstkonto den folgenden Befehl aus:

   gcloud sql users create SERVICE_ACCOUNT_EMAIL --instance=INSTANCE_NAME
   --type=cloud_iam_service_account
   

   Führen Sie für ein Nutzerkonto den folgenden Befehl aus:

   gcloud sql users create USER_EMAIL --instance=INSTANCE_NAME
   --type=cloud_iam_user
   

4. Datenbankberechtigungen gewähren Durch die Verbindung mit IAM wird der Nutzer bei der Datenbank authentifiziert, aber es werden nicht automatisch Berechtigungen in der Datenbank gewährt. Sie müssen standardmäßige PostgreSQL-Befehle wie GRANT verwenden, um diesem neuen Datenbanknutzer Berechtigungen für bestimmte Objekte wie Tabellen und Schemas zu gewähren.

5. Stellen Sie eine Verbindung als Superuser her, z. B. als Standard-Postgres-Nutzer, und führen Sie die folgenden Befehle aus:

   -- Example: Connect using psql as the 'postgres' user
   
   GRANT SELECT ON ALL TABLES IN SCHEMA public TO
   "[e-mail]";
   

6. Verbindung über die IAM-Authentifizierung herstellen.

   Clients stellen in der Regel eine Verbindung über den Cloud SQL Auth-Proxy oder eine Connector-Bibliothek her, die den Tokenaustausch übernimmt. Der Datenbank-Nutzername ist die E-Mail-Adresse des IAM-Hauptkontos. Passwörter werden nicht verwendet. Stattdessen wird ein OAuth 2.0-Token verwendet, das normalerweise automatisch vom Cloud SQL Auth-Proxy oder von der Google Cloud CLI verarbeitet wird.

   Im folgenden Beispiel werden psql und die gcloud CLI verwendet, um ein Token zu generieren:

   PGPASSWORD=$(gcloud sql generate-login-token) psql --host=HOST_IP \
   --username=IAM_PRINCIPAL_EMAIL --dbname=DATABASE_NAME\
   

   Weitere Informationen finden Sie unter IAM-Authentifizierung.

   Ersetzen Sie die Beispielwerte so:

   • INSTANCE_NAME: die ID der Cloud SQL-Instanz, die Sie patchen möchten, um die IAM-Datenbankauthentifizierung zu aktivieren.
   • SERVICE_ACCOUNT_EMAIL: die E-Mail-Adresse des Dienstkontos.
   • USER_EMAIL: die E-Mail-Adresse des Nutzerkontos.
   • HOST_IP: die IP-Adresse der Cloud SQL-Instanz.
   • IAM_PRINCIPAL_EMAIL: die E-Mail-Adresse des IAM-Hauptkontos, z. B. Dienstkonto oder Nutzer.
   • DATABASE_NAME: Der Name der Datenbank, zu der eine Verbindung hergestellt werden soll.

Bei Cloud Spanner authentifizieren

Wenn Sie eine Verbindung zu einer Cloud Spanner-Datenquelle herstellen möchten, müssen Sie sich bei der Cloud Spanner-Instanz authentifizieren.

1. Weisen Sie IAM-Rollen zu. Das Hauptkonto (Nutzer- oder Dienstkonto), das die Conversational Analytics API aufruft, benötigt die entsprechenden IAM-Berechtigungen in Ihrem Projekt inGoogle Cloud . Dazu gehören in der Regel Rollen wie databaseUser.
2. Erstellen Sie entsprechende abstrakte Datenbankrollen in Spanner mithilfe der Datendefinitionssprache (DDL).
3. Verwenden Sie IAM-Richtlinien, damit IAM-Hauptkonten diese Datenbankrollen übernehmen können.

Weitere Informationen finden Sie unter Berechtigungen für die detaillierte Zugriffssteuerung.

Mit einer Datenquelle verbinden

In den folgenden Abschnitten wird beschrieben, wie Sie die Verbindungsdetails für die Datenquellen Ihres KI-Agenten definieren. Ihr KI-Agent kann auf folgende Weise eine Verbindung zu Daten herstellen:

• Looker
• Data Studio
• BigQuery
• AlloyDB-Daten
• Cloud SQL for MySQL-Daten
• Cloud SQL for PostgreSQL-Daten
• Spanner-Daten

Verbindung zu Looker-Daten herstellen

Im folgenden Beispielcode wird eine Verbindung zu einem Looker-Explore definiert. Um eine Verbindung zu einer Looker-Instanz herzustellen, müssen Sie Looker API-Schlüssel generieren, wie unter Authentifizieren und eine Verbindung zu einer Datenquelle herstellen beschrieben. Mit der Conversational Analytics API können Sie gleichzeitige Verbindungen zu bis zu fünf Looker-Explores herstellen.

Beachten Sie Folgendes, wenn Sie eine Verbindung zu einer Looker-Datenquelle herstellen:

• Sie können in einer Unterhaltung jedes enthaltene Explore abfragen.
• Ein KI-Agent kann jeweils nur ein Explore abfragen. Abfragen für mehrere Explores können nicht gleichzeitig ausgeführt werden.
• Ein KI-Agent kann in derselben Unterhaltung mehrere Explores abfragen.

• Ein Agent kann in einer Unterhaltung, die Fragen mit mehreren Teilen oder Folgefragen enthält, mehrere Explores abfragen.

  Beispiel: Ein Nutzer verbindet zwei Explores, eins mit dem Namen cat-explore und eins mit dem Namen dog-explore. Der Nutzer gibt die Frage „Was ist größer: die Anzahl der Katzen oder die Anzahl der Hunde?“ ein. Dadurch werden zwei Abfragen erstellt: eine zum Zählen der Anzahl der Katzen in cat-explore und eine zum Zählen der Anzahl der Hunde in dog-explore. Der KI-Agent vergleicht die Anzahl aus beiden Anfragen, nachdem beide Anfragen abgeschlossen sind.

Mit dem folgenden Beispielcode wird eine Verbindung zu mehreren Looker-Explores definiert. Um die Leistung des KI-Agenten zu verbessern, können Sie optional Golden Queries als strukturierten Kontext für Ihre Explores bereitstellen. Weitere Informationen finden Sie unter Kontext für Daten-Agenten für Looker-Datenquellen definieren.

looker_instance_uri = "INSTANCE_URI"
looker_data_source = {
    "looker": {
        "explore_references": [
            {
                "looker_instance_uri": looker_instance_uri,
                "lookml_model": "MODEL",
                "explore": "EXPLORE",
            },
            {
                "looker_instance_uri": looker_instance_uri,
                "lookml_model": "MODEL_2",
                "explore": "EXPLORE_2",
            },
            # Add up to 5 total Explore references
        ],
    }
}

Ersetzen Sie die Beispielwerte so:

• INSTANCE_URI: Die vollständige URL Ihrer Looker-Instanz (z. B. https://mycompany.looker.com).
• MODEL: der Name des LookML-Modells, das den Explore enthält, zu dem Sie eine Verbindung herstellen möchten.
• EXPLORE: der Name des Looker-Explore, das vom KI-Datenagenten abgefragt werden soll.
• MODEL_2: der Name des zweiten LookML-Modells, das das Explore enthält, zu dem Sie eine Verbindung herstellen möchten. Sie können diese Variable für zusätzliche Modelle für bis zu fünf Explores wiederholen.
• EXPLORE_2: der Name des zusätzlichen Looker-Explore, das vom KI-Datenagenten abgefragt werden soll. Sie können diese Variable wiederholen, um bis zu fünf Explores einzuschließen.

Verbindung zu BigQuery-Daten herstellen

Bei der Conversational Analytics API gibt es keine strikten Grenzwerte für die Anzahl der BigQuery-Tabellen, zu denen Sie eine Verbindung herstellen können. Wenn Sie jedoch zu einer großen Anzahl an Tabellen eine Verbindung herstellen, kann dies die Accuracy beeinträchtigen oder dazu führen, dass das Eingabetokenlimit des Modells überschritten wird.

Hinweis: Abfragen, für die komplexe Joins über mehrere Tabellen hinweg erforderlich sind, können zu weniger genauen Antworten führen.

In den folgenden Abschnitten wird beschrieben, wie Sie mithilfe von Tabellenverweisen, Grafikverweisen oder beidem eine Verbindung zu BigQuery-Daten herstellen.

Mit BigQuery-Tabellen verbinden

Mit dem folgenden Beispielcode wird eine Verbindung zu mehreren BigQuery-Tabellen definiert. Er enthält Beispiele für optionale strukturierte Kontextfelder. Um die Leistung des KI-Agenten zu verbessern, können Sie optional strukturierten Kontext für Ihre BigQuery-Tabellen bereitstellen, z. B. Tabellen- und Spaltenbeschreibungen, Synonyme, Tags, Beispielabfragen und benutzerdefinierte Funktionen. Weitere Informationen finden Sie unter Kontext für Daten-Agenten für BigQuery-Datenquellen definieren.

Wichtig: Sie benötigen die erforderlichen IAM-Berechtigungen (Identity and Access Management), um die verbundenen BigQuery-Tabellen abzufragen.

bigquery_data_sources = {
    "bq": {
        "tableReferences": [
            {
                "projectId": "PROJECT_ID",
                "datasetId": "DATASET_ID",
                "tableId": "TABLE_ID",
                "schema": {
                    "description": "TABLE_DESCRIPTION",
                    "fields": [{
                        "name": "COLUMN_NAME",
                        "description": "COLUMN_DESCRIPTION"
                    }]
                }
            },
            {
                "projectId": "PROJECT_ID_2",
                "datasetId": "DATASET_ID_2",
                "tableId": "TABLE_ID_2"
            },
            {
                "projectId": "PROJECT_ID_3",
                "datasetId": "DATASET_ID_3",
                "tableId": "TABLE_ID_3"
            },
        ]
    }
}

Ersetzen Sie die Beispielwerte folgendermaßen:

• PROJECT_ID: die ID des Projekts in Google Cloud , das das BigQuery-Dataset und die BigQuery-Tabelle enthält, zu denen Sie eine Verbindung herstellen möchten. Wenn Sie eine Verbindung zu einem öffentlichen Dataset herstellen möchten, geben Sie bigquery-public-data an.
• DATASET_ID: Die ID des BigQuery-Datasets.
• TABLE_ID: die ID der BigQuery-Tabelle.
• TABLE_DESCRIPTION: eine optionale Beschreibung des Inhalts und Zwecks der Tabelle.
• COLUMN_NAME: der Name einer Spalte in der Tabelle, für die Sie eine optionale Beschreibung angeben.
• COLUMN_DESCRIPTION: Eine optionale Beschreibung des Inhalts und des Zwecks der Spalte.

Verbindung zu BigQuery Graph herstellen

Sie können auch mit BigQuery Graph eine Verbindung zu Graphen herstellen. Geben Sie im Feld propertyGraphReferences eine oder mehrere Diagrammreferenzen an.

Informationen zu den Anforderungen für BigQuery-Versionen und zu den Einschränkungen für Graphabfragen finden Sie unter Verbindung zu BigQuery Graph herstellen.

bigquery_data_sources = {
    "bq": {
        "propertyGraphReferences": [
          {
            "projectId": "GRAPH_PROJECT_ID",
            "datasetId": "GRAPH_DATASET_ID",
            "propertyGraphId": "GRAPH_ID"
          }
        ]
    }
}

Ersetzen Sie die Beispielwerte so:

• GRAPH_PROJECT_ID: Die ID des Projekts in Google Cloud , das den BigQuery-Graphen enthält.
• GRAPH_DATASET_ID: Die ID des BigQuery-Datasets, das den Graphen enthält.
• GRAPH_ID: Die ID des BigQuery-Diagramms.

Wenn Sie sowohl Tabellen als auch Diagramme mit demselben Daten-Agenten abfragen möchten, fügen Sie sowohl tableReferences als auch propertyGraphReferences in das bq-Objekt ein.

Verbindung zu Data Studio-Daten herstellen

Im folgenden Beispielcode wird eine Verbindung zu einer Data Studio-Datenquelle definiert.

looker_studio_data_source = {
    "studio":{
        "studio_references": [
            {
              "studio_datasource_id": "studio_datasource_id"
            }
        ]
    }
}

Ersetzen Sie studio_datasource_id mit der ID der Datenquelle.

Verbindung zu AlloyDB-Daten herstellen

Die Conversational Analytics API verwendet ein database_reference-Feld im alloydb-Feld, um eine Verbindung zu Ihrem AlloyDB-Cluster herzustellen.

Im folgenden Beispiel wird eine Verbindung zu einer AlloyDB-Datenbank definiert.

alloydb_data_source = {
    "alloydb": {
        "database_reference":
          {
            "project_id":"PROJECT_ID",
            "region":"REGION",
            "cluster_id":"CLUSTER_ID",
            "instance_id":"INSTANCE_ID",
            "database_id":"DATABASE",
            "table_ids":["TABLE_1_ID", "TABLE_2_ID"]
          }
          # Optional: Include this if you have pre-authored context for the agent
          # "agent_context_reference": {
          #     "context_set_id": f"projects/billing_project/locations/location/contextSets/your_context_set_id"
          # }

    }
}

Ersetzen Sie die Beispielwerte so:

• PROJECT_ID: Die ID des Google Cloud -Projekts, das den AlloyDB-Cluster enthält.
• REGION: Die Region, in der sich der AlloyDB-Cluster befindet, z. B. us-central1.
• CLUSTER_ID: Die ID des AlloyDB-Clusters.
• INSTANCE_ID: Die ID der AlloyDB-Instanz.
• DATABASE: Der Name der Zieldatenbank, z. B. financial.
• TABLE_1_ID, TABLE_2_ID: Optional. Eine Liste der Tabellen in der Datenbank, die der KI-Datenagent verwenden soll, z. B. "loan", "client", "disp".
• billing_project: die ID des Abrechnungsprojekts, in dem Sie die erforderlichen APIs aktiviert haben.
• location: Der Speicherort, an dem sich Ihr Kontextset befindet, z. B. global.
• your_context_set_id: Wenn Sie einen erweiterten Kontext für den Agenten erstellt haben, die ID Ihres Kontextsets.

Verbindung zu Cloud SQL for MySQL- und Cloud SQL for PostgreSQL-Daten herstellen

Die Conversational Analytics API verwendet ein database_reference-Feld im sql-Feld, um eine Verbindung zu Ihrer Cloud SQL-Instanz herzustellen.

Im folgenden Beispiel wird eine Verbindung zu einer Cloud SQL for MySQL- oder Cloud SQL for PostgreSQL-Datenbank definiert.

sql_data_source = {
    "cloud_sql_reference": {
        "database_reference":
          {
            "project_id":"PROJECT_ID",
            "region":"REGION",
            "cluster_id":"CLUSTER_ID",
            "instance_id":"INSTANCE_ID",
            "database_id":"DATABASE_ID",
            "table_ids":["TABLE_1_ID", "TABLE_2_ID"]
          }
          # Optional: Include this if you have pre-authored context for the agent
          # "agent_context_reference": {
          #     "context_set_id": f"projects/billing_project/locations/location/contextSets/your_context_set_id"
          # }
    }
}

Ersetzen Sie die Beispielwerte so:

• PROJECT_ID: Die ID des Google Cloud -Projekts, das die Cloud SQL-Instanz enthält.
• REGION: Die Region, in der sich die Cloud SQL-Instanz befindet, z. B. us-central1.
• CLUSTER_ID: Die ID des Cloud SQL-Clusters.
• INSTANCE_ID: Die ID der Cloud SQL-Instanz.
• DATABASE_ID: Der Name der Zieldatenbank, z. B. financial.
• TABLE_1_ID, TABLE_2_ID: Optional. Eine Liste der Tabellen in der Datenbank, die der KI-Datenagent verwenden soll, z. B. "loan", "client", "disp".
• billing_project: die ID des Abrechnungsprojekts, in dem Sie die erforderlichen APIs aktiviert haben.
• location: Der Speicherort, an dem sich Ihr Kontextset befindet, z. B. global.
• your_context_set_id: Wenn Sie einen erweiterten Kontext für den Agenten erstellt haben, die ID Ihres Kontextsets.

Verbindung zu Cloud Spanner-Daten herstellen

Die Conversational Analytics API verwendet ein database_reference-Feld im spanner-Feld, um eine Verbindung zu Ihrer Spanner-Instanz herzustellen.

Im folgenden Beispiel wird eine Verbindung zu einer Cloud Spanner-Datenbank definiert.

spanner_data_sources = {
    "spanner_reference": {
        "database_reference": {
            "project_id": "PROJECT_ID",
            "region": location,
            "engine": GOOGLE_SQL,
            "instance_id": "INSTANCE_ID",
            "database_id": "DATABASE",
            "table_ids":["TABLE_1_ID", "TABLE_2_ID"]
        },
        # Optional: Include this if you have pre-authored context for the agent
        # "agent_context_reference": {
        #     "context_set_id": f"projects/billing_project/locations/location/contextSets/your_context_set_id"
        # }
    }
}

Ersetzen Sie die Beispielwerte so:

• PROJECT_ID: Die ID des Google Cloud -Projekts, das die Spanner-Instanz enthält.
• INSTANCE_ID: Die ID der Spanner-Instanz.
• DATABASE: Der Name der Zieldatenbank, z. B. financial.
• TABLE_1_ID, TABLE_2_ID: Eine Liste der Tabellen in der Datenbank, die der KI-Datenagent verwenden soll, z. B. "loan", "client", "disp".
• billing_project: die ID des Abrechnungsprojekts, in dem Sie die erforderlichen APIs aktiviert haben.
• location: der Speicherort, an dem sich Ihr Kontextset befindet, z. B. global.
• your_context_set_id: Wenn Sie erweiterten Kontext für den Agenten erstellt haben, die ID Ihres Kontextsets.

Daten-Agenten erstellen

Im folgenden Beispielcode wird gezeigt, wie Sie den KI-Datenagenten synchron oder asynchron über eine HTTP-POST-Anfrage an den Endpunkt für die Erstellung von KI-Datenagenten erstellen. Die Anfragenutzlast enthält die folgenden Details:

• Der vollständige Ressourcenname des KI-Agenten. Dieser Wert enthält die Projekt-ID, den Standort und eine eindeutige Kennung für den KI-Agenten.
• Die Beschreibung des Daten-Agenten.
• Der Kontext des KI-Datenagenten, einschließlich der Systembeschreibung (definiert in Erste Einstellungen und Authentifizierung konfigurieren) und der Datenquelle, die der KI-Agent verwendet (definiert in Mit einer Datenquelle verbinden).

Sie können den KI-Datenagenten optional mit kundenverwalteten Verschlüsselungsschlüsseln (CMEK) schützen, indem Sie das Feld kms_key in die Anfragenutzlast einfügen, wenn Sie den KI-Datenagenten erstellen. Weitere Informationen finden Sie unter Kundenverwaltete Verschlüsselungsschlüssel (CMEK).

Optional können Sie auch die erweiterte Analyse mit Python aktivieren, indem Sie den Parameter options in die Anfragenutzlast einfügen. Weitere Informationen zum Parameter options und den Optionen, die Sie für die Unterhaltung konfigurieren können, finden Sie unter REST-Ressource: projects.locations.dataAgents.

Warnung: Der von KI-Datenagenten zurückgegebene Python-Code ist für die Ausführung in einer sicheren, von Google verwalteten Sandbox konzipiert. Wenn Sie diesen Code in einer lokalen oder anderen nicht verifizierten Umgebung ausführen, werden die Sicherheitsmaßnahmen der Sandbox umgangen. Dadurch kann Ihr System Sicherheitsrisiken ausgesetzt sein, z. B. der Ausführung von schädlichem Code. Eine Anleitung zum sicheren Prüfen und Verarbeiten von KI-Agenten generiertem Python-Code finden Sie unter Wie kann ich von KI-Agenten generierten Python-Code sicher prüfen und verarbeiten?.

Im folgenden Beispiel wird die Variable bigquery_data_sources verwendet, die im Abschnitt Verbindung zu BigQuery herstellen erstellt wurde, um den KI-Datenagenten für eine Verbindung zu einer BigQuery-Tabelle zu konfigurieren.

Wenn Sie stattdessen Looker-Daten verwenden möchten, ersetzen Sie bigquery_data_sources durch looker_data_source.

Wenn Sie stattdessen Data Studio-Daten verwenden möchten, ersetzen Sie bigquery_data_sources durch looker_studio_data_source.

Wenn Sie stattdessen AlloyDB-Daten verwenden möchten, ersetzen Sie bigquery_data_sources durch alloydb_data_source.

Wenn Sie stattdessen Cloud SQL-Daten verwenden möchten, ersetzen Sie bigquery_data_sources durch sql_data_source.

Wenn Sie stattdessen Spanner-Daten verwenden möchten, ersetzen Sie bigquery_data_sources durch spanner_data_sources.

Synchron

data_agent_url = f"https://geminidataanalytics.googleapis.com/v1beta/projects/{billing_project}/locations/{location}/dataAgents:createSync"

data_agent_id = "DATA_AGENT_ID"

# Optional: If using CMEK, replace the empty strings with your KMS key details.
kms_project_id = ""  # KMS_PROJECT_ID (Defaults to billing_project if empty)
key_ring_name = ""   # KEY_RING_NAME
key_name = ""        # KEY_NAME
key_location = ""    # KEY_LOCATION (Defaults to location if empty; except eu)

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}", # Optional
      "description": "This is the description of the data agent.", # Optional
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": bigquery_data_sources,
              "system_instruction": system_instruction,
              "options": {
                  # Optional: To enable advanced analysis with Python
                  "analysis": {
                      "python": {
                          "enabled": True
                      }
                  },
                  # Optional: To limit query costs to 100MiB
                  "datasource": {
                      "bigQueryMaxBilledBytes": "104857600"
                  }
              }
          }
      }
  }

# If key details are provided, construct and add the kms_key field.
if key_ring_name and key_name:
  if not kms_project_id:
    kms_project_id = billing_project
  if not key_location:
    key_location = location
  data_agent_payload["kms_key"] = f"projects/{kms_project_id}/locations/{key_location}/keyRings/{key_ring_name}/cryptoKeys/{key_name}"

params = {"data_agent_id": data_agent_id} # Optional

data_agent_response = requests.post(
    data_agent_url, params=params, json=data_agent_payload, headers=headers
)

if data_agent_response.status_code == 200:
    print("Data Agent created successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error creating Data Agent: {data_agent_response.status_code}")
    print(data_agent_response.text)

Asynchron

data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents"

data_agent_id = "DATA_AGENT_ID"

# Optional: If using CMEK, replace the empty strings with your KMS key details.
kms_project_id = ""  # KMS_PROJECT_ID (Defaults to billing_project if empty)
key_ring_name = ""   # KEY_RING_NAME
key_name = ""        # KEY_NAME
key_location = ""    # KEY_LOCATION (Defaults to location if empty; except eu)

data_agent_payload = {
      "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}", # Optional
      "description": "This is the description of the data agent.", # Optional
      "data_analytics_agent": {
          "published_context": {
              "datasource_references": bigquery_data_sources,
              "system_instruction": system_instruction,
              "options": {
                  # Optional: To enable advanced analysis with Python
                  "analysis": {
                      "python": {
                          "enabled": True
                      }
                  },
                  # Optional: To limit query costs to 100MiB
                  "datasource": {
                      "bigQueryMaxBilledBytes": "104857600"
                  }
              }
          }
      }
  }

# If key details are provided, construct and add the kms_key field.
if key_ring_name and key_name:
  if not kms_project_id:
    kms_project_id = billing_project
  if not key_location:
    key_location = location
  data_agent_payload["kms_key"] = f"projects/{kms_project_id}/locations/{key_location}/keyRings/{key_ring_name}/cryptoKeys/{key_name}"

params = {"data_agent_id": data_agent_id} # Optional

data_agent_response = requests.post(
    data_agent_url, params=params, json=data_agent_payload, headers=headers
)

if data_agent_response.status_code == 200:
    print("Data Agent created successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error creating Data Agent: {data_agent_response.status_code}")
    print(data_agent_response.text)

Ersetzen Sie die Beispielwerte so:

• DATA_AGENT_ID: eine eindeutige Kennung für den KI-Datenagenten. Dieser Wert wird im Ressourcennamen des KI-Agenten und als URL-Abfrageparameter data_agent_id verwendet.
• KMS_PROJECT_ID: Wenn Sie CMEK verwenden, die Projekt-ID, in der der Schlüssel gehostet wird. Wenn nicht angegeben, wird standardmäßig Ihr Abrechnungsprojekt verwendet.
• KEY_RING_NAME: Wenn Sie CMEK verwenden, der Name Ihres Cloud KMS-Schlüsselbunds.
• KEY_NAME: Wenn Sie CMEK verwenden, der Name Ihres Cloud KMS-Schlüssels.
• KEY_LOCATION: Wenn Sie CMEK verwenden, der Speicherort Ihres Schlüsselbunds. Verwenden Sie für den multiregionalen Standort eu den Wert europe. Verwenden Sie für alle anderen Standorte denselben Standort wie für den KI-Datenagenten. Wenn nicht angegeben, wird standardmäßig der Standort des KI-Datenagenten verwendet. Das funktioniert für alle Standorte außer dem multiregionalen Standort eu. Weitere Informationen finden Sie unter Standortanforderungen.
• This is the description of the data agent.: Eine Beschreibung des Daten-Agenten.

Unterhaltung erstellen

Im folgenden Beispielcode wird gezeigt, wie Sie eine Unterhaltung mit Ihrem Daten-Agenten erstellen.

Optional können Sie die Unterhaltung mit CMEK schützen, indem Sie beim Erstellen der Unterhaltung das Feld kms_key in die Nutzlast der Anfrage einfügen. Weitere Informationen finden Sie unter Kundenverwaltete Verschlüsselungsschlüssel (CMEK).

conversation_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/conversations"

data_agent_id = "DATA_AGENT_ID"
conversation_id = "CONVERSATION_ID"

# Optional: If using CMEK, replace the empty strings with your KMS key details.
kms_project_id = ""  # KMS_PROJECT_ID (Defaults to billing_project if empty)
key_ring_name = ""   # KEY_RING_NAME
key_name = ""        # KEY_NAME
key_location = ""    # KEY_LOCATION (Defaults to location if empty; single regions only)

conversation_payload = {
    "agents": [
        f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
    ],
    "name": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
}

# If key details are provided, construct and add the kms_key field.
if key_ring_name and key_name:
  if not kms_project_id:
    kms_project_id = billing_project
  if not key_location:
    key_location = location
  conversation_payload["kms_key"] = f"projects/{kms_project_id}/locations/{key_location}/keyRings/{key_ring_name}/cryptoKeys/{key_name}"

params = {
    "conversation_id": conversation_id
}

conversation_response = requests.post(conversation_url, headers=headers, params=params, json=conversation_payload)

if conversation_response.status_code == 200:
    print("Conversation created successfully!")
    print(json.dumps(conversation_response.json(), indent=2))
else:
    print(f"Error creating Conversation: {conversation_response.status_code}")
    print(conversation_response.text)

Ersetzen Sie die Beispielwerte so:

• DATA_AGENT_ID: die ID des Daten-Agenten, wie im Beispielcodeblock unter Daten-Agenten erstellen definiert.
• CONVERSATION_ID: eine eindeutige Kennung für die Unterhaltung.
• KMS_PROJECT_ID: Wenn Sie CMEK verwenden, die Projekt-ID, in der der Schlüssel gehostet wird. Wenn nicht angegeben, wird standardmäßig Ihr Abrechnungsprojekt verwendet.
• KEY_RING_NAME: Wenn Sie CMEK verwenden, der Name Ihres Cloud KMS-Schlüsselbunds.
• KEY_NAME: Wenn Sie CMEK verwenden, der Name Ihres Cloud KMS-Schlüssels.
• KEY_LOCATION: Wenn Sie CMEK verwenden, der Speicherort Ihres Schlüsselbunds. Verwenden Sie für den multiregionalen Standort us den Wert us-central1. Verwenden Sie für den multiregionalen Standort eu den Wert europe-west1. Verwenden Sie für eine einzelne Region dieselbe Region wie für die Unterhaltung. Wenn nichts angegeben ist, wird standardmäßig der Standort der Unterhaltung verwendet. Dies funktioniert nur für einzelne Regionen. Weitere Informationen finden Sie unter Standortanforderungen.

Daten-Agenten und Unterhaltungen verwalten

Die folgenden Codebeispiele zeigen, wie Sie Ihre Daten-Agents und Unterhaltungen mit der Conversational Analytics API verwalten. Sie können folgende Aufgaben ausführen:

• Daten-Agenten abrufen
• KI-Datenagenten auflisten
• Verfügbare Daten-Agenten auflisten
• Daten-Agenten aktualisieren
• IAM-Richtlinie für einen Daten-Agenten abrufen
• IAM-Richtlinie für einen Daten-Agenten festlegen
• Daten-Agenten löschen
• Unterhaltung abrufen
• Unterhaltungen auflisten
• Nachrichten in einer Unterhaltung auflisten

Daten-Agenten abrufen

Im folgenden Beispielcode wird gezeigt, wie Sie einen vorhandenen KI-Datenagenten über eine HTTP-GET-Anfrage an die Ressourcen-URL des KI-Datenagenten abrufen.

data_agent_id = "DATA_AGENT_ID"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"

data_agent_response = requests.get(
    data_agent_url, headers=headers
)

if data_agent_response.status_code == 200:
    print("Fetched Data Agent successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error: {data_agent_response.status_code}")
    print(data_agent_response.text)

Ersetzen Sie im vorherigen Beispiel DATA_AGENT_ID durch die ID des KI-Datenagenten, den Sie abrufen möchten.

Daten-Agenten auflisten

Im folgenden Beispielcode wird gezeigt, wie Sie alle KI-Datenagenten für ein bestimmtes Projekt über eine HTTP-GET-Anfrage an den dataAgents-Endpunkt auflisten.

Zum Auflisten aller KI-Agenten benötigen Sie die Berechtigung geminidataanalytics.dataAgents.list für das Projekt. Weitere Informationen dazu, welche IAM-Rollen diese Berechtigung enthalten, finden Sie in der Liste der vordefinierten Rollen.

billing_project = "BILLING_PROJECT"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents"

data_agent_response = requests.get(
    data_agent_url, headers=headers
)

if data_agent_response.status_code == 200:
    print("Data Agents Listed successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error Listing Data Agents: {data_agent_response.status_code}")

Ersetzen Sie BILLING_PROJECT durch die ID Ihres Abrechnungsprojekts.

Verfügbare Daten-KI-Agenten auflisten

Im folgenden Beispielcode wird gezeigt, wie Sie alle zugänglichen KI-Datenagenten für ein bestimmtes Projekt über eine HTTP-GET-Anfrage an den dataAgents:listAccessible-Endpunkt auflisten.

billing_project = "BILLING_PROJECT"
creator_filter = "CREATOR_FILTER"
data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents:listAccessible"

params = {
    "creator_filter": creator_filter
}

data_agent_response = requests.get(
    data_agent_url, headers=headers, params=params
)

if data_agent_response.status_code == 200:
    print("Accessible Data Agents Listed successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error Listing Accessible Data Agents: {data_agent_response.status_code}")

Ersetzen Sie die Beispielwerte folgendermaßen:

• BILLING_PROJECT: die ID Ihres Abrechnungsprojekts.
• CREATOR_FILTER: der Filter, der basierend auf dem Ersteller des KI-Datenagenten angewendet werden soll. Mögliche Werte sind NONE (Standard), CREATOR_ONLY und NOT_CREATOR_ONLY.

KI-Datenagenten aktualisieren

Im folgenden Beispielcode wird gezeigt, wie Sie einen KI-Datenagenten synchron oder asynchron über eine HTTP-PATCH-Anfrage an die Ressourcen-URL des KI-Datenagenten aktualisieren. Die Anfragenutzlast enthält die neuen Werte für die Felder, die Sie ändern möchten. Die Anfrageparameter enthalten den Parameter updateMask, mit dem die zu aktualisierenden Felder angegeben werden.

Synchron

data_agent_id = "DATA_AGENT_ID"
billing_project = "BILLING_PROJECT"

data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:updateSync"

payload = {
    "description": "Updated description of the data agent.",
    "data_analytics_agent": {
        "published_context": {
            "datasource_references": bigquery_data_sources,
            "system_instruction": system_instruction
        }
    },
}

fields = ["description", "data_analytics_agent"]
params = {
    "updateMask": ",".join(fields)
}

data_agent_response = requests.patch(
    data_agent_url, headers=headers, params=params, json=payload
)

if data_agent_response.status_code == 200:
    print("Data Agent updated successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error Updating Data Agent: {data_agent_response.status_code}")
    print(data_agent_response.text)

Asynchron

data_agent_id = "DATA_AGENT_ID"
billing_project = "BILLING_PROJECT"

data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"

payload = {
    "description": "Updated description of the data agent.",
    "data_analytics_agent": {
        "published_context": {
            "datasource_references": bigquery_data_sources,
            "system_instruction": system_instruction
        }
    },
}

fields = ["description", "data_analytics_agent"]
params = {
    "updateMask": ",".join(fields)
}

data_agent_response = requests.patch(
    data_agent_url, headers=headers, params=params, json=payload
)

if data_agent_response.status_code == 200:
    print("Data Agent updated successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error Updating Data Agent: {data_agent_response.status_code}")
    print(data_agent_response.text)

Ersetzen Sie die Beispielwerte so:

• DATA_AGENT_ID: die ID des Daten-Agenten, den Sie aktualisieren möchten.
• BILLING_PROJECT: die ID Ihres Abrechnungsprojekts.
• Updated description of the data agent.: Eine neue Beschreibung des Daten-Agenten.

IAM-Richtlinie für einen Daten-Agenten abrufen

Im folgenden Beispielcode wird gezeigt, wie Sie die IAM-Richtlinie für einen KI-Datenagenten über eine HTTP-POST-Anfrage an die URL des KI-Datenagenten abrufen. Die Anfragenutzlast enthält den Pfad zum KI-Datenagenten.

billing_project = "BILLING_PROJECT"
data_agent_id = "DATA_AGENT_ID"

data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:getIamPolicy"

# Request body
payload = {
    "resource": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"
}

data_agent_response = requests.post(
    data_agent_url, headers=headers, json=payload
)

if data_agent_response.status_code == 200:
    print("IAM Policy fetched successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error fetching IAM policy: {data_agent_response.status_code}")
    print(data_agent_response.text)

Ersetzen Sie die Beispielwerte folgendermaßen:

• BILLING_PROJECT: die ID Ihres Abrechnungsprojekts.
• DATA_AGENT_ID: die ID des KI-Datenagenten, für den Sie die IAM-Richtlinie abrufen möchten.

IAM-Richtlinie für einen Daten-Agent festlegen

Wenn Sie einen KI-Agenten freigeben möchten, können Sie mit der Methode setIamPolicy Nutzern IAM-Rollen für einen bestimmten KI-Agenten zuweisen. Im folgenden Beispielcode wird gezeigt, wie Sie einen POST-Aufruf an die URL des KI-Datenagenten mit einer Nutzlast durchführen, die Bindungen enthält. Die Bindung gibt an, welche Rollen welchen Nutzern zugewiesen werden sollen.

Wichtig: Mit diesem setIamPolicy API-Aufruf werden vorhandene Berechtigungen für die Ressource überschrieben. Wenn Sie vorhandene Richtlinien beibehalten möchten, rufen Sie die Get IAM policy API auf, um die vorhandene Richtlinie abzurufen. Übergeben Sie sie dann zusammen mit allen weiteren Änderungen im Aufruf an SetIamPolicy.

billing_project = "BILLING_PROJECT"
data_agent_id = "DATA_AGENT_ID"
role = "roles/geminidataanalytics.dataAgentEditor"
users = "[e-mail], [e-mail]"

data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:setIamPolicy"

# Request body
payload = {
    "policy": {
        "bindings": [
            {
                "role": role,
                "members": [
                    f"user:{i.strip()}" for i in users.split(",")
                ]
            }
        ]
    }
}

data_agent_response = requests.post(
    data_agent_url, headers=headers, json=payload
)

if data_agent_response.status_code == 200:
    print("IAM Policy set successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error setting IAM policy: {data_agent_response.status_code}")
    print(data_agent_response.text)

Ersetzen Sie die Beispielwerte folgendermaßen:

• BILLING_PROJECT: die ID Ihres Abrechnungsprojekts.
• DATA_AGENT_ID: die ID des KI-Datenagenten, für den Sie die IAM-Richtlinie festlegen möchten.
• [e-mail], [e-mail]: eine kommagetrennte Liste von Nutzer-E-Mail-Adressen, denen Sie die angegebene Rolle zuweisen möchten.

Daten-Agenten löschen

Im folgenden Beispielcode wird gezeigt, wie Sie einen KI-Datenagenten synchron oder asynchron löschen, indem Sie eine HTTP-DELETE-Anfrage an die Ressourcen-URL des KI-Datenagenten senden. Wenn Sie einen KI-Daten-Agenten löschen, wird er für 30 Tage vorläufig gelöscht und kann nicht wiederhergestellt werden. Weitere Informationen finden Sie unter Datenaufbewahrung und -löschung.

Synchron

billing_project = "BILLING_PROJECT"
data_agent_id = "DATA_AGENT_ID"

data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}:deleteSync"

data_agent_response = requests.delete(
    data_agent_url, headers=headers
)

if data_agent_response.status_code == 200:
    print("Data Agent deleted successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error Deleting Data Agent: {data_agent_response.status_code}")
    print(data_agent_response.text)

Asynchron

billing_project = "BILLING_PROJECT"
data_agent_id = "DATA_AGENT_ID"

data_agent_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"

data_agent_response = requests.delete(
    data_agent_url, headers=headers
)

if data_agent_response.status_code == 200:
    print("Data Agent deleted successfully!")
    print(json.dumps(data_agent_response.json(), indent=2))
else:
    print(f"Error Deleting Data Agent: {data_agent_response.status_code}")
    print(data_agent_response.text)

Ersetzen Sie die Beispielwerte so:

• BILLING_PROJECT: die ID Ihres Abrechnungsprojekts.
• DATA_AGENT_ID: die ID des KI-Datenagenten, den Sie löschen möchten.

Unterhaltung abrufen

Im folgenden Beispielcode wird gezeigt, wie Sie eine vorhandene Unterhaltung über eine HTTP-GET-Anfrage an die Ressourcen-URL der Unterhaltung abrufen.

billing_project = "BILLING_PROJECT"
conversation_id = "CONVERSATION_ID"

conversation_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/conversations/{conversation_id}"

conversation_response = requests.get(conversation_url, headers=headers)

# Handle the response
if conversation_response.status_code == 200:
    print("Conversation fetched successfully!")
    print(json.dumps(conversation_response.json(), indent=2))
else:
    print(f"Error while fetching conversation: {conversation_response.status_code}")
    print(conversation_response.text)

Ersetzen Sie die Beispielwerte folgendermaßen:

• BILLING_PROJECT: die ID Ihres Abrechnungsprojekts.
• CONVERSATION_ID: die ID der Unterhaltung, die Sie abrufen möchten.

Unterhaltungen auflisten

Im folgenden Beispielcode wird gezeigt, wie Sie Unterhaltungen für ein bestimmtes Projekt über eine HTTP-GET-Anfrage an den conversations-Endpunkt auflisten.

Mit dieser Methode werden standardmäßig die Unterhaltungen zurückgegeben, die Sie erstellt haben. Administratoren (Nutzer mit der IAM-Rolle cloudaicompanion.topicAdmin) können alle Unterhaltungen im Projekt sehen.

billing_project = "BILLING_PROJECT"
conversation_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/conversations"

conversation_response = requests.get(conversation_url, headers=headers)

# Handle the response
if conversation_response.status_code == 200:
    print("Conversation fetched successfully!")
    print(json.dumps(conversation_response.json(), indent=2))
else:
    print(f"Error while fetching conversation: {conversation_response.status_code}")
    print(conversation_response.text)

Ersetzen Sie BILLING_PROJECT durch die ID des Abrechnungsprojekts, in dem Sie die erforderlichen APIs aktiviert haben.

Nachrichten in einer Unterhaltung auflisten

Der folgende Beispielcode zeigt, wie Sie alle Nachrichten in einer Unterhaltung über eine HTTP-GET-Anfrage an den messages-Endpunkt der Unterhaltung auflisten.

Zum Auflisten von Nachrichten benötigen Sie die Berechtigung cloudaicompanion.topics.get für die Unterhaltung.

Hinweis: Dieser Auflistungsvorgang unterstützt auch die Paginierung.

billing_project = "BILLING_PROJECT"

conversation_id = "CONVERSATION_ID"

conversation_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/conversations/{conversation_id}/messages"

conversation_response = requests.get(conversation_url, headers=headers)

# Handle the response
if conversation_response.status_code == 200:
    print("Conversation fetched successfully!")
    print(json.dumps(conversation_response.json(), indent=2))
else:
    print(f"Error while fetching conversation: {conversation_response.status_code}")
    print(conversation_response.text)

Ersetzen Sie die Beispielwerte folgendermaßen:

• BILLING_PROJECT: die ID Ihres Abrechnungsprojekts.
• CONVERSATION_ID: die ID der Unterhaltung, für die Sie Nachrichten auflisten möchten.

Unterhaltungen löschen

Im folgenden Beispielcode wird gezeigt, wie Sie eine Unterhaltung über eine HTTP-DELETE-Anfrage an die Ressourcen-URL der Unterhaltung löschen. Administratoren (Nutzer mit der Identity and Access Management-Rolle „cloudaicompanion.topicAdmin“) oder Nutzer mit der Identity and Access Management-Berechtigung cloudaicompanion.topics.delete können Unterhaltungen im Projekt löschen.

billing_project = "BILLING_PROJECT"
conversation_id = "CONVERSATION_ID"

conversation_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/conversations/{conversation_id}"

conversation_response = requests.delete(conversation_url, headers=headers)

# Handle the response
if conversation_response.status_code == 200:
    print("Conversation deleted successfully!")
    print(json.dumps(conversation_response.json(), indent=2))
else:
    print(f"Error while deleting conversation: {conversation_response.status_code}")
    print(conversation_response.text)

Ersetzen Sie die Beispielwerte so:

• BILLING_PROJECT: die ID Ihres Abrechnungsprojekts.
• CONVERSATION_ID: die ID der Unterhaltung, die Sie löschen möchten.

API zum Stellen von Fragen verwenden

Nachdem Sie einen KI-Datenagenten und für zustandsorientierte Chats eine Unterhaltung erstellt haben, können Sie Anfragen an den KI-Agenten senden.

Wenn Sie eine Abfrage senden, gibt die API einen Stream von Message-Objekten zurück. Dieser Stream kann verschiedene Arten von Nachrichten enthalten, darunter Text, Datentabellen und Diagramme. Textnachrichten können Einblick in die Schlussfolgerungen des KI-Agenten geben, über seinen Fortschritt berichten oder die endgültige Antwort liefern. Der Zweck jeder Nachricht wird durch den Wert TextType angegeben:

• THOUGHT: Zeigt den internen Denkprozess des KI-Agenten, während er plant, wie er Ihre Anfrage beantworten soll. THOUGHT-Nachrichten bieten einen schrittweisen Einblick in den Denk- und Entscheidungsprozess des KI-Agenten und bestehen aus zwei Teilen: parts[0] ist die Zusammenfassung des Gedankens, die den vollständigen Gedankentext kurz zusammenfasst, und parts[1] ist der vollständige Gedankentext.
• PROGRESS: Meldet den Fortschritt des KI-Agenten bei einer Aktion, z. B. beim Datenabruf oder beim Aufrufen eines Tools. Dieser Wert wird nur für Looker-Datenquellen zurückgegeben und besteht aus zwei Teilen: parts[0] ist die Zusammenfassung und parts[1] ist der vollständige Fortschrittstext.
• FINAL_RESPONSE: Liefert die endgültige Antwort auf Ihre Anfrage.

In den Beispielen im folgenden Abschnitt werden die Hilfsfunktionen verwendet, die unter Hilfsfunktionen in Python zum Streamen von Chatantworten definiert sind, um jede Nachricht in der gestreamten Antwort der API zu verarbeiten und anzuzeigen. Informationen zum Rendern dieser Nachrichten in einer Benutzeroberfläche, wenn Sie Looker-Datenquellen verwenden, finden Sie unter Antworten von KI-Agenten für Looker-Datenquellen rendern.

Fragen mit zustandsorientiertem und zustandslosem Chat stellen

Sie können mit der API in den folgenden primären Modi interagieren:

• Zustandsorientierter Chat: Der Unterhaltungsverlauf wird von Google Cloud gespeichert und verwaltet. Der zustandsorientierte Chat ist grundsätzlich ein Multi-Turn-Chat, da die API den Kontext aus vorangegangenen Nachrichten beibehält. Sie müssen nur Ihre aktuelle Nachricht senden, um die Unterhaltung am Laufen zu halten.
• Zustandsloser Chat: Der Unterhaltungsverlauf wird von Ihrer Anwendung verwaltet. Sie müssen in jede neue Nachricht die relevanten vorherigen Nachrichten einfügen. Ausführliche Beispiele zum Verwalten von Unterhaltungen mit mehreren Runden im zustandslosen Modus finden Sie unter Zustandslose Multi-Turn-Unterhaltung erstellen.

In den folgenden Beispielen wird gezeigt, wie Sie die API für zustandsorientierte und zustandslose Chats verwenden, indem Sie eine POST-Anfrage an den :chat-Endpunkt senden.

Achtung: In den Codebeispielen in diesem Abschnitt wird die Python-Standardbibliothek requests verwendet, um HTTP-Streaming zu demonstrieren. Standard-HTTP- oder REST-Clients können HTTP/2-Trailer nicht lesen. Wenn während des Streamings ein schwerwiegender Fehler auftritt (z. B. eine Zeitüberschreitung), gibt die API möglicherweise eine allgemeine Fehlermeldung wie 503 Connection reset by peer oder 500 Internal Server Error zurück. Für Produktionsanwendungen empfehlen wir dringend, das Python SDK zu verwenden, das gRPC verwendet, um diese nachgestellten Fehler korrekt zu parsen.

Zustandsorientierter Chat

Zustandsorientierte Chatanfrage mit einem Unterhaltungsverweis senden

Im folgenden Beispielcode wird gezeigt, wie Sie der API Fragen unter Verwendung der Unterhaltung stellen, die Sie in den vorherigen Schritten definiert haben. In diesem Beispiel wird die get_stream-Hilfsfunktion verwendet, um die Antwort zu streamen.

Hinweis: Wenn Ihr KI-Agent eine Looker-Datenquelle verwendet, müssen Sie die Kommentarzeichen aus der Zeile "credentials": looker_credentials entfernen.

chat_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}:chat"

data_agent_id = "DATA_AGENT_ID"
conversation_id = "CONVERSATION_ID"

# Construct the payload
chat_payload = {
    "parent": f"projects/{billing_project}/locations/{location}",
    # "credentials": looker_credentials,
    "messages": [
        {
            "userMessage": {
                "text": "Make a bar graph for the top 5 states by the total number of airports"
            }
        }
    ],
    "conversation_reference": {
        "conversation": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
        "data_agent_context": {
            "data_agent": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
        }
    }
}

# Call the get_stream function to stream the response
get_stream(chat_url, chat_payload)

Ersetzen Sie die Beispielwerte folgendermaßen:

• DATA_AGENT_ID: die ID des Daten-Agenten, wie im Beispielcodeblock unter Daten-Agenten erstellen definiert.
• CONVERSATION_ID: eine eindeutige Kennung für die Unterhaltung.
• Als Beispiel-Prompt wurde Make a bar graph for the top 5 states by the total number of airports verwendet.

Zustandsloser Chat

In den folgenden Beispielen wird gezeigt, wie Sie zustandslose Anfragen entweder mit einer Referenz auf einen KI-Datenagenten oder mit Inline-Kontext senden.

Zustandslose Chatanfrage mit einem KI-Datenagentenverweis senden

Im folgenden Beispielcode wird gezeigt, wie Sie der API eine zustandslose Frage stellen. Dazu verwenden Sie den KI-Datenagenten, den Sie in den vorherigen Schritten definiert haben. In diesem Beispiel wird die get_stream-Hilfsfunktion verwendet, um die Antwort zu streamen.

Hinweis: Wenn Ihr KI-Agent eine Looker-Datenquelle verwendet, müssen Sie die Kommentarzeichen aus der Zeile "credentials": looker_credentials entfernen.

chat_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}:chat"

data_agent_id = "DATA_AGENT_ID"

# Construct the payload
chat_payload = {
    "parent": f"projects/{billing_project}/locations/{location}",
    # "credentials": looker_credentials,
    "messages": [
        {
            "userMessage": {
                "text": "Make a bar graph for the top 5 states by the total number of airports"
            }
        }
    ],
    "data_agent_context": {
        "data_agent": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
    }
}

# Call the get_stream function to stream the response
get_stream(chat_url, chat_payload)

Ersetzen Sie die Beispielwerte folgendermaßen:

• DATA_AGENT_ID: die ID des Daten-Agenten, wie im Beispielcodeblock unter Daten-Agenten erstellen definiert.
• Als Beispiel-Prompt wurde Make a bar graph for the top 5 states by the total number of airports verwendet.

Zustandslose Chatanfrage mit Inline-Kontext senden

Im folgenden Beispielcode wird gezeigt, wie Sie der API eine zustandslose Frage mit Inline-Kontext stellen. In diesem Beispiel wird die get_stream-Hilfsfunktion verwendet, um die Antwort zu streamen. Als Beispiel dient eine BigQuery-Datenquelle.

Hinweis: Wenn Ihr KI-Agent eine Looker-Datenquelle verwendet, müssen Sie die Kommentarzeichen aus der Zeile "credentials": looker_credentials in den folgenden Codebeispielen entfernen.

Optional können Sie auch die erweiterte Analyse mit Python aktivieren, indem Sie den Parameter options in die Anfragenutzlast einfügen. Weitere Informationen zum Parameter options und den Optionen, die Sie für die Unterhaltung konfigurieren können, finden Sie auf der Seite REST-Ressource: projects.locations.dataAgents.

Warnung: Der von KI-Datenagenten zurückgegebene Python-Code ist für die Ausführung in einer sicheren, von Google verwalteten Sandbox konzipiert. Wenn Sie diesen Code in einer lokalen oder anderen nicht verifizierten Umgebung ausführen, werden die Sicherheitsmaßnahmen der Sandbox umgangen. Dadurch kann Ihr System Sicherheitsrisiken ausgesetzt sein, z. B. der Ausführung von schädlichem Code. Eine Anleitung zum sicheren Prüfen und Verarbeiten von KI-Agenten generiertem Python-Code finden Sie unter Wie kann ich von KI-Agenten generierten Python-Code sicher prüfen und verarbeiten?.

chat_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}:chat"

# Construct the payload
chat_payload = {
    "parent": f"projects/{billing_project}/locations/{location}",
    # "credentials": looker_credentials,
    "messages": [
        {
            "userMessage": {
                "text": "Make a bar graph for the top 5 states by the total number of airports"
            }
        }
    ],
    "inline_context": {
        "datasource_references": bigquery_data_sources,
          # Optional: To enable advanced analysis with Python, include the following options block:
          "options": {
              "analysis": {
                  "python": {
                      "enabled": True
                  }
              }
          }
    }
}

# Call the get_stream function to stream the response
get_stream(chat_url, chat_payload)

Im folgenden Beispielcode wird gezeigt, wie Sie der API eine zustandslose Frage mit Inline-Kontext und einer AlloyDB-Datenquelle als Beispiel stellen.

chat_url = f"https://geminidataanalytics.googleapis.com/v1/projects/{billing_project}/locations/{location}:chat"

# The natural language question to ask the data agent
user_prompt = "What is the average loan amount in the US?"  # Replace with your question

# Construct the payload
chat_payload = {
    "parent": f"projects/{billing_project}/locations/{location}",
    # "credentials": looker_credentials,
    "messages": [
        {
            "userMessage": {
                "text": user_prompt
            }
        }
    ],
    "data_agent_context": {
          "data_agent": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
    }
}

print(f"Sending prompt to :chat: '{user_prompt}'")
print(f"Endpoint: {chat_url}")
print(f"Payload: {json.dumps(chat_payload, indent=2)}")

get_stream(chat_url, chat_payload)

Zustandslose Multi-Turn-Unterhaltung erstellen

Wenn Sie in einer zustandslosen Unterhaltung weiterführende Fragen stellen möchten, muss Ihre Anwendung den Kontext der Unterhaltung verwalten. Hierfür wird mit jeder neuen Anfrage der gesamte Nachrichtenverlauf gesendet. Bei Unterhaltungen mit mehreren Runden können Sie weiterführende Fragen stellen, die auf vorherigen Antworten aufbauen.

Im folgenden Beispiel wird eine multi_turn_conversation-Funktion definiert und aufgerufen, um den Unterhaltungskontext zu verwalten, indem Nachrichten in einer Liste gespeichert werden. Die Funktion multi_turn_conversation ruft die Funktion get_stream_multi_turn auf, um die gestreamte API-Antwort zu parsen und die Liste conversation_messages zu aktualisieren. Bei diesem Prozess wird der Kontext für nachfolgende Turns beibehalten. Den Code für get_stream_multi_turn und andere erforderliche Hilfsfunktionen finden Sie unter Hilfsfunktionen für Streaming-Chats.

Im folgenden Codebeispiel wird auf einen Daten-Agenten verwiesen. Wenn Sie stattdessen Inline-Kontext verwenden möchten, entfernen Sie die Kommentarzeichen aus dem Block inline_context und kommentieren Sie den Block data_agent_context aus. Im Beispiel mit Inline-Kontext wird eine BigQuery-Datenquelle verwendet.

Wenn Ihr KI-Agent eine Looker-Datenquelle verwendet, müssen Sie die Kommentarzeichen aus der Zeile "credentials": looker_credentials entfernen.

chat_url = f"{base_url}/v1/projects/{billing_project}/locations/{location}:chat"

# List that is used to track previous turns and is reused across requests
conversation_messages = []

data_agent_id = "DATA_AGENT_ID"

# Helper function for calling the API
def multi_turn_conversation(msg):

  userMessage = {
      "userMessage": {
          "text": msg
      }
  }

  # Send a multi-turn request by including previous turns and the new message
  conversation_messages.append(userMessage)

  # Construct the payload
  chat_payload = {
      "parent": f"projects/{billing_project}/locations/{location}",
      # "credentials": looker_credentials,
      "messages": conversation_messages,
      # Use a data agent reference
      "data_agent_context": {
          "data_agent": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
      },
      # Use inline context
      # "inline_context": {
      #     "datasource_references": bigquery_data_sources,
      # }
  }

  # Call the get_stream_multi_turn helper function to stream the response
  get_stream_multi_turn(chat_url, chat_payload, conversation_messages)

Ersetzen Sie im vorherigen Beispiel DATA_AGENT_ID durch die ID des Daten-Agenten, wie im Beispielcodeblock unter Daten-Agenten erstellen definiert.

Sie können für jede Runde der Unterhaltung die multi_turn_conversation-Hilfsfunktion aufrufen. Im folgenden Beispielcode wird gezeigt, wie Sie eine erste Anfrage und dann eine weiterführende Anfrage senden, die auf der vorherigen Antwort aufbaut:

# Send first-turn request
multi_turn_conversation("Which species of tree is most prevalent?")

# Send follow-up-turn request
multi_turn_conversation("Can you show me the results as a bar chart?")

Ersetzen Sie im vorherigen Beispiel die Beispielwerte folgendermaßen:

• Which species of tree is most prevalent?: eine Frage in natürlicher Sprache, die an den KI-Datenagenten gesendet werden soll.
• Can you show me the results as a bar chart?: eine weiterführende Frage, die auf der vorangegangenen Frage aufbaut oder sie verfeinert.

Hilfsfunktionen definieren

Der folgende Abschnitt enthält Definitionen von Hilfsfunktionen, die in den vorherigen Codebeispielen verwendet werden, um Antworten der API zu parsen und die Ergebnisse anzuzeigen.

Hilfsfunktionen für das Streamen von Chats

Die folgenden Funktionen parsen und zeigen die gestreamte Antwort der API für Standard-Chatanfragen (Single-Turn) an.

Hilfsfunktionen zum Streamen von Chatantworten anzeigen

    def is_json(str):
      try:
          json_object = json_lib.loads(str)
      except ValueError as e:
          return False
      return True

    def handle_text_response(resp):
      parts = resp['parts']
      full_text = "".join(parts)
      if "\n" not in full_text and len(full_text) > 80:
        wrapped_text = textwrap.fill(full_text, width=80)
        print(wrapped_text)
      else:
        print(full_text)

    def get_property(data, field_name, default = ''):
      return data[field_name] if field_name in data else default

    def display_schema(data):
      fields = data['fields']
      df = pd.DataFrame({
        "Column": map(lambda field: get_property(field, 'name'), fields),
        "Type": map(lambda field: get_property(field, 'type'), fields),
        "Description": map(lambda field: get_property(field, 'description', '-'), fields),
        "Mode": map(lambda field: get_property(field, 'mode'), fields)
      })
      display(df)

    def display_section_title(text):
      display(HTML('<h2>{}</h2>'.format(text)))

    def format_bq_table_ref(table_ref):
      return '{}.{}.{}'.format(table_ref['projectId'], table_ref['datasetId'], table_ref['tableId'])

    def format_looker_table_ref(table_ref):
      return 'lookmlModel: {}, explore: {}, lookerInstanceUri: {}'.format(table_ref['lookmlModel'], table_ref['explore'], table_ref['lookerInstanceUri'])

    def display_datasource(datasource):
      source_name = ''

      if 'studioDatasourceId' in datasource:
        source_name = datasource['studioDatasourceId']
      elif 'lookerExploreReference' in datasource:
        source_name = format_looker_table_ref(datasource['lookerExploreReference'])
      else:
        source_name = format_bq_table_ref(datasource['bigqueryTableReference'])

      print(source_name)
      display_schema(datasource['schema'])

    def handle_schema_response(resp):
      if 'query' in resp:
        print(resp['query']['question'])
      elif 'result' in resp:
        display_section_title('Schema resolved')
        print('Data sources:')
        for datasource in resp['result']['datasources']:
          display_datasource(datasource)

    def handle_data_response(resp):
      if 'query' in resp:
        query = resp['query']
        display_section_title('Retrieval query')
        print('Query name: {}'.format(query['name']))
        if 'question' in query:
          print('Question: {}'.format(query['question']))
        if 'datasources' in query:
          print('Data sources:')
          for datasource in query['datasources']:
            display_datasource(datasource)
      elif 'generatedSql' in resp:
        display_section_title('SQL generated')
        print(resp['generatedSql'])
      elif 'result' in resp:
        display_section_title('Data retrieved')

        fields = map(lambda field: get_property(field, 'name'), resp['result']['schema']['fields'])
        dict = {}

        for field in fields:
          dict[field] = map(lambda el: get_property(el, field), resp['result']['data'])

        display(pd.DataFrame(dict))

    def handle_chart_response(resp):
      if 'query' in resp:
        print(resp['query']['instructions'])
      elif 'result' in resp:
        vegaConfig = resp['result']['vegaConfig']
        alt.Chart.from_json(json_lib.dumps(vegaConfig)).display();

    def handle_error(resp):
      display_section_title('Error')
      print('Code: {}'.format(resp['code']))
      print('Message: {}'.format(resp['message']))

    def get_stream(url, json):
      s = requests.Session()

      acc = ''

      with s.post(url, json=json, headers=headers, stream=True) as resp:
        for line in resp.iter_lines():
          if not line:
            continue

          decoded_line = str(line, encoding='utf-8')

          if decoded_line == '[{':
            acc = '{'
          elif decoded_line == '}]':
            acc += '}'
          elif decoded_line == ',':
            continue
          else:
            acc += decoded_line

          if not is_json(acc):
            continue

          data_json = json_lib.loads(acc)

          if not 'systemMessage' in data_json:
            if 'error' in data_json:
                handle_error(data_json['error'])
            continue

          if 'text' in data_json['systemMessage']:
            handle_text_response(data_json['systemMessage']['text'])
          elif 'schema' in data_json['systemMessage']:
            handle_schema_response(data_json['systemMessage']['schema'])
          elif 'data' in data_json['systemMessage']:
            handle_data_response(data_json['systemMessage']['data'])
          elif 'chart' in data_json['systemMessage']:
            handle_chart_response(data_json['systemMessage']['chart'])
          else:
            colored_json = highlight(acc, lexers.JsonLexer(), formatters.TerminalFormatter())
            print(colored_json)
            print('\n')
            acc = ''

    def get_stream_multi_turn(url, json, conversation_messages):
        s = requests.Session()

        acc = ''

        with s.post(url, json=json, headers=headers, stream=True) as resp:
            for line in resp.iter_lines():
                if not line:
                    continue

                decoded_line = str(line, encoding='utf-8')

                if decoded_line == '[{':
                    acc = '{'
                elif decoded_line == '}]':
                    acc += '}'
                elif decoded_line == ',':
                    continue
                else:
                    acc += decoded_line

                if not is_json(acc):
                    continue

                data_json = json_lib.loads(acc)
                # Store the response that will be used in the next iteration
                conversation_messages.append(data_json)

                if not 'systemMessage' in data_json:
                    if 'error' in data_json:
                        handle_error(data_json['error'])
                    continue

                if 'text' in data_json['systemMessage']:
                    handle_text_response(data_json['systemMessage']['text'])
                elif 'schema' in data_json['systemMessage']:
                    handle_schema_response(data_json['systemMessage']['schema'])
                elif 'data' in data_json['systemMessage']:
                    handle_data_response(data_json['systemMessage']['data'])
                elif 'chart' in data_json['systemMessage']:
                    handle_chart_response(data_json['systemMessage']['chart'])
                else:
                    colored_json = highlight(acc, lexers.JsonLexer(), formatters.TerminalFormatter())
                    print(colored_json)
                print('\n')
                acc = ''