Usa el registro automático

Agent Registry puede registrar agentes alojados en supported Google Cloud runtimes sin que tengas que llamar manualmente a la API de Agent Registry. Según el entorno de ejecución, este proceso de registro se realiza automáticamente o requiere un paso de configuración de aceptación durante la implementación.

En este documento, se explica cómo habilitar la detección de agentes en entornos de ejecución compatibles. Si alojas un agente de forma externa o en un entorno de ejecución no compatible, consulta Usa el registro manual.

Los metadatos y las habilidades de A2A extraídos de un agente durante su registro dependen del protocolo del agente. Para obtener más información, consulta Registra agentes.

Antes de comenzar

Antes de registrar agentes, configura Agent Registry. Necesitas el ID de tu proyecto para verificar el registro.

Para usar los comandos de Google Cloud CLI en este documento, asegúrate de haber configurado 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.

El protocolo Agent2Agent (A2A) es un estándar abierto que permite que los agentes declaren sus capacidades e identidad. 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 automáticamente esos cambios.

Registra agentes integrados de Google

Los agentes integrados de Google, como Google Workspace y Gemini Enterprise agentes, se registran automáticamente en Agent Registry. No es necesario que realices ningún paso de configuración ni implementación. Estos agentes se incorporan y están disponibles para la detección en tu registro.

Registra agentes desde GKE

Puedes registrar agentes implementados en Google Kubernetes Engine (GKE) agregando la etiqueta registry.gke.io/functional-type: "AGENT" a tus implementaciones. Esta etiqueta identifica la implementación como un agente de IA, lo que permite que Agent Registry realice un análisis de introspección.

Para habilitar la detección automatizada de las habilidades del agente, también debes proporcionar la anotación a2a-protocol.org/agent-card. El controlador de incorporación usa esta anotación para consultar la tarjeta de agente A2A. Además, configura Workload Identity con la anotación iam.gke.io/spiffe-identity-type: agent-identity para ayudar a habilitar la comunicación autenticada segura.

En el siguiente ejemplo, se muestra un manifiesto de implementación de agente de GKE con estas configuraciones. Para obtener más información, consulta Implementa y organiza agentes de IA.

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

Cuando se aplica la implementación, el clúster de GKE intenta recuperar automáticamente los metadatos del agente y los sincroniza directamente en el modelo de datos de Agent Registry.

Verifica el registro

Para verificar que Agent Registry haya registrado correctamente tus agentes, haz lo siguiente:

Console

  1. En la Google Cloud console, ve a Agent Registry:

    Ir a Agent Registry

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste Agent Registry.

  3. 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.

  4. 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 seleccionadas.

gcloud

Puedes filtrar la lista por los metadatos del agente. Asegúrate de haber configurado tu entorno de Google Cloud CLI para Agent Registry y, luego, ejecuta lo siguiente:

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

Reemplaza lo siguiente:

  • PROJECT_ID: El ID del proyecto
  • REGION: La región del registro
  • FILTER_EXPRESSION: 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 único global (URN), puedes usar agentId='urn:agent:AGENT_URN'.

Los agentes integrados de Google usan un formato URN que depende de dónde se implemente el agente. Por ejemplo, puedes descubrir agentes integrados de Google Workspace si filtras tu lista para 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
}

Reemplaza lo siguiente:

  • REGION: La región del registro
  • DISPLAY_NAME: El nombre visible legible del agente