身分和 ID

Agent Registry 會為註冊的代理、MCP 伺服器、端點和技能指派專屬 ID 和身分，方便您探索功能、強制執行存取權政策，以及轉送執行階段流量。瞭解各個 ID 層的運作方式，有助於在整個 AI 生態系統中設定搜尋查詢、安全性政策和網路路徑。

架構層

Agent Registry 使用四個不同的層級，識別、控管及轉送已註冊的元件：

  • Registry identifiers：邏輯、不可變更的統一資源名稱 (URN)，包括代理 ID、MCP 伺服器 ID、端點 ID 和技能 ID，用於搜尋、註冊資料庫探索和篩選。這些 URN 不會用於執行階段管理。
  • 資源名稱：Agent Registry 指派給 Service、Agent、McpServer、Endpoint 和 Skill 資源的標準Google Cloud 資源名稱，全域不重複。下游服務 (例如 Agent Gateway 路由規則、Identity-Aware Proxy (IAP) 輸出政策，以及 Identity and Access Management (IAM) 政策繫結) 會使用 Agent、McpServer、Endpoint 和 Skill 資源的資源名稱，強制執行治理政策。
  • 代理主體：可驗證的 IAM 身分，例如在Google Cloud 上執行的代理 SPIFFE ID，或外部代理的服務帳戶，用於呼叫端驗證、授權和稽核記錄。
  • 執行階段參照：儲存在 RuntimeReference 訊息中的運算或基礎架構路徑，用於拓撲查詢和輸出流量比對。

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

圖層 主要目的 管理角色 語法
註冊 ID 穩定的登錄檔探索、中繼資料標記和搜尋功能。 不可變更，且不會用於管理。
  • 代理 ID：urn:agent:IDENTIFIER
  • MCP 伺服器 ID：urn:mcp:IDENTIFIER
  • 端點 ID：urn:endpoint:IDENTIFIER
  • 技能 ID：urn:skill:IDENTIFIER
資源名稱 用於執行政策的目標資源 ID。 政策會要求提供這項資訊，Agent Gateway 路由和 IAP 繫結也會使用這項資訊。
  • 代理：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
  • 技能：projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID
代理主體 呼叫端驗證、授權和稽核記錄。 由 IAM 強制執行。
  • principal://PRINCIPAL_PATH
  • principalSet://PRINCIPAL_SET_PATH
執行階段參考資料 實體運算路由和傳出流量比對。 在拓撲查詢和 Agent Gateway 中評估，以比對網路流量。 agentregistry.googleapis.com/system/RuntimeReference 包含運算或基礎架構路徑，例如 uri: "RUNTIME_URI"

註冊資料庫 ID

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

登錄檔 ID 是邏輯 URN，專門用於登錄檔探索和中繼資料註解。與代理主體和資源名稱不同，無法用於 IAM 政策繫結、授權標頭或 Agent Gateway 路由規則。

Agent Registry 使用四種 Registry ID：

代理 ID

Agent Registry 會為所有已註冊的代理指派代理 ID (agentId)，包括內建的 Google 代理，以及自訂或外部代理。代理 ID 僅用於在 Agent Registry 中探索及篩選代理，而非用於 IAM 政策。如要在 IAM 政策中授予或限制代理的存取權，請使用其代理主體。

代理登錄檔會在擷取期間自動產生代理 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
  • Google Kubernetes Engine (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 伺服器上的工具時，系統會使用呼叫的代理主體授權存取權。

以下是 MCP 伺服器 ID 的 URN 格式：

  • Google 和 Google Cloud 遠端 MCP 伺服器： urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:SERVER_ID
  • Cloud Run 服務： urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:run:services:SERVICE_NAME
  • GKE 部署作業： urn:mcp:projects-PROJECT_NUMBER:projects:PROJECT_NUMBER:locations:REGION:container:clusters:CLUSTER_NAME:k8s:namespaces:NAMESPACE:apps:deployments:DEPLOYMENT_NAME
  • 手動註冊的 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。

技能 ID

技能 ID (skillId) 是指派給獨立技能的註冊 ID，用於在 Agent Registry 中探索及解析技能套件。

以下是技能 ID 的 URN 格式，取決於技能的發布者：

  • Google 代管發布商： urn:skill:PUBLISHER_ID:NAMESPACE:SKILL_ID
  • 私人發布者： urn:skill:projects-PROJECT_NUMBER:locations:LOCATION:private-SKILL_ID

資源名稱

無論是自動或手動註冊元件，Agent Registry 都會將標準 Google Cloud 資源名稱指派給產生的唯讀 Agent、McpServer 或 Endpoint 探索資源，或 Skill 資源。每個資源名稱都會在管理專案中，格式化為階層式 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

  • 技能： projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID

    如果是手動註冊的技能，SKILL_ID 會包含 private- 前置字元，例如 private-SKILL_ID。

    每個技能修訂版本都會使用 projects/PROJECT_NUMBER/locations/LOCATION/skills/SKILL_ID/revisions/REVISION_ID。

如果您設定管理邊界，可以在要求中指定管理專案或成員專案，藉此查詢 Agent 或 McpServer 資源。Agent Registry 會保留指派給元件的 ID (格式為 agentregistry-ID)，而您取得的資源名稱會反映要求中指定的專案。因此，資源名稱會與您在查詢中使用的專案相關聯。不過，元件的登錄檔 ID 和執行階段參照一律會保留部署資源的成員專案，且無法變更。詳情請參閱「跨管理邊界的資源名稱」。

手動註冊代理、MCP 伺服器或端點時，您會建立可寫入的 Service 資源，該資源會產生對應的唯讀 Agent、McpServer 或 Endpoint 資源。Service 資源有自己的資源名稱：

projects/PROJECT_NUMBER/locations/LOCATION/services/SERVICE_ID

您可以查詢唯讀和可寫入資源，查看資源名稱。在終端機中使用 gcloud agent-registry services describe 指令等方式查詢 Service 資源時，輸出內容也會顯示 registryResource 欄位，其中包含對應唯讀 Agent、McpServer 或 Endpoint 資源的資源名稱。詳情請參閱「管理代理」、「管理 MCP 伺服器和工具」、「管理及探索端點」和「管理技能」。

資源名稱可用於繫結政策、轉送網路流量，以及設定存取控管機制。下游管理介面 (包括 Agent Gateway 路由規則、IAP 輸出政策和 IAM 資源政策) 會根據這個資源名稱進行評估。請勿在政策繫結或路由規則中使用登錄檔 ID URN。請改用資源名稱。如需疑難排解資訊，請參閱「管理 IAP 政策時發生找不到資源實體錯誤」。

代理主體

代理主體是代理在 IAM 中的身分。您可以將角色授予代理主體，就像授予使用者或服務帳戶一樣，藉此授予或限制存取權。

在 Agent Registry 中，代理是否視為主體，取決於其執行位置：

  • 在 Google Cloud 基礎架構上執行的代理：對於 Agent Runtime 等代管執行階段，Google Cloud 會自動佈建格式為 SPIFFE ID 的代管 Workload Identity，並直接繫結至代理的運算執行階段。在 IAM 許可政策和繫結中參照這個身分時，必須使用 IAM 主體或主體集字串格式，而非 SPIFFE URI 配置。如果將 SPIFFE 字串用於 IAM 政策繫結，會傳回 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 權限直接繫結至代理執行位置。如果您在與部署位置不同的管理專案中註冊代理，或跨管理邊界探索代理，執行階段參照會指向執行基礎工作負載的成員專案。

在代理登錄中，執行階段參照會以 agentregistry.googleapis.com/system/RuntimeReference 屬性表示，其 uri 欄位包含運算或基礎架構路徑。您可以在代理程式詳細資料中查看這個僅限輸出的屬性，或使用該屬性查詢拓撲圖中的流量和關係。

後續步驟