Mendaftarkan endpoint

Di Agent Registry, endpoint mewakili URL target, biasanya REST API, yang diakses oleh agen Anda. Dengan mendaftarkan tujuan ini sebagai komponen agentik terkelola dalam Agent Registry, Anda dapat mengontrol secara terpusat endpoint eksternal mana yang dapat terhubung dengan fleet agen Anda.

Dokumen ini menjelaskan cara mendaftarkan endpoint eksternal secara eksplisit di registry.

Sebelum memulai

Sebelum memulai, siapkan Agent Registry. Anda memerlukan project ID Anda 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 endpoint di Agent Registry, minta administrator untuk memberi Anda peran IAM Editor API Agent Registry (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 endpoint

Karena endpoint adalah tujuan eksternal kustom, gunakan pendaftaran manual untuk menambahkannya ke Agent Registry:

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 Endpoints.

  4. Klik Add endpoint.

  5. Di panel Endpoint details, masukkan nama tampilan, deskripsi, region geografis, dan URL tujuan.

    Secara opsional, klik Test connection di panel ini untuk menguji koneksi Anda ke URL tujuan.

  6. Klik Save.

gcloud

Anda membuat resource Service dengan endpoint-spec-type no-spec.

Daftarkan endpoint dan tentukan detail koneksi antarmukanya:

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

Ganti kode berikut:

  • ENDPOINT_NAME: Nama yang ingin Anda berikan ke endpoint, misalnya, my-external-api.
  • PROJECT_ID: Project ID.
  • REGION: Region registry.
  • DISPLAY_NAME: Nama endpoint yang dapat dibaca manusia.
  • ENDPOINT_URL: URL target, misalnya, https://api.example.com/v1/data.
  • PROTOCOL: Binding protokol untuk antarmuka. Nilai yang valid adalah http-json, grpc, atau jsonrpc.

Setelah resource Service dibuat, Agent Registry akan otomatis membuat resource Endpoint hanya baca di sisi konsumen yang dapat ditemukan dan digunakan oleh agen dan pengatur untuk ditemukan dan digunakan.

Terraform

Untuk mendaftarkan endpoint eksternal, konfigurasi resource google_agent_registry_service dengan blok endpoint_spec:

resource "google_agent_registry_service" "endpoint" {
  location     = "REGION"
  service_id   = "ENDPOINT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "An external REST API registered using Terraform."

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

  endpoint_spec {
    type = "NO_SPEC"
  }
}

output "endpoint_resource_name" {
  description = "The generated read-only Endpoint resource name."
  value       = google_agent_registry_service.endpoint.registry_resource
}

Ganti kode berikut:

  • REGION: Region registry.
  • ENDPOINT_NAME: Nama unik yang ingin Anda berikan ke endpoint, misalnya, my-external-api.
  • DISPLAY_NAME: Nama endpoint yang dapat dibaca manusia.
  • ENDPOINT_URL: URL target, misalnya, https://api.example.com/v1/data.
  • PROTOCOL: Binding protokol untuk antarmuka. Nilai yang valid adalah HTTP_JSON, GRPC, atau JSONRPC.

Mendaftarkan endpoint Google API gabungan

Dalam arsitektur lintas project, project tata kelola pusat menghosting infrastruktur bersama seperti Agent Registry dan Agent Gateway, dan project beban kerja individual menghosting instance komputasi agen.

Saat Anda merutekan traffic agen melalui Agent Gateway dalam mode keluar, traffic jaringan keluar akan diblokir secara default. Agar agen dalam project beban kerja dapat berkomunikasi dengan essential Google Cloud APIs, Anda dapat mengelompokkan beberapa antarmuka API ke dalam satu endpoint gabungan Service di project tata kelola pusat.

Mengelompokkan antarmuka ke dalam satu endpoint akan menyederhanakan administrasi kebijakan dengan memungkinkan Anda mengelola satu binding kebijakan IAP untuk seluruh rangkaian Google API inti.

Ikuti langkah-langkah berikut untuk mendaftarkan endpoint Google API gabungan:

gcloud

Daftarkan endpoint dengan beberapa URL antarmuka di project tata kelola pusat:

gcloud agent-registry services create SERVICE_NAME \
  --project=CENTRAL_PROJECT_ID \
  --location=REGION \
  --display-name="DISPLAY_NAME" \
  --description="DESCRIPTION" \
  --endpoint-spec-type=no-spec \
  --interfaces=protocolBinding=jsonrpc,url=API_URL \
  --interfaces=protocolBinding=jsonrpc,url=ADDITIONAL_API_URL

Ganti kode berikut:

  • SERVICE_NAME: ID untuk layanan, misalnya, core-gapi-services.
  • CENTRAL_PROJECT_ID: Project ID project tata kelola pusat yang menghosting Agent Registry dan Agent Gateway.
  • REGION: Region tempat gateway dan registry Anda berada.
  • DISPLAY_NAME: Nama yang dapat dibaca manusia, misalnya, Core Google APIs.
  • DESCRIPTION: Deskripsi singkat, misalnya, Essential Google APIs for agent operations.
  • API_URL: URL Google API utama, seperti https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: Ulangi flag --interfaces untuk setiap URL atau varian Google API tambahan yang diperlukan oleh agen Anda, seperti https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com, atau varian regional dan mTLS seperti https://telemetry.mtls.googleapis.com.

Terraform

Untuk mendaftarkan endpoint Google API gabungan menggunakan Terraform, tentukan resource google_agent_registry_service dengan beberapa blok interfaces:

resource "google_agent_registry_service" "core_gapi_services" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "SERVICE_NAME"
  display_name = "DISPLAY_NAME"
  description  = "DESCRIPTION"

  endpoint_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "API_URL"
    protocol_binding = "JSONRPC"
  }

  # Add an interfaces block for each additional Google API URL
  interfaces {
    url              = "ADDITIONAL_API_URL"
    protocol_binding = "JSONRPC"
  }
}

Ganti kode berikut:

  • CENTRAL_PROJECT_ID: Project ID project tata kelola pusat.
  • REGION: Region registry.
  • SERVICE_NAME: ID layanan.
  • DISPLAY_NAME: Nama yang dapat dibaca manusia.
  • DESCRIPTION: Deskripsi layanan.
  • API_URL: URL Google API utama, seperti https://telemetry.googleapis.com.
  • ADDITIONAL_API_URL: Ulangi blok interfaces untuk setiap URL atau varian Google API tambahan yang diperlukan oleh agen Anda, seperti https://cloudresourcemanager.googleapis.com, https://iamcredentials.googleapis.com, https://agentregistry.googleapis.com, atau varian regional dan mTLS seperti https://telemetry.mtls.googleapis.com.

Langkah berikutnya