設定 Agent Registry

如要在 Agent Registry 註冊及探索 AI 代理、Model Context Protocol (MCP) 伺服器、獨立技能和端點，必須在 Google Cloud 專案啟用 Agent Registry API。啟用 Agent Registry 的專案會做為管理專案。

您可以設定管理邊界，並以中央管理專案做為治理專案，在單一治理專案或多個專案中設定代理儲存庫。

事前準備

在單一專案或多個專案中設定 Agent Registry：

必要的角色

如要取得設定 Agent Registry 所需的權限，請要求管理員在 Google Cloud 專案中授予您下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

設定 Google Cloud CLI 環境

如要使用 gcloud CLI 執行 Agent Registry，請按照下列步驟操作：

  1. 在 Google Cloud 控制台啟用 Cloud Shell。

    啟用 Cloud Shell

    Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

  2. 使用 gcloud components update 指令，將 gcloud CLI 更新至最新版本：

    gcloud components update

  3. 如要使用預先發布版功能，請使用 gcloud components install 指令安裝 alpha 元件：

    gcloud components install alpha

啟用 Agent Registry API

  • 單一專案：在管理專案啟用 Agent Registry API。啟用 API 並授予權限後，即可開始在該專案中註冊及探索代理。您不需要設定管理邊界。
  • 多項專案 (管理邊界)：在執行設定指令的專案中啟用 Resource Manager API。當您為多項專案設定管理邊界並建立功能設定時，Resource Manager 會自動在管理專案啟用 Agent Registry API。

使用專案 ID 啟用 API：

控制台

如果是單一專案，請在專案中啟用 Agent Registry API：

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

如有多項專案 (管理邊界)，請在用於設定的專案上啟用 Resource Manager API：

啟用 API 所需的角色

您必須具備 serviceusage.services.enable 權限，才能啟用 API。如果您建立了專案，可能已透過擁有者角色 (roles/owner) 取得這項權限。否則，您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。

啟用 API

gcloud

  • 如果是單一專案，請使用 gcloud services enable 指令，在專案中啟用 Agent Registry API：

    gcloud services enable agentregistry.googleapis.com \
    --project=PROJECT_ID

  • 如有多項專案 (管理邊界)，請在用於設定的專案上啟用 Resource Manager API：

    gcloud services enable cloudresourcemanager.googleapis.com \
    --project=PROJECT_ID

將 PROJECT_ID 替換為獨立管理專案的專案 ID，或要用做管理邊界管理專案的專案。

為多項專案設定管理邊界

如要在多個 Google Cloud 專案中使用 Agent Registry，請設定管理邊界。管理邊界會將一或多個 Google Cloud 成員專案分組至中央管理專案，做為治理專案，以便您探索及管理各專案的 AI 代理、MCP 伺服器和工具。

您可以在 Resource Manager 中定義管理邊界。如需逐步說明，請參閱 Resource Manager 說明文件中的「設定管理界限」。

如要瞭解 BoundaryConfig、Boundary 和 CapabilityConfig 資源如何搭配運作，請參閱跨專案邊界。

使用 agent-management 建立 CapabilityConfig 資源時，Resource Manager 會自動在管理專案啟用 agentregistry.googleapis.com。建立管理界線後：

  1. 如需在個別成員專案中執行本機作業，請在這些成員專案中啟用 Agent Registry API。
  2. 將必要的角色和權限授予管理專案中的使用者和服務帳戶。

在管理專案的某個位置列出或搜尋代理或 MCP 伺服器時，Agent Registry 會匯總並傳回該位置中，邊界內所有成員專案自動探索到的資源，以及直接在管理專案該位置建立的任何已註冊 Service 資源。每個傳回的資源名稱都會保留元件 ID，並使用要求中指定的專案。

授予權限

如要查看及管理代理登錄檔中的資源，您必須授予使用者適當的 Identity and Access Management (IAM) 權限。

請將下列一或多個 Agent Registry 角色授予使用者：

  • Agent Registry API 檢視者 (roles/agentregistry.viewer)：查看及搜尋代理、MCP 伺服器、工具、獨立技能、技能修訂版本、發布者、端點和繫結。
  • Agent Registry API 編輯者 (roles/agentregistry.editor)：查看及編輯 Agent Registry 資源，包括註冊、更新和刪除代理、MCP 伺服器、工具、端點、獨立技能和技能修訂版本。
  • Agent Registry API 管理員 (roles/agentregistry.admin)：可對 Agent Registry 資源執行所有動作，包括註冊及管理代理、MCP 伺服器、工具、端點、獨立技能、技能修訂版本、繫結和技能 IAM 政策。
  • Agent Registry 使用者 (roles/agentregistry.user)：可查看所有 Agent Registry 資源，以及建立、更新和刪除獨立技能和技能修訂版本，但無法編輯代理、MCP 伺服器或端點。

如要瞭解如何授予專案的 IAM 角色，請參閱「管理專案、資料夾和組織的存取權」。

變更 Agent Registry 專案

如要變更使用 Agent Registry 的專案，並移除舊專案的依附元件，請在舊專案中停用 Agent Registry API。在舊專案中停用 Agent Registry API 後，即可在其他專案中啟用。您的資料不會遷移，您必須在這個新專案中重新建立資源。

停用 Agent Registry API

如果不想再使用 Agent Registry，請在專案中停用 Agent Registry API：

控制台

  1. 前往 Google Cloud 控制台的 Agent Registry API 管理頁面：

    前往 Agent Registry API

  2. 在專案挑選器中，選取您設定 Agent Registry 的 Google Cloud 專案。

  3. 點選「停用 API」。

  4. 在確認對話方塊中，點選「停用」。

gcloud

使用 gcloud services disable 指令，在專案中停用 Agent Registry API：

gcloud services disable agentregistry.googleapis.com \
    --project=PROJECT_ID

將 PROJECT_ID 替換為專案 ID。

後續步驟