Data Engineering Agent API: Membangun pipeline data dengan agen

Anda dapat menggunakan Data Engineering Agent API, yang diakses melalui geminidataanalytics.googleapis.com, untuk membangun, 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 sesuai kebutuhan rekayasa data Anda.

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

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

Google Cloud

Sebelum memulai

Sebelum Anda 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

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

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

Ekstensi ini diperlukan agar percakapan multi-turn dapat 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 melanjutkan tugas dari tempat terakhir kali tugas tersebut dihentikan dengan token percakapan yang ditampilkan dalam respons di metadata.		 https://geminidataanalytics.googleapis.com/a2a/extensions/finishreason/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/pipelinecontext/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/pipelinecontext/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 menyediakan endpoint inti berikut untuk menggunakan Agen Data Engineering:

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. Opsi ini dapat berguna untuk validasi cepat atau pertanyaan satu putaran.

Izin berikut diperlukan: geminidataanalytics.locations.useDataEngineeringAgent.

Referensi lainnya

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