使用自動註冊功能

Agent Registry 可以註冊託管於支援 Google Cloud 執行階段的代理，不需要您手動呼叫 Agent Registry API。視執行階段而定，這項註冊程序會自動執行，或是在部署期間需要選擇加入設定步驟。

本文說明如何在支援的執行階段中，為代理程式啟用探索功能。如果您在外部或不支援的執行階段中代管代理程式，請參閱「使用手動註冊」。

在代理程式註冊期間擷取的中繼資料和技能取決於代理程式的通訊協定。詳情請參閱「註冊代理程式」。

事前準備

註冊代理程式前，請先設定代理程式登錄檔。 您需要專案 ID 才能驗證註冊。

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

從 Agent Runtime 註冊代理

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

Agent2Agent (A2A) 通訊協定是開放標準，可讓代理聲明自身功能和身分。以下範例說明如何將實作 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 代理

系統會自動在 Agent Registry 中註冊內建的 Google 代理，例如 Google Workspace 和 Gemini Enterprise 代理。您不需要執行任何設定或部署步驟。這些代理程式會擷取並在登錄檔中探索。

從 GKE 註冊代理

如要註冊部署在 Google Kubernetes Engine (GKE) 的代理程式，請在部署作業中新增 registry.gke.io/functional-type: "AGENT" 標籤。這個標籤會將部署作業識別為 AI 代理程式，讓代理程式登錄檔執行內省掃描。

如要啟用自動探索代理程式技能，您也必須提供 a2a-protocol.org/agent-card 註解。擷取控制器會使用這項註解查詢 A2A 代理資訊卡。此外，請使用 iam.gke.io/spiffe-identity-type: agent-identity 註解設定 Workload Identity，協助啟用安全驗證通訊。

下列範例顯示使用這些設定的 GKE 代理程式部署資訊清單。詳情請參閱「部署及協調 AI 代理程式」。

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:
      annotations:
        # Workload Identity annotation for identity and access management
        iam.gke.io/spiffe-identity-type: agent-identity
      labels:
        app: my-agent
    spec:
      containers:
      - name: server
        image: gcr.io/my-project/my-agent:1.0.0
        ports:
        - containerPort: 8080
        env:
        - name: PORT
          value: "8080"
---
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

套用部署作業後，GKE 叢集會自動嘗試從代理程式擷取中繼資料，並直接同步到 Agent Registry 資料模型。

驗證註冊

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

控制台

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

    前往 Agent Registry

  2. 在專案選擇工具中，選取 Google Cloud 您設定代理程式登錄的專案。

  3. 選取「代理人」分頁。

    這個頁面會列出所有已註冊的代理程式及其詳細資料，例如名稱、ID、說明、執行階段和位置。

  4. 依據代理程式位置或執行階段資源篩選清單：

    • 如要依地點篩選，請按一下「地點」選單，選取要篩選的地點，然後按一下「套用」。
    • 如要依執行階段篩選，請點選「執行階段」選單，選取要篩選的執行階段，然後點選「套用」。

    頁面會顯示已根據所選條件篩選的註冊代理人清單。

gcloud

您可以依代理程式的中繼資料篩選清單。請確認您已設定 Agent Registry 的 Google Cloud CLI 環境，然後執行下列指令：

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

更改下列內容：

  • PROJECT_ID：專案 ID。
  • REGION：登錄檔區域。
  • FILTER_EXPRESSION：要篩選的代理程式篩選運算式。舉例來說，如要依顯示名稱篩選，可以使用 displayName='DISPLAY_NAME'。如要依全域不重複的識別碼 (URN) 篩選，可以使用 agentId='urn:agent:AGENT_URN'。

內建 Google 代理程式使用的 URN 格式取決於代理程式的部署位置。舉例來說，您可以透過篩選器，找出 googleapis.com 發布者為 --filter="agentId:'urn:agent:googleapis.com:*'" 的內建 Google Workspace 代理程式。

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：代理程式的顯示名稱，方便使用者辨識。