Membangun agen data menggunakan HTTP dan Python

Halaman ini memandu Anda menggunakan Python untuk membuat permintaan HTTP ke Conversational Analytics API (diakses melalui geminidataanalytics.googleapis.com).

Kode Python contoh di halaman ini menunjukkan cara menyelesaikan tugas-tugas berikut:

Mengonfigurasi setelan awal dan autentikasi

Kode Python contoh berikut melakukan tugas-tugas ini:

  • Mengimpor library Python yang diperlukan.
  • Mendapatkan token akses untuk autentikasi HTTP menggunakan Google Cloud CLI.
  • Menentukan variabel untuk project penagihan, lokasi, dan petunjuk sistem.
  • Menetapkan endpoint API berdasarkan variabel location.
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"

Ganti nilai contoh sebagai berikut:

  • BILLING_PROJECT: ID project Google Cloud tempat Anda mengaktifkan API yang diperlukan.

  • LOCATION: Lokasi tempat resource Anda disimpan. Untuk menggunakan endpoint global, tentukan global. Untuk memenuhi persyaratan residensi data, tentukan satu region yang didukung (seperti us-east4) atau multi-region (seperti eu atau us). Untuk mengetahui informasi selengkapnya, lihat Residensi data.

  • SYSTEM_INSTRUCTIONS: Petunjuk sistem untuk memandu perilaku agen dan menyesuaikannya dengan kebutuhan data Anda. Misalnya, Anda dapat menggunakan petunjuk sistem untuk menentukan istilah bisnis, mengontrol panjang respons, atau menetapkan format data. Idealnya, tentukan petunjuk sistem menggunakan format YAML yang direkomendasikan dalam Menulis petunjuk sistem yang efektif untuk memberikan panduan yang mendetail dan terstruktur.

Melakukan autentikasi ke Looker

Jika Anda berencana untuk terhubung ke sumber data Looker, Anda harus melakukan autentikasi ke instance Looker.

Menggunakan kunci API

Contoh kode Python berikut menunjukkan cara mengautentikasi agen Anda ke instance Looker menggunakan kunci API.

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

Ganti nilai contoh sebagai berikut:

  • CLIENT_ID: Client ID kunci Looker API yang Anda buat.
  • CLIENT_SECRET: Rahasia klien dari kunci Looker API yang Anda buat.

Menggunakan token akses

Contoh kode Python berikut menunjukkan cara mengautentikasi agen Anda ke instance Looker menggunakan token akses.

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

Ganti nilai contoh sebagai berikut:

  • ACCESS_TOKEN: Nilai access_token yang Anda buat untuk melakukan autentikasi ke Looker.

Melakukan autentikasi ke AlloyDB untuk PostgreSQL

Jika Anda berencana untuk terhubung ke sumber data AlloyDB, gunakan gcloud CLI untuk melakukan autentikasi ke instance AlloyDB.

  1. Aktifkan autentikasi Identity and Access Management (IAM) di AlloyDB dengan mengaktifkan flag alloydb.iam_authentication di instance AlloyDB.
  2. Memberikan peran IAM. Akun utama (akun pengguna atau layanan) yang memanggil Conversational Analytics API memerlukan izin IAM yang sesuai di project Google Cloud Anda. Peran ini biasanya mencakup peran seperti alloydb.databaseUser.
  3. Membuat pengguna database yang sesuai. Buat pengguna AlloyDB yang mencerminkan akun utama IAM, menggunakan alamat email akun pengguna atau layanan sebagai nama pengguna.

Untuk mengetahui informasi selengkapnya, lihat Autentikasi database IAM.

Melakukan autentikasi ke Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL

Jika Anda berencana untuk terhubung ke sumber data Cloud SQL untuk MySQL atau Cloud SQL untuk PostgreSQL, Anda harus melakukan autentikasi ke instance Cloud SQL.

  1. Aktifkan autentikasi database IAM. Pastikan flag cloudsql.iam_authentication ditetapkan ke on di instance Cloud SQL untuk MySQL Anda. Anda dapat menambahkan ini saat membuat instance atau saat mem-patch instance yang ada.

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

  2. Berikan peran IAM yang diperlukan.

    Akun utama (akun pengguna atau layanan) yang mencoba terhubung memerlukan izin IAM cloudsql.instances.login dan cloudsql.instances.connect pada project. Untuk memberikan peran dan izin ini, lakukan salah satu hal berikut:

    1. Berikan peran roles/cloudsql.instanceUser. Hal ini mencakup izin untuk login ke instance (cloudsql.instances.login) dan terhubung menggunakan proxy (cloudsql.instances.connect).
    2. Atau, berikan peran khusus yang berisi setidaknya cloudsql.instances.login dan cloudsql.instances.connect.

  3. Tambahkan akun utama IAM sebagai pengguna database. Buat pengguna di instance Cloud SQL yang sesuai dengan alamat email principal IAM.

    Untuk akun layanan, jalankan perintah berikut:

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

    Untuk akun pengguna, jalankan perintah berikut:

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

  4. Memberikan hak istimewa database. Menghubungkan dengan IAM akan mengautentikasi pengguna ke database, tetapi tidak otomatis memberikan izin dalam database. Anda harus menggunakan perintah PostgreSQL standar—seperti GRANT—untuk memberikan izin pengguna database baru ini pada objek tertentu seperti tabel dan skema.

  5. Hubungkan sebagai superuser—seperti pengguna postgres default—dan jalankan perintah berikut:

    -- Example: Connect using psql as the 'postgres' user

GRANT SELECT ON ALL TABLES IN SCHEMA public TO
"user-or-service-account@example.com";

  6. Hubungkan menggunakan autentikasi IAM.

    Klien biasanya terhubung melalui Proxy Auth Cloud SQL atau library konektor, yang menangani pertukaran token. Nama pengguna database adalah email akun utama IAM. Sandi tidak digunakan. Token OAuth 2.0, yang biasanya ditangani secara otomatis oleh Cloud SQL Auth Proxy atau oleh Google Cloud CLI, akan digunakan sebagai gantinya.

    Contoh berikut menggunakan psql dan gcloud CLI untuk membuat token:

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

    Untuk mengetahui informasi selengkapnya, lihat Autentikasi IAM.

    Ganti nilai contoh sebagai berikut:

    • INSTANCE_NAME: ID instance Cloud SQL yang ingin Anda patch untuk mengaktifkan autentikasi database IAM.
    • SERVICE_ACCOUNT_EMAIL: alamat email akun layanan.
    • USER_EMAIL: alamat email akun pengguna.
    • HOST_IP: alamat IP instance Cloud SQL.
    • IAM_PRINCIPAL_EMAIL: alamat email akun utama IAM—misalnya, akun layanan atau pengguna.
    • DATABASE_NAME: nama database yang akan dihubungkan.

Melakukan Autentikasi ke Spanner

Jika Anda berencana untuk terhubung ke sumber data Spanner, Anda harus melakukan autentikasi ke instance Spanner.

  1. Memberikan peran IAM. Akun utama (akun pengguna atau layanan) yang memanggil Conversational Analytics API memerlukan izin IAM yang sesuai di project Google Cloud Anda. Peran ini biasanya mencakup peran seperti databaseUser.
  2. Buat peran database abstrak yang sesuai di Spanner menggunakan Bahasa Definisi Data (DDL).
  3. Gunakan kebijakan IAM untuk mengizinkan akun utama IAM mengasumsikan peran database tersebut.

Untuk mengetahui informasi selengkapnya, lihat Hak istimewa kontrol akses terperinci.

Menghubungkan ke sumber data

Bagian berikut menunjukkan cara menentukan detail koneksi untuk sumber data agen Anda. Agen Anda dapat terhubung ke data dengan cara berikut:

Menghubungkan ke data Looker

Kode contoh berikut menentukan koneksi ke Eksplorasi Looker. Untuk membuat koneksi dengan instance Looker, pastikan Anda telah membuat kunci Looker API, seperti yang dijelaskan dalam Mengautentikasi dan terhubung ke sumber data. Anda dapat terhubung ke maksimal lima Looker Explore sekaligus dengan Conversational Analytics API.

Saat Anda terhubung ke sumber data Looker, perhatikan hal berikut:

  • Anda dapat mengkueri Explore yang disertakan dalam percakapan.
  • Agen hanya dapat mengkueri satu Explore dalam satu waktu. Anda tidak dapat menjalankan kueri di beberapa Eksplorasi secara bersamaan.
  • Agen dapat mengkueri beberapa Eksplorasi dalam percakapan yang sama.

  • Agen dapat mengkueri beberapa Explore dalam percakapan yang menyertakan pertanyaan dengan beberapa bagian, atau dalam percakapan yang menyertakan pertanyaan lanjutan.

    Misalnya: Pengguna menghubungkan dua Eksplorasi, satu bernama cat-explore dan satu bernama dog-explore. Pengguna memasukkan pertanyaan "Mana yang lebih banyak: jumlah kucing atau jumlah?" Tindakan ini akan membuat dua kueri: satu untuk menghitung jumlah kucing di cat-explore dan satu untuk menghitung jumlah di dog-explore. Agen membandingkan angka dari kedua kueri setelah menyelesaikan kedua kueri.

Kode contoh berikut menentukan koneksi ke beberapa Eksplorasi Looker. Untuk meningkatkan performa agen, Anda dapat memberikan golden query sebagai konteks terstruktur untuk Explore. Untuk mengetahui informasi selengkapnya, lihat Menentukan konteks agen data untuk sumber data Looker.

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
        ],
    }
}

Ganti nilai contoh sebagai berikut:

  • INSTANCE_URI: URL lengkap instance Looker Anda (misalnya, https://mycompany.looker.com).
  • MODEL: Nama model LookML yang menyertakan Explore yang ingin Anda hubungkan.
  • EXPLORE: Nama Looker Explore yang ingin Anda kueri oleh agen data.
  • MODEL_2: Nama model LookML kedua yang menyertakan Explore yang ingin Anda hubungkan. Anda dapat mengulangi variabel ini untuk model tambahan hingga lima Eksplorasi.
  • EXPLORE_2: Nama Looker Explore tambahan yang ingin Anda kueri oleh agen data. Anda dapat mengulangi variabel ini untuk menyertakan hingga lima Eksplorasi.

Menghubungkan ke data BigQuery

Dengan Conversational Analytics API, tidak ada batasan ketat terkait jumlah tabel BigQuery yang dapat Anda hubungkan. Namun, menghubungkan ke banyak tabel dapat mengurangi akurasi atau menyebabkan Anda melebihi batas token input model.

Bagian berikut menunjukkan cara terhubung ke data BigQuery menggunakan referensi tabel, referensi grafik, atau keduanya.

Menghubungkan ke tabel BigQuery

Kode contoh berikut menentukan koneksi ke beberapa tabel BigQuery dan menyertakan contoh kolom konteks terstruktur opsional. Untuk meningkatkan performa agen, Anda dapat memberikan konteks terstruktur untuk tabel BigQuery, seperti deskripsi tabel dan kolom, sinonim, tag, contoh kueri, dan fungsi yang ditentukan pengguna (UDF). Untuk mengetahui informasi selengkapnya, lihat Menentukan konteks agen data untuk sumber data BigQuery.

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"
            },
        ]
    }
}

Ganti nilai contoh sebagai berikut:

  • PROJECT_ID: ID project Google Cloud yang berisi set data dan tabel BigQuery yang ingin Anda hubungkan. Untuk terhubung ke set data publik, tentukan bigquery-public-data.
  • DATASET_ID: ID set data BigQuery.
  • TABLE_ID: ID tabel BigQuery.
  • TABLE_DESCRIPTION: Deskripsi opsional tentang konten dan tujuan tabel.
  • COLUMN_NAME: Nama kolom dalam tabel yang deskripsi opsionalnya Anda berikan.
  • COLUMN_DESCRIPTION: Deskripsi opsional tentang konten dan tujuan kolom.

Menghubungkan ke BigQuery Graph

Anda juga dapat terhubung ke grafik menggunakan BigQuery Graph. Berikan satu atau beberapa referensi grafik di kolom propertyGraphReferences.

Untuk mengetahui informasi tentang persyaratan edisi BigQuery dan batasan kueri grafik, lihat Menghubungkan ke BigQuery Graph.

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

Ganti nilai contoh sebagai berikut:

  • GRAPH_PROJECT_ID: ID project Google Cloud yang berisi grafik BigQuery.
  • GRAPH_DATASET_ID: ID set data BigQuery yang berisi grafik.
  • GRAPH_ID: ID grafik BigQuery.

Untuk mengkueri tabel dan grafik dengan agen data yang sama, sertakan tableReferences dan propertyGraphReferences dalam objek bq.

Menghubungkan ke data Data Studio

Kode contoh berikut menentukan koneksi ke sumber data Data Studio.

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

Ganti studio_datasource_id dengan ID sumber data.

Menghubungkan ke data AlloyDB

Conversational Analytics API menggunakan kolom database_reference di kolom alloydb untuk terhubung ke cluster AlloyDB Anda.

Contoh berikut menentukan koneksi ke database AlloyDB.

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"
          # }

    }
}

Ganti nilai contoh sebagai berikut:

  • PROJECT_ID: ID project Google Cloud yang berisi cluster AlloyDB.
  • REGION: Region tempat cluster AlloyDB berada—misalnya, us-central1.
  • CLUSTER_ID: ID cluster AlloyDB.
  • INSTANCE_ID: ID instance AlloyDB.
  • DATABASE: Nama database target—misalnya, financial.
  • TABLE_1_ID, TABLE_2_ID: Opsional. Daftar tabel dalam database yang disarankan untuk digunakan oleh agen data—misalnya, "loan", "client", "disp".
  • billing_project: ID project penagihan tempat Anda mengaktifkan API yang diperlukan.
  • location: Lokasi tempat set konteks Anda berada—misalnya, global.
  • your_context_set_id: Jika Anda membuat konteks lanjutan untuk agen, ID set konteks Anda.

Menghubungkan ke data Cloud SQL untuk MySQL dan Cloud SQL untuk PostgreSQL

Conversational Analytics API menggunakan kolom database_reference di kolom sql untuk terhubung ke instance Cloud SQL Anda.

Contoh berikut menentukan koneksi ke database Cloud SQL untuk MySQL atau Cloud SQL untuk PostgreSQL.

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"
          # }
    }
}

Ganti nilai contoh sebagai berikut:

  • PROJECT_ID: ID project Google Cloud yang berisi instance Cloud SQL.
  • REGION: Region tempat instance Cloud SQL berada, misalnya, us-central1.
  • CLUSTER_ID: ID cluster Cloud SQL.
  • INSTANCE_ID: ID instance Cloud SQL.
  • DATABASE_ID: Nama database target—misalnya, financial.
  • TABLE_1_ID, TABLE_2_ID: Opsional. Daftar tabel dalam database yang disarankan untuk digunakan oleh agen data—misalnya, "loan", "client", "disp".
  • billing_project: ID project penagihan tempat Anda mengaktifkan API yang diperlukan.
  • location: Lokasi tempat set konteks Anda berada—misalnya, global.
  • your_context_set_id: Jika Anda membuat konteks lanjutan untuk agen, ID set konteks Anda.

Menghubungkan ke data Spanner

Conversational Analytics API menggunakan kolom database_reference di kolom spanner untuk terhubung ke instance Spanner Anda.

Contoh berikut menentukan koneksi ke database Spanner.

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"
        # }
    }
}

Ganti nilai contoh sebagai berikut:

  • PROJECT_ID: ID project Google Cloud yang berisi instance Spanner.
  • INSTANCE_ID: ID instance Spanner.
  • DATABASE: Nama database target—misalnya, financial.
  • TABLE_1_ID, TABLE_2_ID: Daftar tabel dalam database yang disarankan untuk digunakan oleh agen data—misalnya, "loan", "client", "disp".
  • billing_project: ID project penagihan tempat Anda mengaktifkan API yang diperlukan.
  • location: lokasi tempat set konteks Anda berada—misalnya, global.
  • your_context_set_id: jika Anda membuat konteks lanjutan untuk agen, ID set konteks Anda.

Membuat agen data

Kode contoh berikut menunjukkan cara membuat agen data secara sinkron atau asinkron dengan mengirimkan permintaan POST HTTP ke endpoint pembuatan agen data. Payload permintaan mencakup detail berikut:

Anda dapat melindungi agen data dengan kunci enkripsi yang dikelola pelanggan (CMEK) dengan menyertakan kolom kms_key dalam payload permintaan saat membuat agen data. Untuk mengetahui informasi selengkapnya, lihat Kunci enkripsi yang dikelola pelanggan (CMEK).

Anda juga dapat mengaktifkan analisis lanjutan dengan Python secara opsional dengan menyertakan parameter options dalam payload permintaan. Lihat Resource REST: projects.locations.dataAgents untuk mengetahui informasi selengkapnya tentang parameter options dan opsi yang dapat Anda konfigurasi untuk percakapan.

Sinkron

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)

Asinkron

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)

Ganti nilai contoh sebagai berikut:

  • DATA_AGENT_ID: ID unik untuk agen data. Nilai ini digunakan dalam nama resource agen dan sebagai parameter kueri URL data_agent_id.
  • KMS_PROJECT_ID: Jika menggunakan CMEK, project ID tempat kunci dihosting. Jika tidak diberikan, setelan ini akan ditetapkan secara default ke project penagihan Anda.
  • KEY_RING_NAME: Jika menggunakan CMEK, nama key ring Cloud KMS Anda.
  • KEY_NAME: Jika menggunakan CMEK, nama kunci Cloud KMS Anda.
  • KEY_LOCATION: Jika menggunakan CMEK, lokasi key ring Anda. Untuk multi-region eu, gunakan europe. Untuk semua lokasi lainnya, gunakan lokasi yang sama dengan agen data. Jika tidak diberikan, setelan ini akan ditetapkan secara default ke lokasi agen data, yang berfungsi untuk semua lokasi kecuali multi-region eu. Untuk mengetahui informasi selengkapnya, lihat Persyaratan lokasi kunci.
  • This is the description of the data agent.: Deskripsi untuk agen data.

Membuat percakapan

Kode contoh berikut menunjukkan cara membuat percakapan dengan agen data Anda.

Anda dapat melindungi percakapan dengan CMEK secara opsional dengan menyertakan kolom kms_key dalam payload permintaan saat membuat percakapan. Untuk mengetahui informasi selengkapnya, lihat Kunci enkripsi yang dikelola pelanggan (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)

Ganti nilai contoh sebagai berikut:

  • DATA_AGENT_ID: ID agen data, seperti yang ditentukan dalam blok kode contoh di Membuat agen data.
  • CONVERSATION_ID: ID unik untuk percakapan.
  • KMS_PROJECT_ID: Jika menggunakan CMEK, project ID tempat kunci dihosting. Jika tidak diberikan, setelan ini akan ditetapkan secara default ke project penagihan Anda.
  • KEY_RING_NAME: Jika menggunakan CMEK, nama key ring Cloud KMS Anda.
  • KEY_NAME: Jika menggunakan CMEK, nama kunci Cloud KMS Anda.
  • KEY_LOCATION: Jika menggunakan CMEK, lokasi key ring Anda. Untuk multi-region us, gunakan us-central1. Untuk multi-region eu, gunakan europe-west1. Untuk satu region, gunakan region yang sama dengan percakapan. Jika tidak diberikan, setelan ini akan ditetapkan secara default ke lokasi percakapan, yang hanya berfungsi untuk satu region. Untuk mengetahui informasi selengkapnya, lihat Persyaratan lokasi kunci.

Mengelola agen data dan percakapan

Contoh kode berikut menunjukkan cara mengelola agen data dan percakapan Anda menggunakan Conversational Analytics API. Anda dapat melakukan tugas berikut:

Mendapatkan agen data

Kode contoh berikut menunjukkan cara mengambil agen data yang ada dengan mengirimkan permintaan GET HTTP ke URL resource agen data.

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)

Pada contoh sebelumnya, ganti DATA_AGENT_ID dengan ID agen data yang ingin Anda ambil.

Mencantumkan agen data

Kode berikut menunjukkan cara mencantumkan semua agen data untuk project tertentu dengan mengirimkan permintaan GET HTTP ke endpoint dataAgents.

Untuk mencantumkan semua agen, Anda harus memiliki izin geminidataanalytics.dataAgents.list pada project. Untuk mengetahui informasi selengkapnya tentang peran IAM yang menyertakan izin ini, lihat daftar peran yang telah ditetapkan.

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}")

Ganti BILLING_PROJECT dengan ID project penagihan Anda.

Mencantumkan agen data yang dapat diakses

Kode berikut menunjukkan cara mencantumkan semua agen data yang dapat diakses untuk project tertentu dengan mengirimkan permintaan GET HTTP ke endpoint dataAgents:listAccessible.

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}")

Ganti nilai contoh sebagai berikut:

  • BILLING_PROJECT: ID project penagihan Anda.
  • CREATOR_FILTER: Filter yang akan diterapkan berdasarkan pembuat agen data. Nilai yang mungkin mencakup NONE (default), CREATOR_ONLY, dan NOT_CREATOR_ONLY.

Memperbarui agen data

Kode contoh berikut menunjukkan cara mengupdate agen data secara sinkron atau asinkron dengan mengirimkan permintaan PATCH HTTP ke URL resource agen data. Payload permintaan menyertakan nilai baru untuk kolom yang ingin Anda ubah, dan parameter permintaan menyertakan parameter updateMask, yang menentukan kolom yang akan diperbarui.

Sinkron

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)

Asinkron

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)

Ganti nilai contoh sebagai berikut:

  • DATA_AGENT_ID: ID agen data yang ingin Anda perbarui.
  • BILLING_PROJECT: ID project penagihan Anda.
  • Updated description of the data agent.: Deskripsi baru untuk agen data.

Mendapatkan kebijakan IAM untuk agen data

Kode contoh berikut menunjukkan cara mengambil kebijakan IAM untuk agen data dengan mengirimkan permintaan POST HTTP ke URL agen data. Payload permintaan menyertakan jalur agen data.

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)

Ganti nilai contoh sebagai berikut:

  • BILLING_PROJECT: ID project penagihan Anda.
  • DATA_AGENT_ID: ID agen data yang kebijakan IAM-nya ingin Anda dapatkan.

Menetapkan kebijakan IAM untuk agen data

Untuk membagikan agen, Anda dapat menggunakan metode setIamPolicy guna menetapkan peran IAM kepada pengguna di agen tertentu. Kode contoh berikut menunjukkan cara melakukan panggilan POST ke URL agen data dengan payload yang menyertakan binding. Binding menentukan peran yang harus ditetapkan kepada pengguna.

billing_project = "BILLING_PROJECT"
data_agent_id = "DATA_AGENT_ID"
role = "roles/geminidataanalytics.dataAgentEditor"
users = "222larabrown@gmail.com, cloudysanfrancisco@gmail.com"

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)

Ganti nilai contoh sebagai berikut:

  • BILLING_PROJECT: ID project penagihan Anda.
  • DATA_AGENT_ID: ID agen data yang ingin Anda tetapkan kebijakan IAM-nya.
  • 222larabrown@gmail.com, cloudysanfrancisco@gmail.com: Daftar email pengguna yang dipisahkan koma yang ingin Anda beri peran yang ditentukan.

Menghapus agen data

Kode contoh berikut menunjukkan cara menghapus agen data secara sinkron atau asinkron dengan mengirimkan permintaan DELETE HTTP ke URL resource agen data. Saat Anda menghapus agen data, agen tersebut akan memasuki periode penghapusan sementara selama 30 hari dan tidak dapat dipulihkan. Untuk mengetahui informasi selengkapnya, lihat Retensi dan penghapusan data.

Sinkron

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)

Asinkron

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)

Ganti nilai contoh sebagai berikut:

  • BILLING_PROJECT: ID project penagihan Anda.
  • DATA_AGENT_ID: ID agen data yang ingin Anda hapus.

Mendapatkan percakapan

Kode contoh berikut menunjukkan cara mengambil percakapan yang ada dengan mengirimkan permintaan GET HTTP ke URL resource percakapan.

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)

Ganti nilai contoh sebagai berikut:

  • BILLING_PROJECT: ID project penagihan Anda.
  • CONVERSATION_ID: ID percakapan yang ingin Anda ambil.

Membuat daftar percakapan

Kode contoh berikut menunjukkan cara mencantumkan percakapan untuk project tertentu dengan mengirimkan permintaan GET HTTP ke endpoint conversations.

Secara default, metode ini menampilkan percakapan yang Anda buat. Admin (pengguna dengan peran IAM cloudaicompanion.topicAdmin) dapat melihat semua percakapan dalam project.

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)

Ganti BILLING_PROJECT dengan ID project penagihan tempat Anda mengaktifkan API yang diperlukan.

Mencantumkan pesan dalam percakapan

Kode contoh berikut menunjukkan cara mencantumkan semua pesan dalam percakapan dengan mengirimkan permintaan GET HTTP ke endpoint messages percakapan.

Untuk mencantumkan pesan, Anda harus memiliki izin cloudaicompanion.topics.get pada percakapan.

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)

Ganti nilai contoh sebagai berikut:

  • BILLING_PROJECT: ID project penagihan Anda.
  • CONVERSATION_ID: ID percakapan yang pesannya ingin Anda cantumkan.

Menghapus percakapan

Kode contoh berikut menunjukkan cara menghapus percakapan dengan mengirimkan permintaan DELETE HTTP ke URL resource percakapan. Admin (pengguna dengan peran Identity and Access Management cloudaicompanion.topicAdmin) atau pengguna dengan izin Identity and Access Management cloudaicompanion.topics.delete dapat menghapus percakapan dalam project.

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)

Ganti nilai contoh sebagai berikut:

  • BILLING_PROJECT: ID project penagihan Anda.
  • CONVERSATION_ID: ID percakapan yang ingin Anda hapus.

Menggunakan API untuk mengajukan pertanyaan

Setelah membuat agen data dan, untuk chat stateful, percakapan, Anda dapat mengirim kueri ke agen.

Saat Anda mengirim kueri, API akan menampilkan aliran objek Message. Streaming ini dapat berisi berbagai jenis pesan, termasuk teks, tabel data, dan diagram. Pesan teks dapat memberikan insight tentang penalaran agen, melaporkan progresnya, atau memberikan jawaban akhir. Tujuan setiap pesan teks ditunjukkan oleh nilai TextType:

  • THOUGHT: Menampilkan proses penalaran internal agen saat merencanakan cara menjawab kueri Anda. Pesan THOUGHT memberikan insight langkah demi langkah tentang proses penalaran dan pengambilan keputusan agen, serta berisi dua bagian: parts[0] adalah ringkasan pemikiran, yang meringkas teks pemikiran lengkap secara singkat, dan parts[1] adalah teks pemikiran lengkap.
  • PROGRESS: Melaporkan progres agen dalam suatu tindakan, seperti pengambilan data atau alat yang sedang dipanggil. Nilai ini hanya ditampilkan untuk sumber data Looker dan berisi dua bagian: parts[0] adalah ringkasan, dan parts[1] adalah teks progres lengkap.
  • FINAL_RESPONSE: Memberikan jawaban akhir untuk kueri Anda.

Contoh di bagian berikut menggunakan fungsi bantuan yang ditentukan dalam Fungsi Python bantuan untuk melakukan streaming respons chat guna memproses dan menampilkan setiap pesan dalam respons yang di-streaming API. Untuk panduan tentang cara merender pesan ini di antarmuka pengguna saat Anda menggunakan sumber data Looker, lihat Merender respons agen untuk sumber data Looker.

Mengajukan pertanyaan dengan chat stateful dan stateless

Anda dapat berinteraksi dengan API dalam mode utama berikut:

  • Chat stateful: Google Cloud menyimpan dan mengelola histori percakapan. Chat stateful pada dasarnya bersifat multi-turn, karena API mempertahankan konteks dari pesan sebelumnya. You only need to send the current message for each turn.
  • Chat stateless: Aplikasi Anda mengelola histori percakapan. Anda harus menyertakan pesan sebelumnya yang relevan dengan setiap pesan baru. Untuk mengetahui contoh mendetail tentang cara mengelola percakapan multi-turn dalam mode stateless, lihat Membuat percakapan multi-turn stateless.

Contoh berikut menunjukkan cara menggunakan API untuk chat stateful dan stateless dengan membuat permintaan POST ke endpoint :chat.

Chat stateful

Mengirim permintaan chat stateful dengan referensi percakapan

Kode contoh berikut menunjukkan cara mengajukan pertanyaan ke API menggunakan percakapan yang Anda tentukan di langkah sebelumnya. Contoh ini menggunakan fungsi bantuan get_stream untuk menstreaming respons.

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)

Ganti nilai contoh sebagai berikut:

  • DATA_AGENT_ID: ID agen data, seperti yang ditentukan dalam blok kode contoh di Membuat agen data.
  • CONVERSATION_ID: ID unik untuk percakapan.
  • Make a bar graph for the top 5 states by the total number of airports digunakan sebagai perintah contoh.

Chat stateless

Contoh berikut menunjukkan cara mengirim permintaan stateless menggunakan referensi agen data atau konteks inline.

Mengirim permintaan chat stateless dengan referensi agen data

Kode contoh berikut menunjukkan cara mengajukan pertanyaan stateless ke API menggunakan agen data yang Anda tentukan di langkah sebelumnya. Contoh ini menggunakan fungsi bantuan get_stream untuk menstreaming respons.

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)

Ganti nilai contoh sebagai berikut:

  • DATA_AGENT_ID: ID agen data, seperti yang ditentukan dalam blok kode contoh di Membuat agen data.
  • Make a bar graph for the top 5 states by the total number of airports digunakan sebagai perintah contoh.

Mengirim permintaan chat stateless dengan konteks inline

Kode contoh berikut menunjukkan cara mengajukan pertanyaan stateless ke API menggunakan konteks inline. Contoh ini menggunakan fungsi bantuan get_stream untuk melakukan streaming respons dan menggunakan sumber data BigQuery sebagai contoh.

Anda juga dapat mengaktifkan analisis lanjutan dengan Python secara opsional dengan menyertakan parameter options dalam payload permintaan. Lihat halaman REST Resource: projects.locations.dataAgents untuk mengetahui informasi selengkapnya tentang parameter options dan opsi yang dapat Anda konfigurasi untuk percakapan.

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)

Kode contoh berikut menunjukkan cara mengajukan pertanyaan stateless ke API menggunakan konteks inline dan sumber data AlloyDB sebagai contoh.

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)

Membuat percakapan multi-giliran stateless

Untuk mengajukan pertanyaan lanjutan dalam percakapan stateless, aplikasi Anda harus mengelola konteks percakapan dengan mengirimkan seluruh histori pesan bersama setiap permintaan baru. Percakapan multi-giliran memungkinkan Anda mengirim pertanyaan lanjutan yang didasarkan pada giliran percakapan sebelumnya.

Contoh berikut menentukan dan memanggil fungsi multi_turn_conversation untuk mengelola konteks percakapan dengan menyimpan pesan dalam daftar. Fungsi multi_turn_conversation memanggil fungsi get_stream_multi_turn untuk mengurai respons API streaming dan memperbarui daftar conversation_messages. Proses ini mempertahankan konteks untuk giliran berikutnya. Untuk kode get_stream_multi_turn dan fungsi bantuan lain yang diperlukan, lihat Fungsi bantuan chat streaming.

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)

Pada contoh sebelumnya, ganti DATA_AGENT_ID dengan ID agen data, seperti yang ditentukan dalam blok kode contoh di Membuat agen data.

Anda dapat memanggil fungsi bantuan multi_turn_conversation untuk setiap giliran percakapan. Kode contoh berikut menunjukkan cara mengirim permintaan awal, lalu permintaan lanjutan yang dibuat berdasarkan respons sebelumnya:

# 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?")

Pada contoh sebelumnya, ganti nilai contoh sebagai berikut:

  • Which species of tree is most prevalent?: Pertanyaan dalam bahasa alami untuk dikirim ke agen data.
  • Can you show me the results as a bar chart?: Pertanyaan lanjutan yang mengembangkan atau menyempurnakan pertanyaan sebelumnya.

Menentukan fungsi bantuan

Bagian berikut berisi definisi fungsi bantuan yang digunakan dalam contoh kode sebelumnya untuk mengurai respons dari API dan menampilkan hasilnya.

Fungsi bantuan chat streaming

Fungsi berikut mengurai dan menampilkan respons streaming dari API untuk permintaan chat standar (single-turn).

Menampilkan fungsi bantuan untuk streaming respons chat

    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 = ''