註冊自訂 ADK 代理

您可以使用 Agent Registry 註冊以 Agent Development Kit (ADK) 建構的自訂代理，並託管於自己的基礎架構，讓其他開發人員和自動調度管理工具代理能找到這些代理。只要公開符合 Agent2Agent (A2A) 通訊協定的代理資訊卡，並手動註冊代理的端點，即可在 Agent Registry 中公開其 A2A 技能。

事前準備

  1. 設定 Agent Registry。

  2. 如果是單一專案設定，請取得已啟用 Agent Registry 的管理專案ID。如果您為多個專案設定了管理邊界，請使用管理專案的 ID 進行邊界範圍的探索和註冊，或指定成員專案 ID 進行單一專案作業。

  3. 如要使用本文件中的 Google Cloud CLI 指令，請設定 gcloud CLI 環境。

必要的角色

如要取得在 Agent Registry 註冊自訂 ADK 代理所需的權限，請要求管理員在已啟用 Agent Registry 的管理專案中，授予您 Agent Registry API 編輯者 (roles/agentregistry.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

Agent Card 端點

為讓 Agent Registry 為自訂代理的功能建立索引，代理必須使用 Agent2Agent (A2A) 通訊協定，公開中繼資料和可用的 A2A 技能。

A2A 規格要求代理在特定端點 (通常是 /.well-known/agent-card.json) 提供代理資訊卡，也就是說明代理身分和工具的 JSON 文件。

使用 ADK 的特定 A2A 伺服器外掛程式或模組註冊代理時，框架會根據您在程式碼中提供的 Agent 定義和 tools，自動產生並提供這個代理資訊卡。

註冊公開的代理

將 ADK 代理部署至託管環境，並成功提供 REST 端點後，請指示 Agent Registry 探索該代理。

由於自訂部署作業需要手動註冊，因此您必須在登錄檔中建立 Service 資源。將代理產生的代理資訊卡儲存為本機 JSON 檔案，例如 agent-card.json。

使用 gcloud CLI 執行 gcloud agent-registry services create 指令來註冊代理，務必指定 a2a-agent-card 規格類型，並使用 --agent-spec-content 旗標上傳本機檔案：

gcloud agent-registry services create AGENT_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --display-name="DISPLAY_NAME" \
    --agent-spec-type=a2a-agent-card \
    --agent-spec-content=agent-card.json

規格檔案的大小上限為 10 KB。

更改下列內容：

  • AGENT_NAME：您要為代理命名的名稱，例如 my-custom-agent。
  • PROJECT_ID：專案 ID。
  • LOCATION：登錄檔位置或區域。
  • DISPLAY_NAME：代理的人類可讀名稱。

建立 Service 資源後，代理登錄檔會剖析代理資訊卡、建立唯讀 Agent 資源，並為 ADK Python 程式碼中定義的 A2A 技能建立索引，方便其他開發人員搜尋。