使用自動註冊功能

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

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

註冊期間為代理建立索引的中繼資料和功能，取決於代理是否實作 Agent2Agent (A2A) 通訊協定。詳情請參閱「註冊代理程式」。

事前準備

註冊代理程式前，請先設定 Agent Registry。您需要專案 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 代理程式工作負載，指示 GKE 叢集執行階段控制器執行叢集內省掃描，並向 Agent Registry 註冊代理程式。

如要啟用自動探索代理程式技能功能，您也必須提供 a2a-protocol.org/agent-card 註解。GKE 擷取控制器會使用這項註解查詢 A2A 代理資訊卡。

以下範例顯示使用這些設定的 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:
      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 Card 端點，並將代理程式的中繼資料和 A2A 技能直接同步至 Agent Registry 資料模型。

從 Cloud Run 註冊代理

部署至 Cloud Run 的代理程式可以透過在部署期間指定 --functional-type=agent 和 --identity-type=agent-identity 旗標來註冊。--functional-type=agent 旗標會將 Cloud Run 工作負載識別為 AI 代理程式，而非標準容器化應用程式，並指示 Cloud Run 向 Agent Registry 註冊代理程式。

使用 --functional-type=agent 設定的工作負載必須指定 --identity-type=agent-identity 標記。使用任何其他身分類型進行部署都會導致錯誤。

您可以將代理程式部署為 Cloud Run 服務或工作。 如要瞭解如何在 Cloud Run 中將代理程式部署為服務或工作，請參閱「為 Cloud Run 設定 Agent Platform 功能」。

註冊期間，Cloud Run 會自動將代理程式的名稱、網址端點和類型 (AGENT) 新增至登錄檔。如要進一步瞭解如何將 A2A 代理程式部署至 Cloud Run，請參閱「將 A2A 代理程式部署至 Cloud Run」。

自動註冊功能只會探索部署在相同Google Cloud 專案中的資源。如要註冊部署在不同專案中的代理程式，請參閱手動註冊。

驗證註冊

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

控制台

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

    前往 Agent Registry

  2. 在專案挑選器中，選取 Google Cloud 您設定 Agent Registry的專案。

  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 發布者篩選清單，找出內建的 Google Workspace 代理程式。--filter="agentId:'urn:agent:googleapis.com:*'"

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