Data Engineering Agent API: Membangun pipeline data dengan agen

Anda dapat menggunakan Data Engineering Agent API, yang diakses melalui geminidataanalytics.googleapis.com, untuk membuat, mengubah, dan mengelola pipeline data guna memuat dan memproses data di BigQuery. API ini menggunakan protokol A2A yang memungkinkan Anda menggunakan perintah bahasa alami untuk membuat dan mengedit pipeline data untuk kebutuhan rekayasa data Anda.

Untuk mengetahui informasi selengkapnya tentang Data Engineering Agent, lihat Menggunakan Data Engineering Agent untuk membuat dan mengubah pipeline data.

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

Sebelum memulai

Sebelum menggunakan Data Engineering Agent API, lakukan langkah-langkah di bagian ini.

Mengaktifkan API

Pastikan Anda telah mengaktifkan API yang diperlukan dan memiliki izin yang diperlukan Untuk mengetahui informasi selengkapnya, lihat Mengaktifkan API yang diperlukan.

Menginstal library klien

Instal library klien berikut:

Untuk mengetahui informasi selengkapnya, lihat Protokol Agent2Agent (A2A).

Ekstensi A2A yang didukung

Data Engineering Agent mendukung ekstensi A2A berikut, yang beberapa di antaranya diperlukan saat berinteraksi dengan Data Engineering Agent.

Nama Ekstensi Persyaratan Deskripsi URI
GcpResource Wajib ID resource untuk resource yang dioperasikan oleh agen. Google Cloud ID ini diperlukan untuk setiap permintaan. https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1
ConversationToken Opsional Ekstensi untuk histori percakapan multi-turn sebagai token percakapan buram.

Ekstensi ini diperlukan untuk percakapan multi-turn guna melanjutkan percakapan dari status sebelumnya. Untuk melanjutkan, salin nilai token percakapan di kolom metadata respons sebelumnya dari agen, dan sertakan di kolom metadata permintaan berikutnya ke agen.		 https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1
MessageLevel Opsional Tingkat pesan untuk kontrol visibilitas klien atas pembaruan pesan.

Agen yang mendukung ekstensi ini melampirkan messageLevel ke setiap message untuk kontrol visibilitas klien.		 https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1
Finish Reason Opsional Ekstensi yang menunjukkan alasan agen berhenti.

Saat DEADLINE_EXCEEDED ditampilkan, klien akan melanjutkan tugas dari tempat terakhirnya dengan token percakapan yang ditampilkan dalam respons di metadata.		 https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Instruction Opsional Petunjuk agen yang ditentukan pengguna.

Agen yang mendukung ekstensi ini menerima daftar petunjuk agen sebagai konteks tambahan dengan kunci agentInstructions. Petunjuk agen ditentukan oleh skema berikut:
  • Name: nama petunjuk. Biasanya berupa nama file
  • Definition: definisi petunjuk
 https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1

Mengaktifkan ekstensi A2A

Untuk mengaktifkan ekstensi A2A, klien Anda harus menyertakan header A2A-Extensions dalam permintaan HTTP ke agen. Nilainya adalah daftar URI ekstensi yang dipisahkan koma untuk aktivasi.

Ekstensi GcpResource harus diaktifkan untuk berinteraksi dengan Data Engineering Agent A2A API.

Contoh berikut menunjukkan permintaan HTTP untuk mengaktifkan ekstensi A2A.

POST /v1/a2a/projects/{project}/locations/{location}/agents/dataengineeringagent/v1/message:stream HTTP/1.1
Host: geminidataanalytics.googleapis.com
Content-Type: application/json
Authorization: Bearer $(gcloud auth print-access-token)
A2A-Extensions: https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Content-Length: 869

{
  "request": {
    "messageId": "0ad14bfa-8d17-48ce-8669-52a856129a66",
    "role": "ROLE_USER",
    "contextId": "test-context-id",
    "content": [{
      "text": "hi"
    }]
  },
  "metadata": {
    "https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1": "cmVxdWVzdGNvbnZlcnNhdGlvbnRva2Vu",
    "https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1": {
      "gcpResourceId": "projects/{project}/locations/{location}/repositories/{repository}/workspaces/{workspace}"
    },
   "https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1": {
      "agentInstructions": [{
        "definition": "Always use uppercase for SQL keywords.",
        "name": "style_guide.md"
      }]
    }
  },
  "tenant": "projects/{project}/locations/{location}/agents/dataengineeringagent"
}

Responsnya mungkin mirip dengan berikut ini.

HTTP/1.1 200 OK
Content-Type: application/json
A2A-Extensions: https://geminidataanalytics.googleapis.com/a2a/extensions/messagelevel/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/instruction/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/gcpresource/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1,
  https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1
Transfer-Encoding: chunked

{
  "statusUpdate": {
    "status": {
      "state": "TASK_STATE_COMPLETED",
      "timestamp": "example-timestamp"
    },
    "final": true,
    "metadata": {
      "https://geminidataanalytics.googleapis.com/a2a/extensions/conversationtoken/v1": "Y29udmVyc2F0aW9udG9rZW4=",
      "https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/v1": "FINISHED"
    }
  }
}

Operasi API utama

API ini menyediakan endpoint inti berikut untuk menggunakan Data Engineering Agent:

Operasi Metode HTTP Endpoint Deskripsi
Mendapatkan Kartu Agen DAPATKAN /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/card Mengambil informasi kartu agen.
Mengirim Pesan Streaming POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:stream Metode streaming untuk mengirim perintah ke agen dan menerima respons streaming.

Izin berikut diperlukan: geminidataanalytics.locations.useDataEngineeringAgent.
Kirim Pesan POST /v1/a2a/{tenant=projects/*/locations/*/agents/dataengineeringagent}/v1/message:send Metode unary untuk mengirim perintah ke agen dan menerima respons sinkron. Metode ini dapat berguna untuk validasi cepat atau pertanyaan satu kali.

Izin berikut diperlukan: geminidataanalytics.locations.useDataEngineeringAgent.

Referensi lainnya

Untuk mengetahui deskripsi mendetail tentang metode, endpoint, dan definisi jenis untuk struktur permintaan dan respons, lihat Referensi REST Data Engineering Agent API.