Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Usa el registro automático para los agentes

Agent Registry te permite configurar el registro automático de agentes en entornos de ejecución de Google Cloud compatibles para que los desarrolladores y los agentes de organización puedan descubrirlos sin crear recursos de registro de forma manual. Según el entorno de ejecución, el registro se realiza de forma predeterminada o a través de un paso de implementación de aceptación, y los metadatos indexados dependen del protocolo de implementación.

El registro automático solo descubre los recursos compatibles implementados dentro del proyecto de administración en el que está habilitado el registro de agentes. Para registrar agentes remotos implementados en otros proyectos deGoogle Cloud , consulta Registra un agente de otro proyecto. En el caso de los agentes remotos alojados de forma externa o en entornos de ejecución no compatibles, consulta Usa el registro manual para los agentes.

Metadatos indexados automáticamente

Los metadatos y las capacidades que se indexan para un agente durante el registro automático dependen de si el agente implementa el protocolo Agent2Agent (A2A):

Agentes que implementan el protocolo A2A: El Registro de agentes consulta la /.well-known/agent-card.json tarjeta de agente para extraer automáticamente sus habilidades de A2A y capacidades anunciadas en el Registro de agentes.
Agentes que no implementan el protocolo A2A: Agent Registry registra el agente, pero no puede capturar automáticamente metadatos como la URL del extremo en la que se aloja el agente, la identidad del agente y las habilidades de A2A. Estos son agentes que exponen, por ejemplo, extremos de REST o gRPC estándar. Para asociar capacidades con agentes que no sean A2A, usa el registro manual o registra habilidades.

Antes de comenzar

Configura el Registro de agentes.
Obtén el ID del proyecto para el proyecto de administración en el que está habilitado el Registro de agentes.
Para usar los comandos de Google Cloud CLI en este documento, configura tu entorno de gcloud CLI.

Registra agentes desde Agent Runtime

Si desarrollas e implementas agentes con Agent Runtime en Gemini Enterprise Agent Platform, el registro en Agent Registry es automático.

En el siguiente ejemplo, se muestra cómo implementar un agente que implementa el protocolo A2A en Agent Runtime. Para obtener más información, consulta Implementa un agente.

# 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]"],
    },
)

A medida que actualizas o borras tu agente en Agent Runtime, Agent Registry sincroniza esos cambios automáticamente.

Registra agentes de Google integrados

Los agentes de Google integrados, como los de Google Workspace y Gemini Enterprise, se registran automáticamente en Agent Registry. No necesitas realizar ningún paso de configuración ni implementación. Estos agentes se transfieren y están disponibles para el descubrimiento dentro de tu registro.

Registra agentes de GKE

Para registrar agentes implementados en Google Kubernetes Engine (GKE), agrega las etiquetas y anotaciones de Kubernetes requeridas a tu manifiesto de implementación. En el siguiente ejemplo, se muestra un manifiesto de GKE que define un Deployment de Kubernetes y un Service de Kubernetes configurados para el registro automático:

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

Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud .

Para configurar y aplicar el manifiesto de implementación, haz lo siguiente:

En metadata.labels del manifiesto de Deployment, agrega la etiqueta registry.gke.io/functional-type: "AGENT". Esta etiqueta identifica la implementación como una carga de trabajo de agente de IA, lo que indica al controlador del entorno de ejecución del clúster de GKE que inspeccione la carga de trabajo y registre el agente en Agent Registry.

Nota: GKE también admite la anotación apphub.cloud.google.com/functional-type: "AGENT" para la retrocompatibilidad. Sin embargo, usa la etiqueta registry.gke.io/functional-type: "AGENT" para tus implementaciones de GKE.
En metadata.annotations del manifiesto de Deployment, habilita el descubrimiento automático de las habilidades de A2A del agente proporcionando la anotación a2a-protocol.org/agent-card. El controlador de transferencia de GKE usa esta anotación para consultar la tarjeta del agente A2A.
En spec.template.metadata.annotations de la plantilla del Pod, habilita la comunicación autenticada configurando Agent Identity con la anotación iam.gke.io/spiffe-identity-type: agent-identity.
Aplica el manifiesto de Deployment a tu clúster. Para obtener más información, consulta Implementa y organiza agentes de IA.

Cuando aplicas la implementación, el controlador del entorno de ejecución del clúster de GKE inspecciona automáticamente el contenedor de la carga de trabajo y consulta el extremo de la tarjeta de agente declarado en la anotación. Luego, sincroniza los metadatos del agente y las habilidades de A2A directamente en un recurso de descubrimiento de Agent de solo lectura en Agent Registry.

Registra agentes desde Cloud Run

Puedes registrar agentes automáticamente cuando los implementas como servicios o trabajos de Cloud Run especificando las marcas --functional-type=agent y --identity-type=agent-identity. La marca --functional-type=agent identifica el servicio o trabajo de Cloud Run como un agente de IA, en lugar de una carga de trabajo en contenedores estándar, lo que indica a Cloud Run que registre el agente en el Registro de agentes. Durante el registro, Cloud Run agrega automáticamente el nombre del agente y el tipo AGENT al registro.

Las cargas de trabajo configuradas con --functional-type=agent deben especificar la marca --identity-type=agent-identity. La implementación con cualquier otro tipo de identidad genera un error.

Para configurar el registro automático en un servicio o trabajo de Cloud Run nuevo o existente, consulta Configura las funciones de Gemini Enterprise Agent Platform para Cloud Run. Para preparar, alojar en contenedores e implementar un agente compatible con A2A en Cloud Run, consulta Implementa agentes A2A en Cloud Run.

Verifica el registro

Para verificar que Agent Registry haya registrado correctamente tus agentes, enuméralos:

Console

En la consola de Google Cloud , ve a Agent Registry:

Ir al registro de agentes
En el selector de proyectos, selecciona el proyecto de Google Cloud en el que configuraste el Registro de agentes.
Selecciona la pestaña Agentes.

En la página, se muestra una lista de todos los agentes registrados y sus detalles, como el nombre, el identificador, la descripción, el entorno de ejecución y la ubicación.
Filtra la lista por la ubicación del agente o su recurso de entorno de ejecución:
- Para filtrar por ubicación, haz clic en el menú Ubicación, selecciona las ubicaciones que deseas filtrar y haz clic en Aplicar.
- Para filtrar por entorno de ejecución, haz clic en el menú Entorno de ejecución, selecciona los entornos de ejecución que deseas filtrar y haz clic en Aplicar.
En la página, se muestra una lista filtrada de los agentes registrados para las condiciones que seleccionaste.

gcloud

Puedes filtrar la lista por los metadatos del agente. Asegúrate de haber configurado tu entorno de gcloud CLI para el Registro de agentes y, luego, ejecuta el comando gcloud agent-registry agents list:

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

Reemplaza lo siguiente:

PROJECT_ID: Es el ID del proyecto.
REGION: Es la región del registro.
FILTER_EXPRESSION: Es la expresión de filtro para los agentes que deseas filtrar. Por ejemplo, para filtrar por nombre visible, puedes usar displayName='DISPLAY_NAME'. Para filtrar por el identificador de agente (URN) único a nivel global, puedes usar agentId='urn:agent:AGENT_URN'.

Los agentes integrados de Google usan un formato de identificador de agente (URN) que depende de dónde se implemente el agente. Por ejemplo, puedes descubrir agentes integrados de Google Workspace filtrando tu lista por el publicador googleapis.com con --filter="agentId:'urn:agent:googleapis.com:*'".

Terraform

Haz referencia a tu agente registrado en otras configuraciones de Terraform con la fuente de datos google_agent_registry_agent:

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
}