使用代理自動註冊功能

透過代理註冊資料庫，您可以設定代理在支援的 Google Cloud 執行階段自動註冊，讓開發人員和自動化調度管理代理能找到這些代理，不必手動建立註冊資料庫資源。視執行階段而定，註冊作業預設會執行，或透過選擇加入的部署步驟執行，而索引中繼資料則取決於實作通訊協定。

根據預設，自動註冊功能會探索部署在已啟用 Agent Registry 的管理專案中的支援資源。如要探索多個 Google Cloud 專案中自動註冊的代理，請設定管理邊界。如果不使用管理邊界，也可以在管理專案中手動註冊其他專案的代理。

如果遠端代理託管於外部或不支援的執行階段，您必須手動註冊代理。

自動建立索引的中繼資料

自動註冊期間，系統為代理建立索引的中繼資料和功能，取決於代理是否實作 Agent2Agent (A2A) 通訊協定：

• 採用 A2A 通訊協定的代理：Agent Registry 會查詢代理的 /.well-known/agent-card.json 代理資訊卡，自動擷取其在 Agent Registry 中宣傳的 A2A 技能和功能。
• 未實作 A2A 通訊協定的代理：Agent Registry 會註冊代理，但無法自動擷取中繼資料，例如託管代理的端點網址、代理身分和 A2A 技能。這類代理會公開標準 REST 或 gRPC 端點等。如要將功能與非 A2A 代理建立關聯，請使用手動註冊或註冊技能。

事前準備

1. 設定 Agent Registry。

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

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

從 Agent Runtime 註冊代理

如果您使用 Gemini Enterprise Agent Platform 的 Agent Runtime 開發及部署代理，系統會自動在 Agent Registry 註冊。

以下範例說明如何將實作 A2A 通訊協定的代理部署至 Agent Runtime。詳情請參閱「部署代理程式」。

# Create and deploy the agent
# This action automatically registers the agent in Agent Registry
remote_agent = client.agent_engines.create(
    agent=my_a2a_agent, # Your defined A2A object
    config={
        "display_name": "my-support-agent",
        "description": "An agent that handles support tickets.",
        "requirements": ["google-cloud-aiplatform[agent_engines,langchain]"],
    },
)

在 Agent Runtime 更新或刪除代理時，Agent Registry 會自動同步處理這些變更。

註冊內建的 Google 代理

內建的 Google 代理 (例如 Google Workspace 和 Gemini Enterprise 代理) 會自動登錄在 Agent Registry。您不需要執行任何設定或部署步驟。這些代理會擷取至儲存庫，並可供探索。

從 GKE 註冊代理

如要註冊部署在 Google Kubernetes Engine (GKE) 的代理程式，請在部署資訊清單中新增必要的 Kubernetes 標籤和註解。以下範例顯示 GKE 資訊清單，其中定義了 Kubernetes Deployment 和 Kubernetes Service，並設定為自動註冊：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-agent
  labels:
    # GKE takes this label and registers the agent to Agent Registry
    registry.gke.io/functional-type: "AGENT"
  annotations:
    # A2A protocol metadata annotation for automated Agent Card discovery
    a2a-protocol.org/agent-card: |
      card:
        endpoint: /.well-known/agent-card.json
        protocol: HTTP
        port: 8080
spec:
  selector:
    matchLabels:
      app: my-agent
  template:
    metadata:
      labels:
        app: my-agent
      annotations:
        # Agent Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
    spec:
      containers:
      - name: server
        image: gcr.io/PROJECT_ID/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
# Kubernetes Service for in-cluster network routing to the agent pod
apiVersion: v1
kind: Service
metadata:
  name: my-agent-service
  labels:
    app: my-agent
spec:
  type: ClusterIP
  ports:
  - port: 8080
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: my-agent

將 PROJECT_ID 替換為 Google Cloud 專案 ID。

如要設定及套用 Deployment 資訊清單，請按照下列步驟操作：

1. 在 Deployment 資訊清單的 metadata.labels 中，新增 registry.gke.io/functional-type: "AGENT" 標籤。這個標籤會將 Deployment 識別為 AI 代理工作負載，指示 GKE 叢集執行階段控制器檢查工作負載，並向 Agent Registry 註冊代理。

2. 在 Deployment 資訊清單的 metadata.annotations 中，提供 a2a-protocol.org/agent-card 註解，啟用代理程式 A2A 技能的自動探索功能。GKE 擷取控制器會使用這個註解查詢 A2A 代理資訊卡。

3. 在 Pod 範本的 spec.template.metadata.annotations 中，使用 iam.gke.io/spiffe-identity-type: agent-identity 註解設定代理程式身分，啟用經過驗證的通訊。

4. 將 Deployment 資訊清單套用至叢集。詳情請參閱「部署及自動調度管理 AI 代理」。

   套用 Deployment 時，GKE 叢集執行階段控制器會自動檢查工作負載容器，並查詢註解中宣告的代理卡端點。接著，系統會將代理的中繼資料和 A2A 技能，直接同步到 Agent Registry 的唯讀 Agent 探索資源。

註冊 Cloud Run 中的代理

將代理部署為 Cloud Run 服務或工作時，您可以指定 --functional-type=agent 和 --identity-type=agent-identity 旗標，自動註冊代理。--functional-type=agent 旗標會將 Cloud Run 服務或工作識別為 AI 代理，而非標準容器化工作負載，指示 Cloud Run 向 Agent Registry 註冊代理。註冊期間，Cloud Run 會自動將代理程式名稱和 AGENT 類型新增至登錄檔。

設定 --functional-type=agent 的工作負載必須指定 --identity-type=agent-identity 旗標。如果使用任何其他身分類型部署，則會發生錯誤。

如要為新的或現有的 Cloud Run 服務或工作設定自動註冊，請參閱「設定 Cloud Run 的 Gemini Enterprise Agent Platform 功能」。如要準備、容器化及部署符合 A2A 規範的代理至 Cloud Run，請參閱「將 A2A 代理部署至 Cloud Run」。

驗證註冊

您可以列出代理，確認 Agent Registry 是否已成功註冊代理：

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

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
}