Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

手動註冊代理

您可以透過代理登錄檔，手動註冊符合 A2A 標準和標準 REST 代理，這些代理可託管於 Google Cloud外部、在不支援的執行階段上執行，或部署於不同 Google Cloud 專案。為這些代理建立 Service 資源後，整個 AI 生態系統就能探索其端點和功能。

註冊範圍和地點

Agent Registry 使用中央 Google Cloud管理專案。在本文件中，「遠端」一詞是指託管於管理專案或管理邊界外部的代理程式，例如位於沒有管理邊界的獨立 Google Cloud 專案、地端部署環境或外部雲端，或在不支援的執行階段上執行。自動註冊功能只會探索已啟用 Agent Registry 的管理專案中部署的支援資源，或在您設定管理邊界時跨專案探索，因此在所有其他情況下，您必須在管理專案的登錄檔中手動註冊遠端代理。

您可以在支援的區域位置、支援的多區域或 global 位置手動註冊代理。如要進一步瞭解支援的位置，請參閱「代理程式登錄檔位置」。

代理類型

您可以手動註冊兩種代理：

符合 A2A 規範的代理：採用 A2A_AGENT_CARD 類型實作 Agent2Agent (A2A) 規格的代理。登錄檔會掃描其 agent-card.json代理資訊卡端點，為其 A2A 技能建立索引。
標準 REST 代理：未實作 A2A 規格且使用 NO_SPEC 類型的遠端代理，例如公開 REST API 端點的代理。

事前準備

設定 Agent Registry。
如果是單一專案設定，請取得已啟用 Agent Registry 的管理專案 ID。如果您為多個專案設定了管理邊界，請使用管理專案的 ID 進行邊界範圍的探索和註冊，或指定成員專案 ID 進行單一專案作業。
如要使用本文件中的 Google Cloud CLI 指令，請設定 gcloud CLI 環境。

必要的角色

如要取得在 Agent Registry 手動註冊代理所需的權限，請要求管理員在已啟用 Agent Registry 的管理專案中，授予您下列 IAM 角色：

如要在 Agent Registry 註冊代理，請使用 Agent Registry API 編輯者 (roles/agentregistry.editor) 角色
如要跨專案註冊，並存取其他 Google Cloud 專案中的代理中繼資料： Agent Registry API 檢視者 (roles/agentregistry.viewer)

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

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

如果代理的端點或代理資訊卡可透過標準公開網址存取，或透過預先設定的憑證驗證，則不需要任何額外權限。

註冊符合 A2A 規範的代理

如果遠端代理實作 A2A 規格，請將代理註冊資料庫導向代理的 agent-card.json 酬載。登錄檔會自動同步代理資訊卡，並為代理可用的 A2A 技能建立索引，方便探索。

請按照下列步驟註冊代理程式：

控制台

前往 Google Cloud 控制台的「Agent Registry」：

前往 Agent Registry
在專案挑選器中，選取設定 Agent Registry 的 Google Cloud 專案。
選取「代理」分頁標籤。
按一下「新增代理」。
在「Agent details」(代理詳細資料) 面板中，輸入下列詳細資料：
- Type：選取「A2A」。
- Region (區域)：選取要註冊代理程式的地理位置。
您可以選擇下列其中一個選項：
- 如要使用代理程式資訊卡網址註冊代理程式，請選取「From URI」(來自 URI) 分頁標籤，然後在「URI」欄位中輸入有效網址。接著，按一下「Import」(匯入)，從網址取得代理資訊卡。
- 如要複製及貼上代理卡片內容，請選取「Paste JSON」(貼上 JSON) 分頁標籤，然後貼上 agent-card.json 檔案的完整內容。
按一下「儲存」。

gcloud

您使用的規格旗標會決定元件所屬的資源集合。如需旗標與資源集合的完整對應關係，請參閱「[服務資源和探索資源](/agent-registry/data-model#service-resources)」。

如要註冊 A2A 代理，請將代理的代理資訊卡儲存為本機 JSON 檔案 (例如 agent-card.json)，然後執行 gcloud agent-registry services create 指令：

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

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

更改下列內容：

AGENT_NAME：要指派給代理程式的 ID，例如 my-support-agent。ID 必須介於 4 到 63 個字元之間，且只能使用小寫英文字母、數字和連字號。
PROJECT_ID：專案 ID。
REGION：要註冊代理程式的區域。您也可以指定支援的多區域或 global。
DISPLAY_NAME：您要為代理指定的名稱，例如 Support Agent。

Terraform

您設定的規格區塊會決定元件所屬的資源集合。如需規格與資源集合的完整對應關係，請參閱「[服務資源和探索資源](/agent-registry/data-model#service-resources)」。

如要註冊符合 A2A 規範的代理，請設定 google_agent_registry_service 資源。指定 agent_spec 區塊，其中 A2A_AGENT_CARD 類型和 content 代表代理資訊卡 JSON 酬載：

resource "google_agent_registry_service" "a2a_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"

  agent_spec {
    type = "A2A_AGENT_CARD"
    content = jsonencode({
      name               = "AGENT_NAME"
      description        = "A custom support agent registered using Terraform."
      version            = "1.0.0"
      capabilities       = {}
      defaultInputModes  = ["text/plain"]
      defaultOutputModes = ["text/plain"]
      supportedInterfaces = [
        {
          url             = "https://api.example.com/v1/agents/support"
          protocolBinding = "JSONRPC"
          protocolVersion = "1.0"
        }
      ]
      skills = [
        {
          id          = "customer_lookup"
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
          tags        = ["support", "customer"]
        }
      ]
    })
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.a2a_agent.registry_resource
}

更改下列內容：

REGION：註冊代理程式的區域。
AGENT_NAME：要指派給代理的專屬 ID，例如 my-support-agent。ID 必須介於 4 到 63 個字元之間，且只能使用小寫英文字母、數字和連字號。
DISPLAY_NAME：您要為代理指定的名稱，例如 Support Agent。

註冊標準 REST 代理

標準 REST 代理可透過名稱和說明搜尋，但除非採用 A2A 通訊協定，否則不具備可搜尋的 A2A 技能。

如要註冊未實作 A2A 規格的遠端代理，請建立非 A2A Service 資源。Agent Registry 會在 agents 集合中，為非 A2A 代理產生唯讀的 Agent 資源，包括端點網址，以便協調器、其他代理和 Agent Gateway 探索及連線至該代理。

在 Google Cloud 控制台中將代理類型設為「Non-A2A」，或在 gcloud CLI 指令中使用 --agent-spec-type=no-spec 旗標，即可註冊 AI 代理。請勿將該代理個別註冊為 Endpoint 資源。只有在您想控管代理輸出連線至非代理 REST API 或網路服務 (例如資料庫 API、第三方 SaaS API 或 Google API) 時，才需要註冊 Endpoint 資源。如要瞭解如何註冊非代理 API 目的地，請參閱「註冊端點」。

請按照下列步驟註冊代理程式：

控制台

前往 Google Cloud 控制台的「Agent Registry」：

前往 Agent Registry
在專案挑選器中，選取設定 Agent Registry 的 Google Cloud 專案。
選取「代理」分頁標籤。
按一下「新增代理」。
在「Agent details」(代理詳細資料) 面板中，輸入下列詳細資料：
- Type：選取「Non-A2A」。
- 「Name」(名稱)：輸入人類可讀的代理顯示名稱，例如 Travel Agent。
- 說明：輸入代理功能說明，例如 A test agent that plans travel itineraries.
- Region (區域)：選取要註冊代理程式的地理位置。
- 端點：輸入代理的託管端點。
按一下「儲存」。

gcloud

如要註冊標準 REST 代理，並指定託管代理的端點網址，請執行 gcloud agent-registry services create 指令，並加上 --agent-spec-type=no-spec 和 --interfaces 旗標：

gcloud agent-registry services create AGENT_NAME \
    --project=PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --agent-spec-type=no-spec \
    --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL

更改下列內容：

AGENT_NAME：要指派給代理程式的 ID，例如 my-remote-rest-agent。ID 必須介於 4 到 63 個字元之間，且只能使用小寫英文字母、數字和連字號。
PROJECT_ID：專案 ID。
REGION：登錄檔區域。
DISPLAY_NAME：您要為代理指定的名稱，例如 Remote REST Agent。
ENDPOINT_URL：代理程式的 API 端點網址，例如 https://api.example.com/v1/agents/1234。
PROTOCOL：端點的通訊協定繫結。有效值為 http-json、grpc 或 jsonrpc。

Terraform

如要註冊標準 REST 代理，請設定 google_agent_registry_service 資源，並將 agent_spec 設為 NO_SPEC 類型，然後定義端點介面連線：

resource "google_agent_registry_service" "rest_agent" {
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "A standard REST agent registered using Terraform."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.rest_agent.registry_resource
}

更改下列內容：

REGION：註冊代理程式的區域。
AGENT_NAME：要指派給代理的專屬 ID，例如 my-remote-rest-agent。ID 必須介於 4 到 63 個字元之間，且只能使用小寫英文字母、數字和連字號。
DISPLAY_NAME：您要為代理指定的名稱，例如 Remote REST Agent。
ENDPOINT_URL：代理程式的 API 端點網址，例如 https://api.example.com/v1/agents/1234。
PROTOCOL：端點的通訊協定繫結。有效值為 HTTP_JSON、GRPC 或 JSONRPC。

註冊其他專案的代理

如果您設定管理邊界，Agent Registry 會自動將成員專案中支援的代理匯總至管理專案。如果您未設定管理邊界，或遠端代理程式在不支援的執行階段上執行，則必須手動將每個遠端代理程式註冊到要管理該代理程式的中央管理專案登錄檔。

舉例來說，如果貴組織在多個Google Cloud 專案中部署代理，並使用 Agent-to-Anywhere 輸出模式的中央 Agent Gateway 管理流量，則可將其他 Google Cloud 專案的代理註冊到中央管理專案的登錄檔。如要進一步瞭解這個架構，請參閱「部署模式範例」。

跨專案註冊的注意事項

手動註冊跨專案代理程式前，請先詳閱下列事項：

相容位置：Agent Registry 執行個體、Agent Gateway 和 Agent Endpoint 必須位於相同地理區域或 global 位置。
自動探索跨專案：只有在設定管理邊界時，系統才會自動支援跨專案探索。如果是自訂或手動註冊的代理，您必須在管理專案中建立 Service 資源。如果沒有管理邊界，您只能在部署資源的專案中探索資源。
生命週期管理：如果代理執行的其他Google Cloud 專案發生變更，代理註冊資料庫中的手動項目不會自動更新或刪除。修改或移除遠端代理時，您必須在中央註冊資料庫中管理這些項目的生命週期。
僅限輸出模式：只有 Agent-to-Anywhere 輸出閘道支援透過 Agent Gateway 跨專案管理。用戶端對代理程式輸入閘道，需要代理程式和閘道位於相同專案。

註冊遠端代理

如要手動註冊其他專案的代理，請按照下列步驟操作：

控制台

前往 Google Cloud 控制台的「Agent Registry」：

前往 Agent Registry
在專案挑選器中，選取要註冊代理的中央治理專案。
選取「代理」分頁標籤。
按一下「新增代理」。
在「Agent details」(代理詳細資料) 面板中，輸入下列詳細資料：
- Type：如果遠端代理實作 A2A 協定，請選取「A2A」；如果是標準 REST 端點，請選取「Non-A2A」。
- Region (區域)：選取與中央閘道和遠端代理部署作業相符的區域。
提供代理端點：
- 如果是 A2A 代理，請選取「From URI」(從 URI)，然後輸入遠端代理的代理資訊卡網址，或選取「Paste JSON」(貼上 JSON)，然後貼上 agent-card.json 內容。
- 如果是非 A2A 代理，請輸入遠端代理的端點網址。
按一下「儲存」。

gcloud

A2A 代理：如要註冊其他專案的 A2A 代理，請執行 gcloud agent-registry services create 指令：

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

REST 代理：如要從其他專案註冊標準 REST 代理，請執行 gcloud agent-registry services create 指令：

gcloud agent-registry services create AGENT_NAME \
    --project=CENTRAL_PROJECT_ID \
    --location=REGION \
    --display-name="DISPLAY_NAME" \
    --agent-spec-type=no-spec \
    --interfaces=url=REMOTE_ENDPOINT_URL,protocolBinding=PROTOCOL

更改下列內容：

AGENT_NAME：中央註冊資料庫中的代理 ID，例如 remote-support-agent。ID 必須介於 4 到 63 個半形字元之間，且只能使用小寫英文字母、數字和連字號。
CENTRAL_PROJECT_ID：中央管理專案的專案 ID。
REGION：註冊代理程式的區域，以及中央閘道和遠端代理程式所在的區域，例如 us-central1。
DISPLAY_NAME：人類可讀的代理名稱，例如 Remote Support Agent。
REMOTE_ENDPOINT_URL：在其他 Google Cloud 專案中執行的遠端代理端點網址，例如 https://remote-support-agent-abc123.us-central1.run.app 或 https://api.example.com/v1/agents/support。
PROTOCOL：端點的通訊協定繫結。有效值為 http-json、grpc 或 jsonrpc。

Terraform

如要使用 Terraform 在中央管理專案中註冊遠端代理，請設定 google_agent_registry_service 資源並指定中央專案：

resource "google_agent_registry_service" "remote_agent" {
  project      = "CENTRAL_PROJECT_ID"
  location     = "REGION"
  service_id   = "AGENT_NAME"
  display_name = "DISPLAY_NAME"
  description  = "Remote agent registered from project AGENT_PROJECT_ID."

  agent_spec {
    type = "NO_SPEC"
  }

  interfaces {
    url              = "REMOTE_ENDPOINT_URL"
    protocol_binding = "PROTOCOL"
  }
}

output "agent_resource_name" {
  description = "The generated read-only Agent resource name."
  value       = google_agent_registry_service.remote_agent.registry_resource
}

更改下列內容：

CENTRAL_PROJECT_ID：中央管理專案的專案 ID。
REGION：註冊代理程式的區域，以及中央閘道和遠端代理程式所在的區域，例如 us-central1。
AGENT_NAME：代理在登錄檔中的專屬 ID，例如 remote-support-agent。ID 必須介於 4 到 63 個字元之間，且只能使用小寫英文字母、數字和連字號。
DISPLAY_NAME：人類可讀的代理名稱，例如 Remote Support Agent。
AGENT_PROJECT_ID：託管遠端代理的獨立 Google Cloud 專案 ID。
REMOTE_ENDPOINT_URL：在其他 Google Cloud 專案中執行的遠端代理端點網址，例如 https://remote-support-agent-abc123.us-central1.run.app 或 https://api.example.com/v1/agents/support。
PROTOCOL：端點的通訊協定繫結。有效值為 HTTP_JSON、GRPC 或 JSONRPC。

驗證註冊

註冊代理後，請確認 Agent Registry 已成功處理 Service 資源，並建立對應的唯讀 Agent 資源：

控制台

前往 Google Cloud 控制台的「Agent Registry」：

前往 Agent Registry
在專案挑選器中，選取設定 Agent Registry 的 Google Cloud 專案。
選取「代理」分頁標籤。

頁面會列出所有已註冊的代理程式和詳細資料。

gcloud

使用 gcloud agent-registry agents list 指令，列出登錄檔中已註冊的代理：

gcloud agent-registry agents list \
    --project=PROJECT_ID \
    --location=REGION

如果您有多個代理程式，或想確認單一代理程式的註冊狀態，可以依據代理程式的中繼資料篩選清單：

gcloud agent-registry agents list \
    --project=PROJECT_ID \
    --location=REGION \
    --filter="FILTER_EXPRESSION"

更改下列內容：

PROJECT_ID：專案 ID。
REGION：您註冊代理程式的區域。您也可以指定支援的多區域或 global。
FILTER_EXPRESSION：要篩選的代理篩選運算式。舉例來說，如要依顯示名稱篩選，可以使用 displayName='DISPLAY_NAME'。如要依全球不重複的代理程式 ID (URN) 篩選，可以使用 agentId='urn:agent:AGENT_URN'。

Terraform

使用 google_agent_registry_agent 資料來源，在其他 Terraform 設定中參照已註冊的代理：

data "google_agent_registry_agent" "my_agent" {
  location = "REGION"
  filter = "displayName=\"DISPLAY_NAME\""
}

output "agent_urn" {
  value = data.google_agent_registry_agent.my_agent.urn
}

更改下列內容：

REGION：登錄檔區域。
DISPLAY_NAME：人類可讀的代理顯示名稱。

後續步驟

瞭解如何管理註冊代理人。
瞭解自動註冊，這是註冊部署至代管執行階段的代理程式時，建議使用的方法。

手動註冊代理 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

註冊範圍和地點

代理類型

事前準備

必要的角色

註冊符合 A2A 規範的代理

控制台

gcloud

Terraform

註冊標準 REST 代理

控制台

gcloud

Terraform

註冊其他專案的代理

跨專案註冊的注意事項

註冊遠端代理

控制台

gcloud

Terraform

驗證註冊

控制台

gcloud

Terraform

後續步驟

手動註冊代理