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

使用手動註冊

如果代理託管於Google Cloud外部、在不支援的執行階段執行，或部署在不同 Google Cloud 專案中，您必須在 Agent Registry 中手動註冊。本文說明如何在 Agent Registry 中手動註冊代理程式。

警告：us 和 eu 多區域位置不支援這項功能。你必須使用支援的區域或 global 位置。詳情請參閱「代理程式登錄位置」。

事前準備

開始之前，請先設定代理程式登錄。您需要專案 ID 才能執行這些工作。

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

必要的角色

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

如要在 Agent Registry 中註冊代理程式，請使用「Agent Registry API 編輯者」 (roles/agentregistry.editor)。
如要跨專案註冊，請執行下列操作，存取遠端專案中的代理程式中繼資料： Agent Registry API 檢視者 (roles/agentregistry.viewer)

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

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

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

註冊符合 A2A 規範的代理

如果遠端代理程式實作 Agent2Agent (A2A) 規格，請將 Agent Registry 直接指向代理程式的 agent-card.json 酬載。登錄檔會自動同步代理資訊卡，並為代理可用的 A2A 技能建立索引，以供探索。

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

控制台

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

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

gcloud

如要註冊 A2A 代理，請將代理的代理資訊卡儲存為本機 JSON 檔案 (例如 agent-card.json)，然後執行下列操作：

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：您要為代理程式指定的名稱，例如 my-support-agent。
PROJECT_ID：專案 ID。
REGION：要註冊代理程式的區域。如果不想使用特定區域，請使用 global 值。
DISPLAY_NAME：您要為代理程式指定的使用者可讀名稱，例如 Support Agent。

Terraform

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

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({
      schemaVersion = "v1"
      displayName   = "DISPLAY_NAME"
      description   = "A custom support agent registered using Terraform."
      skills = [
        {
          name        = "customer_lookup"
          description = "Looks up customer info by email address."
        }
      ]
    })
  }
}

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

更改下列內容：

REGION：您註冊代理程式的區域。
AGENT_NAME：您要為代理程式指定的專屬名稱，例如 my-support-agent。
DISPLAY_NAME：您要為代理程式指定的使用者可讀名稱，例如 Support Agent。

註冊標準 REST 代理程式

標準 REST 代理程式可依名稱和說明探索，但除非採用 A2A 協定，否則不會有可搜尋的 A2A 技能。

如要註冊未實作 A2A 規格的遠端代理程式 (例如標準 REST 或 SaaS API 端點)，Agent Registry API 會建立不含代理程式通訊協定規格的 Service 資源。

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

控制台

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

前往 Agent Registry
在專案選擇工具中，選取 Google Cloud 您設定代理程式登錄的專案。
選取「代理人」分頁。
按一下「新增代理」。
在「代理程式詳細資料」面板中，輸入下列詳細資料：
- 類型：選取「非 A2A」。
- 名稱：輸入代理程式的顯示名稱，例如 Travel Agent。
- 說明：輸入代理程式功能的說明，例如 A test agent that plans travel itineraries.
- 區域：選取要註冊代理程式的地理位置。
- 端點：輸入代管代理程式的端點。
按一下 [儲存]。

gcloud

您可以選擇使用 --interfaces 旗標提供定義的 HTTP/JSON 端點介面，讓登錄檔與代理程式建立連線。

如要註冊標準 REST 代理程式，請按照下列步驟操作：

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：您要為代理程式指定的名稱，例如 my-remote-rest-agent。
PROJECT_ID：專案 ID。
REGION：登錄檔區域。
DISPLAY_NAME：您要為代理程式指定的使用者可讀名稱，例如 Remote REST Agent。
ENDPOINT_URL：代理程式的 API 端點網址，例如 https://api.remote-service.com/v1/agents/1234。
PROTOCOL：端點的通訊協定繫結。有效值為 http-json、grpc 或 jsonrpc。

Terraform

如要註冊標準 REST 代理程式，請將 google_agent_registry_service 資源的 agent_spec 設為 NO_SPECtype，並定義端點介面連線：

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：您要為代理程式指定的專屬名稱，例如 my-remote-rest-agent。
DISPLAY_NAME：您要為代理程式指定的使用者可讀名稱，例如 Remote REST Agent。
ENDPOINT_URL：代理程式的 API 端點網址，例如 https://api.remote-service.com/v1/agents/1234。
PROTOCOL：端點的通訊協定繫結。有效值為 HTTP_JSON、GRPC 或 JSONRPC。

註冊其他專案的代理

如果貴機構在多個 Google Cloud專案中部署代理程式，並使用中央代理閘道控管輸出流量，您可以將輻射或工作負載專案中的代理程式註冊到中央代理程式登錄目錄。

由於自動註冊功能只會探索在同一專案中建立的資源，因此您必須手動將每個遠端代理程式註冊到中央控管專案的登錄檔。

跨專案註冊的注意事項

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

相容位置：Agent Registry 執行個體、Agent Gateway 和代理端點必須位於相同地理區域或 global 位置。
自動探索限制：系統不支援自動跨專案探索。您必須手動註冊每個遠端代理程式。
生命週期管理：遠端專案發生變更時，代理程式登錄中的手動項目不會自動更新或刪除。修改或移除遠端代理程式時，您必須在中央登錄檔中管理這些項目的生命週期。
僅限輸出模式：只有代理程式到任何位置 (輸出) 的閘道，才支援使用 Agent Gateway 進行跨專案管理。如要使用「用戶端到代理程式」的 Ingress 閘道，代理程式和閘道必須位於相同專案。

註冊遠端代理程式

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

控制台

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

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

gcloud

A2A 代理：如要使用 gcloud CLI 註冊其他專案的 A2A 代理，請在中央控管專案中執行下列指令：

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 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：中央登錄檔中的代理程式名稱，例如 remote-support-agent。
CENTRAL_PROJECT_ID：中央控管專案的專案 ID。
REGION：您註冊代理程式的區域。
DISPLAY_NAME：代理程式的易讀名稱，例如 Remote Support Agent。
REMOTE_ENDPOINT_URL：在遠端專案中執行的代理程式端點網址，例如 https://<var>AGENT_SERVICE_NAME</var>-<var>HASH</var>.<var>REGION</var>.run.app。
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 REMOTE_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：您註冊代理程式的區域。
AGENT_NAME：登錄檔中代理程式的專屬名稱，例如 remote-support-agent。
DISPLAY_NAME：代理程式的易讀名稱，例如 Remote Support Agent。
REMOTE_PROJECT_ID：代理程式代管所在的專案 ID。
REMOTE_ENDPOINT_URL：在遠端專案中執行的代理程式端點網址。
PROTOCOL：端點的通訊協定繫結。有效值為 HTTP_JSON、GRPC 或 JSONRPC。

驗證註冊

註冊服務專員後，請確認服務專員登錄服務已成功處理 Service，並建立對應的 Agent 資源：

控制台

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

前往 Agent Registry
在專案選擇工具中，選取 Google Cloud 您設定代理程式登錄的專案。
選取「代理人」分頁。

這個頁面會顯示所有已註冊代理程式的清單和詳細資料。

gcloud

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'。如要依全域不重複的識別碼 (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

後續步驟

使用手動註冊