Menggunakan pendaftaran manual

Anda memerlukan pendaftaran manual di Agent Registry untuk agen yang dihosting di luar Google Cloud atau berjalan di runtime yang tidak didukung. Dokumen ini menunjukkan cara mendaftarkan agen secara manual di Agent Registry.

Sebelum memulai

Sebelum memulai, siapkan Agent Registry. Anda memerlukan project ID untuk melakukan tugas ini.

Untuk menggunakan perintah Google Cloud CLI dalam dokumen ini, pastikan Anda telah menyiapkan lingkungan gcloud CLI.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mendaftarkan agen secara manual di Agent Registry, minta administrator untuk memberi Anda peran IAM Agent Registry API Editor (roles/agentregistry.editor) pada project. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

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

Mendaftarkan agen yang kompatibel dengan A2A

Jika agen jarak jauh Anda mengimplementasikan spesifikasi Agent2Agent (A2A), arahkan Agent Registry ke payload agent-card.json agen. Registry akan otomatis menyinkronkan Kartu Agen dan mengindeks kemampuan agen yang tersedia untuk penemuan.

Ikuti langkah-langkah berikut untuk mendaftarkan agen:

Konsol

  1. Di Google Cloud konsol, buka Agent Registry:

    Buka Agent Registry

  2. Dari pemilih project, pilih Google Cloud project tempat Anda menyiapkan Agent Registry.

  3. Pilih tab Agents.

  4. Klik Add agent.

  5. Di panel Agent details, masukkan detail berikut:

    • Type: Pilih A2A.
    • Wilayah: Pilih lokasi geografis tempat Anda ingin mendaftarkan agen.

  6. Pilih salah satu opsi berikut:

    • Untuk mendaftarkan agen menggunakan URI resource-nya, pilih tab From URI dan masukkan URL yang valid di kolom URI. Kemudian, klik Import untuk mendapatkan Kartu Agen dari URL.
    • Untuk menyalin dan menempel konten Kartu Agen, pilih tab Paste JSON dan tempel seluruh konten file agent-card.json Anda.

  7. Klik Save.

gcloud

Untuk mendaftarkan agen A2A, simpan Kartu Agen agen sebagai file JSON lokal, misalnya, agent-card.json, dan lakukan hal berikut:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=a2a-agent-card \
  --agent-spec-content=agent-card.json

Ukuran file maksimum untuk file spesifikasi adalah 10 KB.

Ganti kode berikut:

  • AGENT_NAME: Nama yang ingin Anda berikan untuk agen Anda, misalnya, my-support-agent.
  • PROJECT_ID: Project ID.
  • REGION: Wilayah tempat Anda ingin mendaftarkan agen. Jika Anda tidak ingin menggunakan region tertentu, gunakan nilai global.
  • DISPLAY_NAME: Nama yang dapat dibaca manusia yang ingin Anda berikan untuk agen Anda, misalnya, Support Agent.

Terraform

Untuk mendaftarkan agen yang kompatibel dengan A2A, konfigurasi resource google_agent_registry_service. Tentukan blok agent_spec dengan jenis A2A_AGENT_CARD dan content yang mewakili payload JSON Kartu Agen Anda:

resource "google_agent_registry_service" "a2a_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"

  agent_spec {
    type    = "A2A_AGENT_CARD"
    content = jsonencode({
      schemaVersion = "v1"
      displayName   = "DISPLAY_NAME"
      description   = "A custom support agent registered using Terraform."
      skills = [
        {
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
        }
      ]
    })
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.a2a_agent.registry_resource
}

Ganti kode berikut:

  • REGION: Region tempat Anda mendaftarkan agen.
  • AGENT_NAME: Nama unik yang ingin Anda berikan untuk agen Anda, misalnya, my-support-agent.
  • DISPLAY_NAME: Nama yang dapat dibaca manusia yang ingin Anda berikan untuk agen Anda, misalnya, Support Agent.

Mendaftarkan agen REST standar

Agen REST standar dapat ditemukan berdasarkan nama dan deskripsi, tetapi tidak memiliki kemampuan yang dapat ditelusuri kecuali jika mengadopsi protokol A2A.

Jika Anda ingin mendaftarkan agen jarak jauh yang tidak mengimplementasikan spesifikasi A2A, seperti endpoint REST standar atau SaaS API, Agent Registry API akan membuat resource Service tanpa spesifikasi protokol agen.

Ikuti langkah-langkah berikut untuk mendaftarkan agen:

Konsol

  1. Di Google Cloud konsol, buka Agent Registry:

    Buka Agent Registry

  2. Dari pemilih project, pilih Google Cloud project tempat Anda menyiapkan Agent Registry.

  3. Pilih tab Agents.

  4. Klik Add agent.

  5. Di panel Agent details, masukkan detail berikut:

    • Tipe: Pilih Non-A2A.
    • Nama: Masukkan nama tampilan yang dapat dibaca manusia untuk agen Anda, seperti Travel Agent.
    • Deskripsi: Masukkan deskripsi kemampuan agen, seperti A test agent that plans travel itineraries.
    • Wilayah: Pilih lokasi geografis tempat Anda ingin mendaftarkan agen.
    • Endpoint: Masukkan endpoint tempat agen dihosting.

  6. Klik Save.

gcloud

Anda dapat secara opsional memberikan antarmuka endpoint HTTP/JSON yang ditentukan dengan flag --interfaces sehingga registry membuat koneksi dengan agen.

Untuk mendaftarkan agen REST standar, lakukan hal berikut:

gcloud agent-registry services create AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --agent-spec-type=no-spec \
  --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

Ganti kode berikut:

  • AGENT_NAME: Nama yang ingin Anda berikan untuk agen Anda, misalnya, my-remote-rest-agent.
  • PROJECT_ID: Project ID.
  • REGION: Region registry.
  • DISPLAY_NAME: Nama yang dapat dibaca manusia yang ingin Anda berikan untuk agen Anda, misalnya, Remote REST Agent.
  • ENDPOINT_URL: URL endpoint API agen, misalnya, https://api.remote-service.com/v1/agents/1234.
  • PROTOCOL: Binding protokol untuk endpoint. Nilai yang valid adalah HTTP_JSON, GRPC, atau JSONRPC.

Terraform

Untuk mendaftarkan agen REST standar, konfigurasi resource google_agent_registry_service dengan agent_spec yang ditetapkan ke jenis NO_SPEC, dan tentukan koneksi antarmuka endpoint:

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "A standard REST agent registered using Terraform."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.rest_agent.registry_resource
}

Ganti kode berikut:

  • REGION: Region tempat Anda mendaftarkan agen.
  • AGENT_NAME: Nama unik yang ingin Anda berikan untuk agen Anda, misalnya, my-remote-rest-agent.
  • DISPLAY_NAME: Nama yang dapat dibaca manusia yang ingin Anda berikan untuk agen Anda, misalnya, Remote REST Agent.
  • ENDPOINT_URL: URL endpoint API agen, misalnya, https://api.remote-service.com/v1/agents/1234.
  • PROTOCOL: Binding protokol untuk endpoint. Nilai yang valid adalah HTTP_JSON, GRPC, atau JSONRPC.

Memverifikasi pendaftaran

Setelah mendaftarkan agen, verifikasi bahwa Agent Registry berhasil memproses Service dan membuat resource Agent yang sesuai:

Konsol

  1. Di Google Cloud konsol, buka Agent Registry:

    Buka Agent Registry

  2. Dari pemilih project, pilih Google Cloud project tempat Anda menyiapkan Agent Registry.

  3. Pilih tab Agents.

    Halaman ini harus menampilkan daftar semua agen terdaftar dan detailnya.

gcloud 

gcloud agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION

Jika Anda memiliki beberapa agen, atau jika Anda ingin mengonfirmasi pendaftaran satu agen, Anda dapat memfilter daftar berdasarkan metadata agen:

gcloud agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION \
  --filter="FILTER_EXPRESSION"

Ganti kode berikut:

  • PROJECT_ID: Project ID.
  • REGION: Wilayah tempat Anda ingin mendaftarkan agen. Jika Anda tidak ingin menggunakan region tertentu, gunakan nilai global.
  • FILTER_EXPRESSION: Ekspresi filter untuk agen yang ingin Anda filter. Misalnya, untuk memfilter berdasarkan nama tampilan, Anda dapat menggunakan displayName='DISPLAY_NAME'. Untuk memfilter berdasarkan ID unik global (URN), Anda dapat menggunakan agentId='urn:agent:AGENT_URN'.

Terraform

Referensi agen terdaftar Anda dalam konfigurasi Terraform lainnya menggunakan sumber data google_agent_registry_agent:

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  filter = "displayName=\"DISPLAY_NAME\""
}

output "agent_urn" {
  value = data.google_agent_registry_agent.my_agent.urn
}

Ganti kode berikut:

  • REGION: Region registry.
  • DISPLAY_NAME: Nama tampilan agen yang dapat dibaca manusia.

Langkah berikutnya