Mendaftarkan endpoint

Di Agent Registry, endpoint merepresentasikan URL target, biasanya REST API, yang diakses agen Anda. Dengan mendaftarkan tujuan ini sebagai komponen agentik terkelola dalam Agent Registry, Anda dapat mengelola secara terpusat endpoint eksternal yang dapat dihubungkan oleh kumpulan agen Anda.

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

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 Agent Registry API Editor (roles/agentregistry.editor) di 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 konsol Google Cloud , 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, wilayah geografis, dan URL tujuan.

    Jika perlu, klik Uji koneksi di panel ini untuk menguji koneksi Anda ke URL tujuan.

  6. Klik Simpan.

gcloud

Flag spesifikasi yang Anda gunakan menentukan koleksi resource tempat layanan Anda berada. Untuk mengetahui pemetaan lengkap tanda ke koleksi resource, lihat resource API.

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 registri.
  • 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 pengelola.

Terraform

Blok spesifikasi yang Anda konfigurasi, misalnya, endpoint_spec, menentukan koleksi resource tempat layanan Anda berada. Untuk mengetahui pemetaan lengkap spesifikasi ke koleksi resource, lihat resource API.

Untuk mendaftarkan endpoint eksternal, konfigurasikan 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 registri.
  • 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 API Google 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 egress, traffic jaringan keluar akan diblokir secara default. Untuk memungkinkan agen di project beban kerja berkomunikasi dengan API Google Cloud penting, Anda dapat mengelompokkan beberapa antarmuka API ke dalam satu endpoint Service gabungan di project tata kelola pusat.

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

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

gcloud

Daftarkan endpoint dengan beberapa URL antarmuka dalam 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 registri Anda berada.
  • DISPLAY_NAME: Nama yang mudah dibaca, 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 tanda --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 mTLS dan regional seperti https://telemetry.mtls.googleapis.com.

Terraform

Untuk mendaftarkan endpoint Google API komposit 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 registri.
  • 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 mTLS dan regional seperti https://telemetry.mtls.googleapis.com.

Langkah berikutnya