身分和 ID

如要在 Agent Registry 中註冊及管理代理，您需要處理四個架構層。每個層級都使用特定的命名、身分識別或路由機制：

  • 登錄 ID (代理 ID、MCP 伺服器 ID 和端點 ID)：用於追蹤目錄、探索登錄項目和篩選的邏輯不變 Uniform Resource Name (URN)。這些 URN 不會用於執行階段控管。
  • 資源名稱：標準全域不重複 Google Cloud 資源名稱 (registryResource 或 name) 註冊時產生，供 Agent Gateway 路由規則、 Identity-Aware Proxy (IAP) 輸出政策，以及 Identity and Access Management (IAM) 政策繫結使用。
  • 代理主體：可驗證的 IAM 身分，例如在Google Cloud 上執行的代理的 SPIFFE ID，或是外部代理的服務帳戶，用於呼叫端驗證、授權和稽核記錄。
  • 執行階段參照：用於拓撲查詢和輸出流量比對的運算或基礎架構路徑 (RuntimeReference)。

下表比較各層、主要用途、下游管理角色和語法：

圖層 主要目的 管理角色 語法
登錄識別碼
(代理程式、MCP 伺服器或端點識別碼)		 穩定探索登錄檔、標記中繼資料及搜尋。 不可變更，且不適用於管理。
  • urn:agent:IDENTIFIER
  • urn:mcp:IDENTIFIER
  • urn:endpoint:IDENTIFIER
資源名稱 用於強制執行政策的目標資源 ID。 政策規定必須使用，且 Agent Gateway 路由和 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
代理主體 呼叫端驗證、授權和稽核記錄。 由 IAM 強制執行。
  • principal://PRINCIPAL_PATH
  • principalSet://PRINCIPAL_SET_PATH
執行階段參考資料 實體運算路徑和傳出流量比對。 在拓撲查詢和 Agent Gateway 中評估，以比對網路流量。 agentregistry.googleapis.com/system/RuntimeReference 包含運算或基礎架構路徑，如 uri: "RUNTIME_URI"

登錄檔 ID

登錄檔 ID 是全域專屬的不可變動統一資源名稱 (URN)，由代理程式登錄檔指派給已註冊的元件。這個 URN 可為消費者和協調器代理程式提供穩定的參照，以便在 Agent Registry 中探索、篩選及搜尋元件，且無論基礎架構遷移或程式碼更新為何，這個 URN 都會保持不變。

登錄 ID 是邏輯 URN，專門用於登錄探索和中繼資料註解。這類名稱與執行階段安全身分和資源名稱不同，無法用於 IAM 政策繫結、授權標頭或 Agent Gateway 路由規則。

Agent Registry 使用三種註冊 ID：

代理程式 ID

Agent Registry 會為所有已註冊的代理指派代理 ID (agentId)，包括 Google 管理的代理，以及外部或自訂代理。如要管理代理的受政策控管安全通訊，請使用代理主體，而非代理 ID。

代理程式登錄會在擷取期間自動產生代理程式 ID。 確切的 URN 結構取決於部署代理程式的運算環境：

  • Gemini Enterprise Agent Platform 的 Agent Runtime： urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:aiplatform:reasoningEngines:AGENT_ID
  • Cloud Run 服務： urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME
  • Cloud Run 作業： urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:jobs:JOB_NAME
  • 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
  • 手動註冊的代理程式： urn:agent:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:AGENT_ID

MCP 伺服器 ID

MCP 伺服器 ID (mcpServerId) 是註冊資料庫 ID，用於在 Agent Registry 中探索 MCP 伺服器及其工具。

MCP 伺服器只會回應要求，沒有 IAM 主體。當代理在 MCP 伺服器上叫用工具時，系統會使用呼叫代理主體授權存取權。

URN 格式取決於伺服器是 Google 代管服務還是外部註冊伺服器：

  • Google 和 Google Cloud 遠端 MCP 伺服器： urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID
  • 手動註冊的 MCP 伺服器： urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:SERVER_ID

端點 ID

端點 ID (endpointId) 是指分配給已註冊端點的登錄 ID，用於探索目標 API 目的地。

手動註冊端點的 URN 格式為 urn:endpoint:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:LOCATION:agentregistry:services:ENDPOINT_ID。

資源名稱

在 Agent Registry 中註冊代理、MCP 伺服器或端點時，註冊程序會產生標準 Google Cloud 資源名稱，格式為階層式 URI 路徑：

  • 代理人： projects/PROJECT_NUMBER/locations/LOCATION/agents/agentregistry-ID
  • MCP 伺服器： projects/PROJECT_NUMBER/locations/LOCATION/mcpServers/agentregistry-ID
  • 端點： projects/PROJECT_NUMBER/locations/LOCATION/endpoints/agentregistry-ID

建立或檢查可寫入的 Service 資源時 (例如執行 gcloud agent-registry services describe)，系統會在僅供輸出的 registryResource 欄位中傳回這個資源名稱。直接查詢或檢查產生的唯讀 Agent、McpServer 或 Endpoint 資源時 (例如使用 gcloud agent-registry agents describe 指令)，系統會在標準 name 欄位中傳回這個資源名稱。

資源名稱可用於繫結政策、轉送網路流量，以及設定存取控管機制。下游控管介面 (包括代理閘道路由規則、IAP 對外政策和 IAM 資源政策) 會根據這個資源名稱進行評估。這類政策不接受登錄 ID中的 URN，例如代理 ID、MCP 伺服器 ID或端點 ID。

如果您在政策繫結或路由規則中使用登錄識別碼 URN，而不是資源名稱，API 會傳回 NOT_FOUND: Requested entity was not found. 錯誤。如果在設定控管政策時遇到這項錯誤，請確認下列事項：

  • 註冊狀態：確認目標代理、MCP 伺服器或端點已在 Agent Registry 中註冊，且位置符合預期。
  • ID 格式：確認政策繫結或路徑規則指定的是標準資源名稱 (projects/PROJECT_NUMBER/locations/LOCATION/.../agentregistry-ID)，而非登錄 ID URN。

代理主體

代理主體是 IAM 中的代理安全身分。與使用者或服務帳戶一樣，代理程式會使用主體來保留權限及呼叫下游服務。設定 IAM 政策時，您可以使用代理的主體字串授予或限制存取權。

在 Agent Registry 中，代理如何識別為主體取決於代理的執行位置：

  • 在基礎架構上執行的代理 Google Cloud ：對於代管執行階段 (例如 Gemini Enterprise Agent Platform 的 Agent Runtime)， Google Cloud會自動佈建格式為 SPIFFE ID 的代管 Workload Identity，直接繫結至代理的運算執行階段。在 IAM 允許政策和繫結中參照這個身分時，您必須使用 IAM 主體或主體集字串格式，而非 SPIFFE URI 配置。如果 IAM 政策繫結使用 SPIFFE 字串，系統會傳回 INVALID_ARGUMENT 錯誤。
  • 在外部執行的代理程式 Google Cloud：外部或地端部署代理程式必須透過 Workload Identity Federation 聯盟外部身分，或使用標準服務帳戶與 Google Cloud 資源互動。完成驗證後，該聯合 Workload Identity 字串或服務帳戶電子郵件就會在 IAM 政策中做為代理主體。

如果是透過 Google Cloud執行的代理，由於代管代理主體直接繫結至代理執行階段的運算資源，主體字串會納入該基礎運算資源的完整路徑。

IAM 支援在下列範圍內控管代理程式存取權：

  • 單一引擎執行個體：授予特定代理程式部署作業權限。舉例來說，個別 Agent Runtime 例項會以單一主體字串表示：principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/REGION/reasoningEngines/REASONING_ENGINE_ID
  • 專案範圍：透過主體組合，將權限授予在特定專案內執行的所有推論引擎： principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/attribute.platformContainer/aiplatform/projects/PROJECT_NUMBER
  • 全機構範圍：透過主體集萬用字元，將權限授予整個機構的所有代理程式： principalSet://agents.global.org-ORGANIZATION_ID.system.id.goog/*

當您查看代理程式的詳細資料時，Agent Registry 會將個別代理主體顯示為僅供輸出的屬性。

執行階段參考資料

執行階段參照會指向代理程式、MCP 伺服器或端點程式碼執行的基礎運算基礎架構。舉例來說，執行階段參照可以指向 Agent Runtime 推理引擎、GKE 部署作業或 Cloud Run 服務。

代理的主體字串包含執行階段參照路徑，可將 IAM 權限直接繫結至代理的執行位置。如果您在部署代理程式的專案以外註冊代理程式，執行階段參照會指向代管基礎工作負載的專案。

在 Agent Registry API 中，執行階段參照是由 agentregistry.googleapis.com/system/RuntimeReference 屬性代表，該屬性的 uri 欄位包含運算或基礎架構路徑。您可以查看這個僅供輸出的屬性，做為代理程式詳細資料的一部分，也可以使用這個屬性查詢拓撲圖中的流量和關係。

後續步驟