Mengorkestrasi agen data dengan A2A

Conversational Analytics API Google Cloud menerapkan protokol Agent-to-Agent (A2A) terbuka, yang memungkinkan agen dalam alur kerja multi-agen menemukan kemampuan, mendelegasikan kueri analisis, dan melakukan streaming respons terstruktur, seperti kueri SQL yang dapat dieksekusi dan visualisasi diagram.

Anda dapat membuat kueri agen data yang dibuat ke dalam Conversational Analytics API untuk BigQuery dan Looker dengan meneruskan konteks set data dalam permintaan API, atau Anda dapat membuat kueri agen data kustom yang dikonfigurasi dengan logika bisnis organisasi Anda.

Untuk membuat dan membuat kueri agen data secara langsung, lihat Membuat agen data menggunakan Python SDK atau Membuat agen data menggunakan HTTP.

Pelajari cara dan waktu Gemini untuk Google Cloud menggunakan data Anda.

Cara kerja orkestrasi agen data

Saat Anda mengintegrasikan agen data Conversational Analytics API ke dalam aplikasi atau sistem multi-agen, alur kerja orkestrasi mengikuti operasi berikut:

  • Agen orkestrator menemukan kapabilitas dan keahlian agen data dengan memeriksa kartu agennya sebelum mendelegasikan kueri analitis.
  • Agen orkestrator mengirim pesan untuk mengkueri agen data bawaan (agents/bigquery-ca atau agents/looker-ca) dengan menentukan sumber data dalam permintaan, atau agen data kustom (dataAgents/DATA_AGENT_ID) yang dikonfigurasi dengan logika bisnis domain.
  • Agen data memproses permintaan, menjalankan kueri yang diperlukan, dan menampilkan hasilnya—baik sebagai respons lengkap atau dengan mengalirkan progres penalaran dan artefak terstruktur (seperti SQL yang dapat dieksekusi dan spesifikasi diagram Vega-Lite).

Sebelum memulai

Sebelum memulai, selesaikan prasyarat berikut:

  1. Aktifkan Conversational Analytics API, BigQuery API, dan Looker API di Google Cloud project Anda.
  2. Pastikan Anda memiliki peran dan izin IAM yang diperlukan.
  3. Lakukan autentikasi terhadap Conversational Analytics API dan instal library klien atau dapatkan token otorisasi.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan guna menemukan dan membuat kueri agen data melalui A2A, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Untuk membuat kueri sumber data pokok, Anda juga harus memiliki izin baca pada set data BigQuery target (seperti roles/bigquery.dataViewer) atau Eksplorasi Looker.

Menemukan kemampuan agen

Sebelum mendelegasikan kueri ke agen data, agen orkestrator, atau aplikasi klien, kartu agen dapat diperiksa untuk melihat kemampuan dan konfigurasinya, seperti deskripsi, keterampilan yang tersedia, dan ekstensi yang didukung. Anda dapat mengambil kartu agen menggunakan metode getCard untuk agen data bawaan (agents/bigquery-ca dan agents/looker-ca) serta agen data kustom (dataAgents/DATA_AGENT_ID).

Mengambil kartu agen

Contoh kode berikut menunjukkan cara mengambil kartu agen. Contoh ini menggunakan agen data BigQuery bawaan (agents/bigquery-ca) sebagai contoh, tetapi Anda dapat mengambil kartu untuk agen Looker bawaan (agents/looker-ca) atau agen data kustom (dataAgents/DATA_AGENT_ID) dengan mengubah nama resource agen dalam permintaan Anda:

Python SDK

from google.cloud import geminidataanalytics_v1

client = geminidataanalytics_v1.DataA2AServiceClient()

agent_name = "projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca"

request = geminidataanalytics_v1.GetAgentCardRequest(tenant=agent_name)
card = client.get_agent_card(request=request)

print(card)

Dalam sampel sebelumnya, ganti nilai sebagai berikut:

  • PROJECT_ID: ID Google Cloud project Anda
  • LOCATION: lokasi resource agen (seperti us, us-east4, eu, atau global)

HTTP

curl -X GET \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  "https://geminidataanalytics.googleapis.com/v1/a2a/projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca/v1/card"

Dalam sampel sebelumnya, ganti nilai sebagai berikut:

  • PROJECT_ID: ID Google Cloud project Anda
  • LOCATION: lokasi resource agen (seperti us, us-east4, eu, atau global)

Memahami struktur kartu agen

Permintaan yang berhasil akan menampilkan objek kartu agen yang berisi metadata, keahlian yang didukung, dan ekstensi:

{
  "name": "BigQuery Conversational Analytics Agent",
  "description": "This agent can answer questions about your data using BigQuery.",
  "protocolVersion": "1.0",
  "skills": [
    {
      "id": "data-analysis",
      "name": "Data Analysis",
      "description": "Provides data analysis assistance",
      "examples": [
        "What is the total sales for the last 3 months?"
      ],
      "inputModes": [
        "text/plain"
      ],
      "outputModes": [
        "text/plain",
        "application/json"
      ]
    }
  ],
  "capabilities": {
    "streaming": true,
    "extensions": [
      {
        "uri": "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1",
        "description": "Google Data Analytics BigQuery Context extension"
      }
    ]
  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain",
    "application/json"
  ]
}

Kartu agen mencakup kolom berikut:

  • name: nama tampilan agen data
  • description: ringkasan kemampuan analisis agen data
  • protocolVersion: versi A2A protocol yang didukung oleh endpoint (seperti 1.0)
  • skills: tugas yang dapat dilakukan agen data, termasuk perintah contoh (examples) dan format data yang didukung (inputModes dan outputModes, seperti text/plain atau application/json)
  • capabilities.streaming: nilai boolean yang menunjukkan apakah agen data mendukung streaming real-time melalui metode stream
  • capabilities.extensions: ekstensi A2A yang didukung oleh agen data, seperti bigquery_context/v1, stateless/v1, dan kms/v1
  • defaultInputModes dan defaultOutputModes: format data default (seperti text/plain atau application/json) untuk payload permintaan dan respons

Mengirim pesan ke agen data

Untuk mengirim pesan ke agen data, gunakan metode send. Agen data memproses permintaan, membuat dan menjalankan kueri SQL yang diperlukan terhadap data Anda, serta menampilkan jawaban bahasa alami beserta artefak data yang dihasilkan.

Kirim pesan

Saat Anda mengirim pesan, tentukan agen data target di jalur resource:

  • Untuk agen data bawaan (agents/bigquery-ca atau agents/looker-ca), teruskan referensi tabel target atau Jelajahi di kolom metadata menggunakan ekstensi bigquery_context/v1 atau looker_context/v1.
  • Untuk agen data kustom (dataAgents/DATA_AGENT_ID), hapus kolom metadata karena konteks, skema, dan petunjuk dikonfigurasi langsung di resource agen.

Untuk memproses kueri tanpa menyimpan histori percakapan di Google Cloud, sertakan ekstensi stateless/v1 dalam permintaan Anda. Untuk mengenkripsi data dan metadata percakapan tersimpan menggunakan kunci enkripsi yang dikelola pelanggan, teruskan ekstensi kms/v1 dengan nama kunci Cloud KMS Anda. Untuk mengetahui informasi selengkapnya, lihat Kunci enkripsi yang dikelola pelanggan (CMEK).

Contoh kode berikut menunjukkan cara mengirim pesan ke agen data BigQuery bawaan:

Python SDK

from google.cloud import geminidataanalytics_v1

client = geminidataanalytics_v1.DataA2AServiceClient()

agent_name = "projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca"

request = geminidataanalytics_v1.SendMessageRequest(
    tenant=agent_name,
    message=geminidataanalytics_v1.Message(
        role="ROLE_USER",
        # Optional: Pass context_id to continue an existing conversation
        # context_id="projects/PROJECT_ID/locations/LOCATION/conversations/CONVERSATION_ID",
        parts=[
            geminidataanalytics_v1.Part(
                text="What are the top 5 countries where our users are located?"
            )
        ],
    ),
    configuration=geminidataanalytics_v1.SendMessageConfiguration(
        return_immediately=False
    ),
    metadata={
        "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
            "datasource_references": {
                "bq": {
                    "tableReferences": [
                        {
                            "projectId": "DATASET_PROJECT_ID",
                            "datasetId": "DATASET_ID",
                            "tableId": "TABLE_ID",
                        }
                    ]
                }
            }
        },
        # Optional: Process queries without storing conversation history in Google Cloud
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/stateless/v1": {},
        # Optional: Encrypt conversation history and metadata with a customer-managed encryption key (CMEK)
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/kms/v1": {
        #     "kmsKey": "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"
        # },
    },
)

response = client.send_message(request=request)

print(response)

Dalam sampel sebelumnya, ganti nilai sebagai berikut:

  • PROJECT_ID: ID Google Cloud project Anda
  • LOCATION: lokasi resource agen (seperti us, us-east4, eu, atau global)
  • CONVERSATION_ID: (Opsional) ID sesi percakapan yang ada untuk dilanjutkan
  • What are the top 5 countries where our users are located?: pertanyaan bahasa alami untuk diajukan kepada agen data
  • DATASET_PROJECT_ID: ID project Google Cloud yang berisi set data BigQuery (misalnya, bigquery-public-data)
  • DATASET_ID: ID set data BigQuery (misalnya, thelook_ecommerce)
  • TABLE_ID: ID tabel BigQuery (misalnya, users)
  • KEY_RING: (Opsional) nama key ring Cloud KMS saat menggunakan CMEK
  • KEY_NAME: (Opsional) nama kunci kripto Cloud KMS saat menggunakan CMEK

HTTP

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "A2A-Extensions: https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "What are the top 5 countries where our users are located?"
        }
      ]
    },
    "configuration": {
      "return_immediately": false
    },
    "metadata": {
      "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
        "datasource_references": {
          "bq": {
            "tableReferences": [
              {
                "projectId": "DATASET_PROJECT_ID",
                "datasetId": "DATASET_ID",
                "tableId": "TABLE_ID"
              }
            ]
          }
        }
      }
    }
  }' \
  "https://geminidataanalytics.googleapis.com/v1/a2a/projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca/v1/message:send"

Dalam sampel sebelumnya, ganti nilai sebagai berikut:

  • PROJECT_ID: ID Google Cloud project Anda
  • LOCATION: lokasi resource agen (seperti us, us-east4, eu, atau global)
  • What are the top 5 countries where our users are located?: pertanyaan bahasa alami untuk diajukan kepada agen data
  • DATASET_PROJECT_ID: ID project Google Cloud yang berisi set data BigQuery (misalnya, bigquery-public-data)
  • DATASET_ID: ID set data BigQuery (misalnya, thelook_ecommerce)
  • TABLE_ID: ID tabel BigQuery (misalnya, users)

Memahami struktur respons

Permintaan yang berhasil akan menampilkan objek task yang berisi status akhir, ID percakapan, dan artefak yang dihasilkan:

{
  "task": {
    "id": "ab12d1f2-e170-4c4f-aff4-be466c6beaaa",
    "contextId": "projects/my-project/locations/us/conversations/conv-67890",
    "status": {
      "state": "TASK_STATE_COMPLETED"
    },
    "artifacts": [
      {
        "artifactId": "synthetic-8a368e8e-378a-4b80-9f07-0b1a397c221d",
        "name": "Final response",
        "description": "Final response from the agent.",
        "parts": [
          {
            "text": "The top 5 countries where our users are located are China (33,783), the United States (22,701), Brasil (14,620), South Korea (5,302), and France (4,645)."
          }
        ]
      },
      {
        "artifactId": "synthetic-50483808-b231-4b30-a859-2c30d0355a8d",
        "name": "Generated SQL",
        "description": "Generated SQL from the agent.",
        "parts": [
          {
            "text": "SELECT country, COUNT(DISTINCT id) AS user_count FROM `bigquery-public-data.thelook_ecommerce.users` GROUP BY country ORDER BY user_count DESC LIMIT 5",
            "mediaType": "text/x-sql"
          }
        ]
      }
    ]
  }
}

Respons mencakup kolom kunci berikut:

  • task.id: ID unik untuk tugas eksekusi
  • task.contextId: jalur resource percakapan, yang Anda teruskan di kolom message.contextId pada permintaan berikutnya untuk melanjutkan sesi
  • task.status.state: status eksekusi tugas (seperti TASK_STATE_COMPLETED)
  • task.artifacts[]: aset terstruktur yang dihasilkan oleh agen data, seperti jawaban bahasa natural (Final response), kueri SQL yang dapat dieksekusi (Generated SQL), dan baris hasil tabular (Data result)

Men-streaming respons dari agen data

Untuk menerima update real-time saat agen data memproses kueri, gunakan metode stream. Respons mengalirkan pembaruan status (status_update) dengan pemikiran sementara dan artefak inkremental (artifact_update), seperti kueri SQL yang dibuat dan spesifikasi diagram Vega-Lite.

Permintaan streaming juga mendukung percakapan berkelanjutan (context_id), pemrosesan stateless (stateless/v1), dan kunci enkripsi yang dikelola pelanggan (kms/v1).

Mengirim pesan streaming

Contoh kode berikut menunjukkan cara melakukan streaming peristiwa dari agen data BigQuery bawaan. Untuk melakukan streaming dari agen data kustom (dataAgents/DATA_AGENT_ID), targetkan jalur resource agen kustom dan hapus kolom metadata:

Python SDK

from google.cloud import geminidataanalytics_v1

client = geminidataanalytics_v1.DataA2AServiceClient()

agent_name = "projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca"

request = geminidataanalytics_v1.SendMessageRequest(
    tenant=agent_name,
    message=geminidataanalytics_v1.Message(
        role="ROLE_USER",
        parts=[
            geminidataanalytics_v1.Part(
                text="What are the top 5 countries where our users are located? Please show a pie chart."
            )
        ],
    ),
    metadata={
        "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
            "datasource_references": {
                "bq": {
                    "tableReferences": [
                        {
                            "projectId": "DATASET_PROJECT_ID",
                            "datasetId": "DATASET_ID",
                            "tableId": "TABLE_ID",
                        }
                    ]
                }
            }
        },
        # Optional: Process queries without storing conversation history in Google Cloud
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/stateless/v1": {},
        # Optional: Encrypt conversation history and metadata with a customer-managed encryption key (CMEK)
        # "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/kms/v1": {
        #     "kmsKey": "projects/PROJECT_ID/locations/LOCATION/keyRings/KEY_RING/cryptoKeys/KEY_NAME"
        # },
    },
)

# Stream response events
stream = client.send_streaming_message(request=request)

for chunk in stream:
  print(chunk)

Dalam sampel sebelumnya, ganti nilai sebagai berikut:

  • PROJECT_ID: ID Google Cloud project Anda
  • LOCATION: lokasi resource agen (seperti us, us-east4, eu, atau global)
  • What are the top 5 countries where our users are located? Please show a pie chart.: pertanyaan bahasa alami untuk diajukan kepada agen data
  • DATASET_PROJECT_ID: ID project Google Cloud yang berisi set data BigQuery (misalnya, bigquery-public-data)
  • DATASET_ID: ID set data BigQuery (misalnya, thelook_ecommerce)
  • TABLE_ID: ID tabel BigQuery (misalnya, users)
  • KEY_RING: (Opsional) nama key ring Cloud KMS saat menggunakan CMEK
  • KEY_NAME: (Opsional) nama kunci kripto Cloud KMS saat menggunakan CMEK

HTTP

curl -X POST \
  -N \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Accept: text/event-stream, application/json" \
  -H "A2A-Extensions: https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1" \
  -d '{
    "message": {
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "What are the top 5 countries where our users are located? Please show a pie chart."
        }
      ]
    },
    "metadata": {
      "https://docs.cloud.google.com/gemini/docs/conversational-analytics-api/reference/a2a/extensions/bigquery_context/v1": {
        "datasource_references": {
          "bq": {
            "tableReferences": [
              {
                "projectId": "DATASET_PROJECT_ID",
                "datasetId": "DATASET_ID",
                "tableId": "TABLE_ID"
              }
            ]
          }
        }
      }
    }
  }' \
  "https://geminidataanalytics.googleapis.com/v1/a2a/projects/PROJECT_ID/locations/LOCATION/agents/bigquery-ca/v1/message:stream"

Dalam sampel sebelumnya, ganti nilai sebagai berikut:

  • PROJECT_ID: ID Google Cloud project Anda
  • LOCATION: lokasi resource agen (seperti us, us-east4, eu, atau global)
  • What are the top 5 countries where our users are located? Please show a pie chart.: pertanyaan bahasa alami untuk diajukan kepada agen data
  • DATASET_PROJECT_ID: ID project Google Cloud yang berisi set data BigQuery (misalnya, bigquery-public-data)
  • DATASET_ID: ID set data BigQuery (misalnya, thelook_ecommerce)
  • TABLE_ID: ID tabel BigQuery (misalnya, users)

Memahami struktur respons streaming

Saat Anda mengirim permintaan streaming, server akan menampilkan aliran objek peristiwa (StreamResponse). Setiap peristiwa berisi pembaruan status atau pembaruan artefak.

Peristiwa pembaruan status memberikan notifikasi progres menengah dan pesan pemikiran saat agen data memproses kueri Anda:

{
  "statusUpdate": {
    "taskId": "f41cd8e3-e665-460c-aceb-7b337f1848ef",
    "status": {
      "state": "TASK_STATE_WORKING",
      "message": {
        "role": "ROLE_AGENT",
        "parts": [
          {
            "text": "Analyzing context"
          },
          {
            "text": "Retrieved context for 1 table."
          }
        ]
      }
    }
  }
}

Peristiwa pembaruan artefak memberikan objek output terstruktur, seperti kueri SQL yang dapat dieksekusi, jawaban bahasa alami, atau spesifikasi diagram:

{
  "artifactUpdate": {
    "taskId": "f41cd8e3-e665-460c-aceb-7b337f1848ef",
    "artifact": {
      "artifactId": "synthetic-7ca98286-0a15-4ca0-a8bc-f14dc231b3ba",
      "name": "Chart result",
      "description": "Chart visualization generated by the data agent.",
      "parts": [
        {
          "data": {
            "title": "Top 5 Countries by User Population",
            "mark": "arc",
            "encoding": {
              "color": {
                "field": "country",
                "type": "nominal"
              },
              "theta": {
                "field": "user_count",
                "type": "quantitative"
              }
            },
            "data": {
              "values": [
                {
                  "country": "China",
                  "user_count": 33783
                },
                {
                  "country": "United States",
                  "user_count": 22701
                },
                {
                  "country": "Brasil",
                  "user_count": 14620
                },
                {
                  "country": "South Korea",
                  "user_count": 5302
                },
                {
                  "country": "France",
                  "user_count": 4645
                }
              ]
            }
          }
        }
      }
    },
    "lastChunk": true
  }
}

Respons streaming mencakup kolom utama berikut:

  • statusUpdate.status.state: status tugas sementara atau akhir (seperti TASK_STATE_WORKING atau TASK_STATE_COMPLETED)
  • statusUpdate.status.message.parts[]: deskripsi pemikiran atau progres yang dikeluarkan selama eksekusi
  • artifactUpdate.artifact: aset terstruktur yang dihasilkan oleh agen data, seperti spesifikasi diagram Vega-Lite (data) atau kueri SQL (text)
  • artifactUpdate.lastChunk: tanda boolean yang menunjukkan apakah aliran artefak sudah selesai

Untuk merender spesifikasi Vega atau Vega-Lite yang ditampilkan di aplikasi Python atau frontend, lihat Merender respons agen sebagai visualisasi.

Langkah berikutnya