Identitas dan ID

Untuk mendaftarkan dan mengelola agen di Agent Registry, Anda bekerja di empat lapisan arsitektur. Setiap lapisan menggunakan mekanisme penamaan, identitas, atau perutean tertentu:

  • ID pendaftaran (ID agen, ID server MCP, dan ID endpoint): Nama Resource Seragam (URN) logis dan tidak dapat diubah yang digunakan untuk pelacakan inventaris, penemuan pendaftaran, dan pemfilteran. URN ini tidak digunakan untuk tata kelola runtime.
  • Nama resource: Nama resourceGoogle Cloud unik secara global standar (registryResource atau name) yang dibuat saat pendaftaran dan digunakan oleh aturan rute Agent Gateway, kebijakan keluar Identity-Aware Proxy (IAP), dan binding kebijakan Identity and Access Management (IAM).
  • Principal agen: Identitas IAM yang dapat diverifikasi, seperti ID SPIFFE untuk agen yang berjalan di Google Cloud atau akun layanan untuk agen eksternal, yang digunakan untuk autentikasi, otorisasi, dan logging audit pemanggil.
  • Referensi runtime: Jalur komputasi atau infrastruktur (RuntimeReference) yang digunakan untuk kueri topologi dan pencocokan traffic keluar.

Tabel berikut membandingkan setiap lapisan, tujuan utamanya, peran tata kelola hilir, dan sintaksisnya:

Lapisan Tujuan utama Peran tata kelola Sintaksis
ID pendaftaran
(ID Agen, server MCP, atau endpoint)		 Penemuan, pemberian tag metadata, dan penelusuran registri yang stabil. Tidak dapat diubah dan tidak digunakan untuk tata kelola.
  • urn:agent:IDENTIFIER
  • urn:mcp:IDENTIFIER
  • urn:endpoint:IDENTIFIER
Nama resource Identifikasi resource target untuk penerapan kebijakan. Diperlukan oleh kebijakan dan digunakan oleh rute Agent Gateway dan binding IAP.
  • projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID
  • projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID
  • projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID
Akun utama agen Autentikasi pemanggil, otorisasi, dan logging audit. Diterapkan oleh IAM.
  • principal://PRINCIPAL_PATH
  • principalSet://PRINCIPAL_SET_PATH
Referensi runtime Pencocokan traffic keluar dan perutean komputasi fisik. Dievaluasi dalam kueri topologi dan di Agent Gateway agar sesuai dengan traffic jaringan. agentregistry.googleapis.com/system/RuntimeReference yang berisi jalur komputasi atau infrastruktur sebagai uri: "RUNTIME_URI"

ID pendaftaran

ID registry adalah Nama Resource Seragam (URN) unik global yang tidak dapat diubah yang ditetapkan Agent Registry ke komponen terdaftar. URN ini memberikan referensi yang stabil bagi konsumen dan agen orkestrator untuk menemukan, memfilter, dan menelusuri komponen di Agent Registry, yang tetap konstan terlepas dari migrasi infrastruktur atau update kode yang mendasarinya.

ID registri adalah URN logis yang digunakan secara eksklusif untuk penemuan registri dan anotasi metadata. ID ini berbeda dengan identitas keamanan runtime dan nama resource, serta tidak dapat digunakan dalam binding kebijakan IAM, header otorisasi, atau aturan rute Agent Gateway.

Agent Registry menggunakan tiga jenis ID pendaftaran:

ID agen

Agent Registry menetapkan ID agen (agentId) ke semua agen terdaftar, termasuk agen yang dikelola Google dan agen eksternal atau kustom. Untuk mengelola komunikasi yang aman dan diatur oleh kebijakan untuk agen, gunakan principal agen, bukan ID agennya.

Agent Registry otomatis membuat ID agen selama penyerapan. Struktur URN yang tepat bergantung pada lingkungan komputasi tempat agen di-deploy:

  • Agent Runtime di Gemini Enterprise Agent Platform: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID
  • Layanan Cloud Run: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME
  • Tugas Cloud Run: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME
  • Deployment GKE: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:container:clusters:CLUSTER_NAME:k8s:namespaces:NAMESPACE:apps:deployments:DEPLOYMENT_NAME
  • Gemini Enterprise: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:global:discoveryengine:collections:default_collection:engines:ENGINE_ID:assistants:default_assistant:agents:AGENT_ID
  • Google Workspace: urn:agent:googleapis.com:locations:global:workspaceagent:workspaceagent--a2a
  • Agen yang terdaftar secara manual: urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:AGENT_ID

ID server MCP

ID server MCP (mcpServerId) adalah ID pendaftaran yang digunakan untuk menemukan server MCP dan alatnya di Agent Registry.

Server MCP hanya merespons permintaan dan tidak memiliki pokok IAM. Saat agen memanggil alat di server MCP, akses akan diizinkan menggunakan principal agen yang memanggil.

Format URN bergantung pada apakah server adalah layanan yang dikelola Google atau server terdaftar eksternal:

  • Server MCP Google dan Google Cloud jarak jauh: urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID
  • Server MCP yang terdaftar secara manual: urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID

ID endpoint

ID endpoint (endpointId) adalah ID registri yang ditetapkan ke endpoint terdaftar untuk menemukan tujuan API target.

Format URN untuk endpoint yang didaftarkan secara manual adalah urn:endpoint:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:ENDPOINT_ID.

Nama resource

Saat Anda mendaftarkan agen, server MCP, atau endpoint di Agent Registry, proses pendaftaran akan menghasilkan Google Cloud nama resource standar yang diformat sebagai jalur URI hierarkis:

  • Agen: projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID
  • Server MCP: projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID
  • Endpoints: projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID

Saat Anda membuat atau memeriksa resource Service yang dapat ditulis, misalnya, dengan menjalankan gcloud agent-registry services describe, nama resource ini akan ditampilkan di kolom registryResource hanya output. Saat Anda membuat kueri atau memeriksa resource Agent, McpServer, atau Endpoint hanya baca yang dihasilkan secara langsung, misalnya, dengan menggunakan perintah gcloud agent-registry agents describe, nama resource ini akan ditampilkan di kolom name standar.

Nama resource dapat digunakan untuk mengikat kebijakan, merutekan traffic jaringan, dan mengonfigurasi kontrol akses. Permukaan tata kelola hilir, termasuk aturan rute Agent Gateway, kebijakan keluar IAP, dan kebijakan resource IAM, dievaluasi berdasarkan nama resource ini. URN tidak menerima URN dari ID pendaftaran, seperti ID agen, ID server MCP, atau ID endpoint.

Jika Anda menggunakan URN ID registri dalam pengikatan kebijakan atau aturan rute, bukan nama resource, API akan menampilkan error NOT_FOUND: Requested entity was not found.. Jika Anda mengalami error ini saat mengonfigurasi kebijakan tata kelola, periksa hal berikut:

  • Status pendaftaran: Pastikan target agen, server MCP, atau endpoint terdaftar di Agent Registry di lokasi yang diharapkan.
  • Format ID: Pastikan bahwa pengikatan kebijakan atau aturan rute Anda menentukan nama resource standar (projects/PROJECT_NUMBER/locations/LOCATION/.../agentregistry-ID), bukan URN ID registri.

Akun utama agen

Akun utama agen adalah identitas keamanan agen di IAM. Sama seperti akun pengguna atau akun layanan, agen menggunakan akun utamanya untuk memegang izin dan memanggil layanan hilir. Saat mengonfigurasi kebijakan IAM, Anda menggunakan string utama agen untuk memberikan atau membatasi akses.

Di Agent Registry, cara agen diidentifikasi sebagai akun utama bergantung pada tempat agen tersebut berjalan:

  • Agen yang berjalan di infrastruktur Google Cloud : Untuk runtime terkelola seperti Agent Runtime di Gemini Enterprise Agent Platform, Google Cloudsecara otomatis menyediakan Workload Identity terkelola yang diformat sebagai SPIFFE ID, yang terikat langsung ke runtime komputasi agen. Saat mereferensikan identitas ini dalam kebijakan dan binding IAM, Anda harus menggunakan format string set utama atau utama IAM, bukan skema URI SPIFFE. Menggunakan string SPIFFE untuk binding kebijakan IAM akan menampilkan error INVALID_ARGUMENT.
  • Agen yang berjalan di luar Google Cloud: Agen eksternal atau lokal harus menggabungkan identitas eksternal mereka melalui Workload Identity Federation atau menggunakan akun layanan standar untuk berinteraksi dengan sumber daya Google Cloud . Setelah diautentikasi, string identitas Workload Identity gabungan atau email akun layanan tersebut akan bertindak sebagai entitas agen dalam kebijakan IAM.

Untuk agen yang berjalan di Google Cloud, karena entitas agen terkelola terikat langsung ke resource komputasi runtime agen, string entitas menyertakan jalur lengkap ke resource komputasi yang mendasarinya.

IAM mendukung pengelolaan akses agen di seluruh cakupan berikut:

  • Instance mesin tunggal: Memberikan izin ke deployment agen tertentu. Misalnya, setiap instance Agent Runtime diwakili melalui satu string utama: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID
  • Cakupan project: Memberikan izin ke semua mesin penalaran yang berjalan di dalam project tertentu melalui kumpulan pokok: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
  • Cakupan di seluruh organisasi: Memberikan izin kepada semua agen di seluruh organisasi melalui karakter pengganti set akun utama: principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*

Agent Registry menampilkan prinsipal agen individual sebagai atribut hanya output saat Anda melihat detail agen.

Referensi runtime

Referensi runtime mengarah ke infrastruktur komputasi dasar tempat kode untuk agen, server MCP, atau endpoint berjalan. Misalnya, referensi runtime dapat mengarah ke mesin penalaran Agent Runtime, deployment GKE, atau layanan Cloud Run.

String utama agen mencakup jalur referensi runtime-nya, yang mengikat izin IAM secara langsung ke tempat agen berjalan. Jika Anda mendaftarkan agen di project yang berbeda dengan tempat agen di-deploy, referensi runtime akan mengarah ke project yang menghosting workload pokok.

Di Agent Registry API, referensi runtime diwakili oleh atribut agentregistry.googleapis.com/system/RuntimeReference, yang berisi jalur komputasi atau infrastruktur di kolom uri-nya. Anda dapat melihat atribut hanya output ini sebagai bagian dari detail agen atau menggunakannya untuk membuat kueri alur dan hubungan traffic dalam grafik topologi.

Langkah berikutnya