使用自动注册

Agent Registry 可以注册托管在受支持的Google Cloud runtime 上的代理，而无需您手动调用 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) protocol 是一种开放标准，可让代理声明其功能和身份。以下示例展示了如何将实现 A2A protocol 的代理部署到 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 的代理

您可以通过向部署添加 registry.gke.io/functional-type: "AGENT" 标签来注册部署在 Google Kubernetes Engine (GKE) 上的代理。此标签用于将部署标识为 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

应用 Deployment 后，GKE 集群运行时控制器会自动内省工作负载容器，查询注解中声明的 Agent Card 端点，并将代理的元数据和 A2A 技能直接同步到 Agent Registry 数据模型中。

从 Cloud Run 注册代理

您可以在部署期间指定 --functional-type=agent 和 --identity-type=agent-identity 标志，以注册部署到 Cloud Run 的代理。--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. 选择代理标签页。

    该页面会显示所有已注册的代理及其详细信息，例如名称、标识符、说明、运行时和位置。

  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：智能体的直观易懂的显示名称。