Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Menggunakan pendaftaran manual

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

Peringatan: Fitur ini tidak didukung di lokasi multi-region us dan eu. Anda harus menggunakan wilayah yang didukung atau lokasi global. Untuk mengetahui informasi selengkapnya, lihat Lokasi 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 Anda perlukan guna mendaftarkan agen secara manual di Agent Registry, minta administrator untuk memberi Anda peran IAM berikut pada project:

Untuk mendaftarkan agen di Agent Registry: Agent Registry API Editor (roles/agentregistry.editor)
Untuk pendaftaran lintas project, guna mengakses metadata agen di project jarak jauh: Pelihat Agent Registry API (roles/agentregistry.viewer)

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.

Anda tidak memerlukan izin tambahan jika endpoint agen atau Kartu Agen dapat diakses menggunakan URL publik standar atau diautentikasi melalui kredensial yang telah dikonfigurasi sebelumnya.

Mendaftarkan agen yang kompatibel dengan A2A

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

Ikuti langkah-langkah berikut untuk mendaftarkan agen:

Konsol

Di konsol Google Cloud , buka Agent Registry:

Buka Agent Registry
Dari pemilih project, pilih Google Cloud project tempat Anda menyiapkan Agent Registry.
Pilih tab Agen.
Klik Tambahkan agen.
Di panel Agent details, masukkan detail berikut:
- Jenis: Pilih A2A.
- Region: Pilih lokasi geografis tempat Anda ingin mendaftarkan agen.
Pilih salah satu opsi berikut:
- Untuk mendaftarkan agen menggunakan URI resource, pilih tab Dari URI dan masukkan URL yang valid di kolom URI. Kemudian, klik Impor untuk mendapatkan Kartu Agen dari URL.
- Untuk menyalin dan menempelkan konten Kartu Agen, pilih tab Tempelkan JSON dan tempelkan seluruh konten file agent-card.json Anda.
Klik Simpan.

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, misalnya, my-support-agent.
PROJECT_ID: Project ID.
REGION: Region tempat Anda ingin mendaftarkan agen. Jika Anda tidak ingin menggunakan wilayah tertentu, gunakan nilai global.
DISPLAY_NAME: Nama yang mudah dibaca yang ingin Anda berikan ke agen, 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 merepresentasikan 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 ke agen Anda, misalnya, my-support-agent.
DISPLAY_NAME: Nama yang mudah dibaca yang ingin Anda berikan ke agen, misalnya, Support Agent.

Mendaftarkan agen REST standar

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

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

Ikuti langkah-langkah berikut untuk mendaftarkan agen:

Konsol

Di konsol Google Cloud , buka Agent Registry:

Buka Agent Registry
Dari pemilih project, pilih Google Cloud project tempat Anda menyiapkan Agent Registry.
Pilih tab Agen.
Klik Tambahkan agen.
Di panel Agent details, masukkan detail berikut:
- Jenis: Pilih Non-A2A.
- Name: Masukkan nama tampilan yang mudah dibaca untuk agen Anda, seperti Travel Agent.
- Deskripsi: Masukkan deskripsi kemampuan agen, seperti A test agent that plans travel itineraries.
- Region: Pilih lokasi geografis tempat Anda ingin mendaftarkan agen.
- Endpoint: Masukkan endpoint tempat agen dihosting.
Klik Simpan.

gcloud

Anda dapat secara opsional menyediakan antarmuka endpoint HTTP/JSON yang ditentukan dengan tanda --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, misalnya, my-remote-rest-agent.
PROJECT_ID: Project ID.
REGION: Region registri.
DISPLAY_NAME: Nama yang mudah dibaca yang ingin Anda berikan ke agen, misalnya, Remote REST Agent.
ENDPOINT_URL: URL endpoint API agen, misalnya, https://api.remote-service.com/v1/agents/1234.
PROTOCOL: Pengikatan 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 ke agen Anda, misalnya, my-remote-rest-agent.
DISPLAY_NAME: Nama yang mudah dibaca yang ingin Anda berikan ke agen, misalnya, Remote REST Agent.
ENDPOINT_URL: URL endpoint API agen, misalnya, https://api.remote-service.com/v1/agents/1234.
PROTOCOL: Pengikatan protokol untuk endpoint. Nilai yang valid adalah HTTP_JSON, GRPC, atau JSONRPC.

Mendaftarkan agen dari project lain

Jika organisasi Anda men-deploy agen di beberapa project Google Cloud dan menggunakan Agent Gateway pusat untuk mengatur traffic keluar, Anda dapat mendaftarkan agen dari project spoke atau workload ke katalog Agent Registry pusat.

Karena pendaftaran otomatis hanya menemukan resource yang dibuat dalam project yang sama, Anda harus mendaftarkan setiap agen jarak jauh secara manual ke registry project tata kelola pusat.

Pertimbangan untuk pendaftaran lintas project

Sebelum mendaftarkan agen di seluruh project, tinjau hal berikut:

Lokasi yang kompatibel: Instance Agent Registry, Agent Gateway, dan endpoint agen harus berada di region geografis yang sama atau lokasi global.
Batasan penemuan otomatis: Penemuan lintas project otomatis tidak didukung. Anda harus mendaftarkan setiap agen jarak jauh secara manual.
Pengelolaan siklus proses: Entri manual di Agent Registry tidak diperbarui atau dihapus secara otomatis saat terjadi perubahan di project jarak jauh. Anda harus mengelola siklus proses entri ini di registry pusat saat agen jarak jauh diubah atau dihapus.
Khusus mode keluar: Tata kelola lintas project dengan Agent Gateway hanya didukung untuk gateway Agent-to-Anywhere (keluar). Gateway ingress Client-to-Agent mengharuskan agen dan gateway berada dalam project yang sama.

Mendaftarkan remote agent

Untuk mendaftarkan agen secara manual dari project lain, ikuti langkah-langkah berikut:

Konsol

Di konsol Google Cloud , buka Agent Registry:

Buka Agent Registry
Dari pemilih project, pilih project tata kelola terpusat Google Cloud tempat Anda ingin mendaftarkan agen.
Pilih tab Agen.
Klik Tambahkan agen.
Di panel Agent details, masukkan detail berikut:
- Jenis: Pilih A2A jika agen jarak jauh menerapkan protokol A2A, atau Non-A2A untuk endpoint REST standar.
- Region: Pilih region yang cocok dengan deployment agen jarak jauh dan gateway pusat Anda.
Berikan endpoint agen:
- Untuk agen A2A, pilih Dari URI dan masukkan URL Kartu Agen agen jarak jauh, atau pilih Tempel JSON dan tempelkan konten agent-card.json.
- Untuk agen non-A2A, masukkan URL Endpoint agen jarak jauh.
Klik Simpan.

gcloud

Agen A2A: Untuk mendaftarkan agen A2A dari project lain menggunakan gcloud CLI, jalankan perintah berikut di project tata kelola pusat:

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

Agen REST: Untuk mendaftarkan agen REST standar dari project lain, jalankan perintah berikut di project tata kelola pusat:

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

Ganti kode berikut:

AGENT_NAME: Nama untuk agen Anda di registri pusat, misalnya, remote-support-agent.
CENTRAL_PROJECT_ID: Project ID project tata kelola pusat.
REGION: Region tempat Anda mendaftarkan agen.
DISPLAY_NAME: Nama yang mudah dibaca untuk agen, misalnya, Remote Support Agent.
REMOTE_ENDPOINT_URL: URL endpoint agen yang berjalan di project jarak jauh, misalnya, https://<var>AGENT_SERVICE_NAME</var>-<var>HASH</var>.<var>REGION</var>.run.app.
PROTOCOL: Pengikatan protokol untuk endpoint. Nilai yang valid adalah http-json, grpc, atau jsonrpc.

Terraform

Untuk mendaftarkan agen jarak jauh dalam project tata kelola terpusat menggunakan Terraform, konfigurasikan resource google_agent_registry_service dan tentukan project pusat:

resource "google_agent_registry_service" "remote_agent" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Remote agent registered from project REMOTE_PROJECT_ID."

  agent_spec {
    type = "NO_SPEC"
  }

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

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

Ganti kode berikut:

CENTRAL_PROJECT_ID: Project ID project tata kelola pusat.
REGION: Region tempat Anda mendaftarkan agen.
AGENT_NAME: Nama unik untuk agen Anda di registry, misalnya, remote-support-agent.
DISPLAY_NAME: Nama yang mudah dibaca untuk agen, misalnya, Remote Support Agent.
REMOTE_PROJECT_ID: Project ID tempat agen dihosting.
REMOTE_ENDPOINT_URL: URL endpoint agen yang berjalan di project jarak jauh.
PROTOCOL: Pengikatan protokol untuk endpoint. Nilai yang valid adalah HTTP_JSON, GRPC, atau JSONRPC.

Verifikasi pendaftaran

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

Konsol

Di konsol Google Cloud , buka Agent Registry:

Buka Agent Registry
Dari pemilih project, pilih Google Cloud project tempat Anda menyiapkan Agent Registry.
Pilih tab Agen.

Halaman ini 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 menurut metadata agen:

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

Ganti kode berikut:

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

Terraform

Mereferensikan agen terdaftar Anda dalam konfigurasi Terraform lain 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 registri.
DISPLAY_NAME: Nama tampilan agen yang dapat dibaca manusia.

Langkah berikutnya

Pelajari cara mengelola agen terdaftar.
Pelajari pendaftaran otomatis, metode yang direkomendasikan untuk mendaftarkan agen yang di-deploy ke runtime terkelola.

Menggunakan pendaftaran manual Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Sebelum memulai

Peran yang diperlukan

Mendaftarkan agen yang kompatibel dengan A2A

Konsol

gcloud

Terraform

Mendaftarkan agen REST standar

Konsol

gcloud

Terraform

Mendaftarkan agen dari project lain

Pertimbangan untuk pendaftaran lintas project

Mendaftarkan remote agent

Konsol

gcloud

Terraform

Verifikasi pendaftaran

Konsol

gcloud

Terraform

Langkah berikutnya

Menggunakan pendaftaran manual