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

Menggunakan pendaftaran manual untuk agen

Registry Agen memungkinkan Anda mendaftarkan agen REST standar dan yang mematuhi A2A secara manual yang dihosting di luar Google Cloud, berjalan di runtime yang tidak didukung, atau di-deploy di berbagai project Google Cloud . Dengan membuat resource Service untuk agen ini, Anda membuat endpoint dan kemampuannya dapat ditemukan di seluruh ekosistem AI Anda.

Agent Registry menggunakan Google Cloud project tata kelola pusat. Dalam dokumen ini, istilah jarak jauh mengacu pada agen yang dihosting di luar project tata kelola atau batas pengelolaan, seperti di project Google Cloud terpisah tanpa batas pengelolaan, lingkungan lokal, atau cloud eksternal, atau berjalan pada runtime yang tidak didukung. Karena pendaftaran otomatis hanya menemukan resource yang didukung yang di-deploy di project tata kelola tempat Agent Registry diaktifkan, atau di seluruh project saat Anda mengonfigurasi batas pengelolaan, Anda harus mendaftarkan agen jarak jauh secara manual di registry project tata kelola dalam semua kasus lainnya.

Jenis agen dan batasan

Anda dapat mendaftarkan dua jenis agen secara manual:

Agen yang mematuhi A2A: agen yang menerapkan spesifikasi Agent2Agent (A2A) dengan jenis A2A_AGENT_CARD. Registry akan memindai endpoint agent-card.json Kartu Agen mereka untuk mengindeks kemampuan A2A mereka.
Agen REST standar: agen jarak jauh yang tidak menerapkan spesifikasi A2A dan menggunakan jenis NO_SPEC, seperti agen yang mengekspos endpoint API REST.

Pendaftaran manual 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

Menyiapkan Agent Registry.
Untuk penyiapan project tunggal, dapatkan project ID dari project tata kelola tempat Agent Registry diaktifkan. Jika Anda mengonfigurasi batas pengelolaan untuk beberapa project, gunakan ID project pengelolaan Anda untuk penemuan dan pendaftaran di seluruh batas, atau tentukan ID project anggota untuk operasi project tunggal.
Untuk menggunakan perintah Google Cloud CLI dalam dokumen ini, siapkan lingkungan gcloud CLI Anda.

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk mendaftarkan agen secara manual di Agent Registry, minta administrator untuk memberi Anda peran IAM berikut pada project tata kelola tempat Agent Registry diaktifkan:

Untuk mendaftarkan agen di Agent Registry: Agent Registry API Editor (roles/agentregistry.editor)
Untuk pendaftaran lintas project, guna mengakses metadata agen di project Google Cloud lain: Agent Registry API Viewer (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 mematuhi A2A

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

Ikuti langkah-langkah berikut untuk mendaftarkan agen:

Konsol

Di konsol Google Cloud , buka Agent Registry:

Buka Agent Registry
Dari pemilih project, pilih project Google Cloud tempat Anda menyiapkan Agent Registry.
Pilih tab Agen.
Klik Tambahkan agen.
Di panel Agent details, masukkan detail berikut:
- Type: pilih A2A.
- Region: pilih lokasi geografis tempat Anda ingin mendaftarkan agen.
Pilih salah satu opsi berikut:
- Untuk mendaftarkan agen menggunakan URL Kartu Agennya, pilih tab From 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 Paste JSON, lalu tempelkan konten lengkap file agent-card.json Anda.
Klik Simpan.

gcloud

Flag spesifikasi yang Anda gunakan menentukan koleksi resource tempat komponen Anda berada. Untuk pemetaan lengkap flag ke koleksi resource, lihat [Resource layanan dan resource penemuan](/agent-registry/data-model#service-resources).

Untuk mendaftarkan agen A2A, simpan Kartu Agen agen sebagai file JSON lokal, misalnya, agent-card.json, lalu jalankan perintah gcloud agent-registry services create:

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: ID yang ingin Anda berikan ke agen, misalnya, my-support-agent. ID harus terdiri dari 4 hingga 63 karakter dan hanya boleh berisi huruf kecil, angka, dan tanda hubung.
PROJECT_ID: project ID.
REGION: region 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 kepada agen, misalnya, Support Agent.

Terraform

Blok spesifikasi yang Anda konfigurasi menentukan koleksi resource tempat komponen Anda berada. Untuk pemetaan lengkap spesifikasi ke koleksi resource, lihat [Resource layanan dan resource penemuan](/agent-registry/data-model#service-resources).

Untuk mendaftarkan agen yang mematuhi A2A, konfigurasikan 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({
      name               = "AGENT_NAME"
      description        = "A custom support agent registered using Terraform."
      version            = "1.0.0"
      capabilities       = {}
      defaultInputModes  = ["text/plain"]
      defaultOutputModes = ["text/plain"]
      supportedInterfaces = [
        {
          url             = "https://api.example.com/v1/agents/support"
          protocolBinding = "JSONRPC"
          protocolVersion = "1.0"
        }
      ]
      skills = [
        {
          id          = "customer_lookup"
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
          tags        = ["support", "customer"]
        }
      ]
    })
  }
}

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: ID unik yang ingin Anda berikan kepada agen, misalnya, my-support-agent. ID harus terdiri dari 4 hingga 63 karakter dan hanya boleh berisi huruf kecil, angka, dan tanda hubung.
DISPLAY_NAME: nama yang dapat dibaca manusia yang ingin Anda berikan kepada agen, misalnya, Support Agent.

Mendaftarkan agen REST standar

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

Untuk mendaftarkan agen jarak jauh yang tidak menerapkan spesifikasi A2A, buat resource Service non-A2A. Agent Registry menghasilkan resource Agent hanya baca untuk agen non-A2A dalam koleksi agents, termasuk URL endpoint-nya, sehingga orchestrator, agen lain, dan Agent Gateway dapat menemukan dan terhubung ke agen tersebut.

Menetapkan jenis agen ke Non-A2A di konsol Google Cloud atau menggunakan flag --agent-spec-type=no-spec dalam perintah gcloud CLI akan mendaftarkan agen AI. Jangan mendaftarkan agen tersebut secara terpisah sebagai resource Endpoint. Hanya daftarkan resource Endpoint jika Anda ingin mengatur koneksi egress agen ke REST API atau layanan web non-agen, seperti API database, API SaaS pihak ketiga, atau Google API. Untuk mengetahui petunjuk tentang cara mendaftarkan tujuan API non-agen, lihat Mendaftarkan endpoint.

Ikuti langkah-langkah berikut untuk mendaftarkan agen:

Konsol

Di konsol Google Cloud , buka Agent Registry:

Buka Agent Registry
Dari pemilih project, pilih project Google Cloud tempat Anda menyiapkan Agent Registry.
Pilih tab Agen.
Klik Tambahkan agen.
Di panel Agent details, masukkan detail berikut:
- Type: pilih Non-A2A.
- Name: masukkan nama tampilan yang dapat dibaca manusia untuk agen Anda, seperti Travel Agent.
- Description: 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

Untuk mendaftarkan agen REST standar dan menentukan URL endpoint tempat agen dihosting, jalankan perintah gcloud agent-registry services create dengan --agent-spec-type=no-spec dan flag --interfaces:

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: ID yang ingin Anda berikan ke agen, misalnya, my-remote-rest-agent. ID harus terdiri dari 4 hingga 63 karakter dan hanya boleh berisi huruf kecil, angka, dan tanda hubung.
PROJECT_ID: project ID.
REGION: region registry.
DISPLAY_NAME: nama yang dapat dibaca manusia yang ingin Anda berikan kepada agen, misalnya, Remote REST Agent.
ENDPOINT_URL: URL endpoint API agen, misalnya, https://api.example.com/v1/agents/1234.
PROTOCOL: binding protokol untuk endpoint. Nilai yang valid adalah http-json, grpc, atau jsonrpc.

Terraform

Untuk mendaftarkan agen REST standar, konfigurasikan 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: ID unik yang ingin Anda berikan kepada agen, misalnya, my-remote-rest-agent. ID harus terdiri dari 4 hingga 63 karakter dan hanya boleh berisi huruf kecil, angka, dan tanda hubung.
DISPLAY_NAME: nama yang dapat dibaca manusia yang ingin Anda berikan kepada agen, misalnya, Remote REST Agent.
ENDPOINT_URL: URL endpoint API agen, misalnya, https://api.example.com/v1/agents/1234.
PROTOCOL: binding protokol untuk endpoint. Nilai yang valid adalah HTTP_JSON, GRPC, atau JSONRPC.

Mendaftarkan agen dari project lain

Jika Anda mengonfigurasi batas pengelolaan, Registry Agen akan otomatis menggabungkan agen yang didukung dari project anggota ke dalam project pengelolaan Anda. Jika Anda tidak mengonfigurasi batas pengelolaan, atau jika agen jarak jauh berjalan pada runtime yang tidak didukung, Anda harus mendaftarkan setiap agen jarak jauh secara manual ke registry project tata kelola pusat tempat Anda ingin mengelolanya.

Misalnya, jika organisasi Anda men-deploy agen di beberapa Google Cloud project dan menggunakan Agent Gateway pusat dalam mode egress Agent-to-Anywhere untuk mengatur traffic, Anda dapat mendaftarkan agen dari project Google Cloud lain tersebut ke registry project tata kelola pusat. Untuk mengetahui informasi selengkapnya tentang arsitektur ini, lihat Contoh pola deployment.

Pertimbangan untuk pendaftaran lintas project

Sebelum Anda mendaftarkan agen secara manual 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.
Penemuan otomatis di seluruh project: penemuan lintas project didukung secara otomatis hanya saat Anda mengonfigurasi batas pengelolaan. Untuk agen kustom atau yang didaftarkan secara manual, Anda harus membuat resource Service di project pengelolaan. Tanpa batas pengelolaan, Anda hanya dapat menemukan resource dalam project tempat resource tersebut di-deploy.
Pengelolaan siklus proses: entri manual di Agent Registry tidak otomatis diperbarui atau dihapus saat terjadi perubahan di project Google Cloud lain tempat agen berjalan. Anda harus mengelola siklus proses entri ini di registry pusat saat agen jarak jauh diubah atau dihapus.
Hanya mode egress: tata kelola lintas project dengan Agent Gateway hanya didukung untuk gateway egress Agent-to-Anywhere. Gateway ingress Klien ke Agen mengharuskan agen dan gateway berada dalam project yang sama.

Mendaftarkan agen jarak jauh

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

Konsol

Di konsol Google Cloud , buka Agent Registry:

Buka Agent Registry
Dari pemilih project, pilih project tata kelola pusat tempat Anda ingin mendaftarkan agen.
Pilih tab Agen.
Klik Tambahkan agen.
Di panel Agent details, masukkan detail berikut:
- Type: pilih A2A jika agen jarak jauh menerapkan protokol A2A, atau Non-A2A untuk endpoint REST standar.
- Region: pilih region yang cocok dengan deployment gateway pusat dan agen jarak jauh Anda.
Berikan endpoint agen:
- Untuk agen A2A, pilih From URI dan masukkan URL Kartu Agen dari agen jarak jauh, atau pilih Paste 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, jalankan perintah gcloud agent-registry services create:

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 gcloud agent-registry services create:

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: ID untuk agen Anda di registry pusat, misalnya, remote-support-agent. ID harus terdiri dari 4 hingga 63 karakter dan hanya boleh berisi huruf kecil, angka, dan tanda hubung.
CENTRAL_PROJECT_ID: project ID dari project tata kelola pusat.
REGION: region tempat Anda mendaftarkan agen dan tempat gateway pusat dan agen jarak jauh berada, misalnya, us-central1.
DISPLAY_NAME: nama yang dapat dibaca manusia untuk agen, misalnya, Remote Support Agent.
REMOTE_ENDPOINT_URL: URL endpoint agen jarak jauh yang berjalan di project Google Cloud lain, misalnya, https://remote-support-agent-abc123.us-central1.run.app atau https://api.example.com/v1/agents/support.
PROTOCOL: binding protokol untuk endpoint. Nilai yang valid adalah http-json, grpc, atau jsonrpc.

Terraform

Untuk mendaftarkan agen jarak jauh di project tata kelola pusat 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 AGENT_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 dari project tata kelola pusat.
REGION: region tempat Anda mendaftarkan agen dan tempat gateway pusat dan agen jarak jauh berada, misalnya, us-central1.
AGENT_NAME: ID unik untuk agen Anda di registry, misalnya, remote-support-agent. ID harus terdiri dari 4 hingga 63 karakter dan hanya boleh berisi huruf kecil, angka, dan tanda hubung.
DISPLAY_NAME: nama yang dapat dibaca manusia untuk agen, misalnya, Remote Support Agent.
AGENT_PROJECT_ID: project ID dari project Google Cloud terpisah tempat agen jarak jauh dihosting.
REMOTE_ENDPOINT_URL: URL endpoint agen jarak jauh yang berjalan di project Google Cloud lain, misalnya, https://remote-support-agent-abc123.us-central1.run.app atau https://api.example.com/v1/agents/support.
PROTOCOL: binding protokol untuk endpoint. Nilai yang valid adalah HTTP_JSON, GRPC, atau JSONRPC.

Memverifikasi pendaftaran

Setelah mendaftarkan agen, pastikan Agent Registry berhasil memproses resource Service dan membuat resource Agent hanya baca yang sesuai:

Konsol

Di konsol Google Cloud , buka Agent Registry:

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

Halaman ini menampilkan daftar semua agen terdaftar dan detailnya.

gcloud

Cantumkan agen terdaftar di registry Anda dengan perintah gcloud agent-registry agents list:

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

Jika Anda memiliki beberapa agen, atau jika 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: region 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 menurut nama tampilan, Anda dapat menggunakan displayName='DISPLAY_NAME'. Untuk memfilter berdasarkan ID agen (URN) yang unik secara global, Anda dapat menggunakan agentId='urn:agent:AGENT_URN'.

Terraform

Referensi agen terdaftar Anda di 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

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

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

Jenis agen dan batasan

Sebelum memulai

Peran yang diperlukan

Mendaftarkan agen yang mematuhi A2A

Konsol

gcloud

Terraform

Mendaftarkan agen REST standar

Konsol

gcloud

Terraform

Mendaftarkan agen dari project lain

Pertimbangan untuk pendaftaran lintas project

Mendaftarkan agen jarak jauh

Konsol

gcloud

Terraform

Memverifikasi pendaftaran

Konsol

gcloud

Terraform

Langkah berikutnya

Menggunakan pendaftaran manual untuk agen