为代理使用自动注册

借助 Agent Registry，您可以为受支持的 Google Cloud 运行时上的智能体配置自动注册，以便开发者和编排器智能体无需手动创建注册表资源即可发现这些智能体。根据运行时，注册默认发生或通过选择启用的部署步骤发生，索引元数据取决于实现协议。

自动注册功能只会发现在启用了 Agent Registry 的治理项目中部署的受支持资源。如需注册部署在其他Google Cloud 项目中的远程代理，请参阅注册其他项目中的代理。对于在外部或不受支持的运行时上托管的远程代理，请参阅为代理使用手动注册。

自动编入索引的元数据

在自动注册期间为智能体编入索引的元数据和功能取决于智能体是否实现了 Agent2Agent (A2A) 协议：

• 实现 A2A protocol 的智能体：Agent Registry 会查询智能体的 /.well-known/agent-card.json 智能体卡片，以自动提取其在 Agent Registry 中通告的 A2A skill和能力。
• 未实现 A2A protocol 的代理：Agent Registry 会注册代理，但无法自动捕获元数据，例如托管代理的端点网址、Agent Identity 和 A2A 技能。这些代理会公开标准 REST 或 gRPC 端点等。如需将功能与非 A2A 智能体相关联，请使用手动注册或注册技能。

准备工作

1. 设置 Agent Registry。

2. 获取已启用 Agent Registry 的治理项目的项目 ID。

3. 如需使用本文档中的 Google Cloud CLI 命令，请设置 gcloud CLI 环境。

注册 Agent Runtime 中的智能体

如果您使用 Gemini Enterprise Agent Platform 上的 Agent Runtime 开发和部署代理，则系统会自动在 Agent Registry 中注册。

以下示例展示了如何将实现 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 注册智能体

如需注册部署在 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。

如需配置和应用部署清单，请执行以下操作：

1. 在 Deployment 清单的 metadata.labels 中，添加 registry.gke.io/functional-type: "AGENT" 标签。此标签会将部署标识为 AI 智能体工作负载，从而指示 GKE 集群运行时控制器检查工作负载，并在 Agent Registry 中注册智能体。

   注意 ：GKE 还支持 apphub.cloud.google.com/functional-type: "AGENT" 注解，以实现向后兼容。不过，请为 GKE 部署使用 registry.gke.io/functional-type: "AGENT" 标签。

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 智能体。

   应用部署后，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 功能。如需在 Cloud Run 上准备、容器化和部署符合 A2A 规范的智能体，请参阅将 A2A 智能体部署到 Cloud Run。

验证注册

您可以通过列出智能体来验证 Agent Registry 是否已成功注册这些智能体：

控制台

1. 在 Google Cloud 控制台中，前往 Agent Registry：

   前往 Agent Registry

2. 在项目选择器中，选择您设置 Agent Registry 的 Google Cloud 项目。

3. 选择代理标签页。

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

4. 按代理的位置或其运行时资源过滤列表：

   • 如需按位置过滤，请点击位置菜单，选择要过滤的位置，然后点击应用。
   • 如需按运行时进行过滤，请点击运行时菜单，选择要过滤的运行时，然后点击应用。

   该页面会显示符合所选条件的已注册代理的过滤列表。

gcloud

您可以按代理的元数据过滤列表。确保您已为 Agent Registry 设置 gcloud CLI 环境，然后运行 gcloud agent-registry agents list 命令：

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) 格式，该格式取决于代理的部署位置。例如，您可以使用 --filter="agentId:'urn:agent:googleapis.com:*'" 过滤 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：代理的人类可读显示名称。