Usa el registro automático

Agent Registry puede registrar agentes alojados en entornos de ejecución compatibles Google Cloud 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 Cómo usar el registro manual.

Los metadatos y las capacidades indexados para un agente durante el registro dependen de si el agente implementa el protocolo Agent2Agent (A2A). 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 a los agentes declarar 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 una carga de trabajo de agente de IA, lo que indica al controlador de tiempo de ejecución del clúster de GKE que realice un análisis de introspección en el clúster y registre el agente con Agent Registry.

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 de GKE usa esta anotación para consultar la tarjeta de agente A2A.

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:
      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 controlador de tiempo de ejecución del clúster de GKE inspecciona automáticamente el contenedor de la carga de trabajo, consulta el extremo de la tarjeta de agente declarado en la anotación y sincroniza los metadatos del agente y las habilidades de A2A directamente en el modelo de datos de Agent Registry.

Registra agentes desde Cloud Run

Puedes registrar agentes implementados en Cloud Run especificando las marcas --functional-type=agent y --identity-type=agent-identity durante la implementación. La marca --functional-type=agent identifica la carga de trabajo de Cloud Run como un agente de IA en lugar de una aplicación en contenedores estándar, lo que indica a Cloud Run que registre el agente con Agent Registry.

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.

Puedes implementar agentes como servicios o trabajos de Cloud Run. Para obtener información sobre cómo implementar un agente como un servicio o trabajo en Cloud Run, consulta Configura las funciones de Agent Platform para Cloud Run.

Durante el registro, Cloud Run agrega automáticamente el nombre, el extremo de URL y el tipo (AGENT) del agente al registro. Para obtener más información sobre la implementación de agentes A2A en Cloud Run, consulta Implementa agentes A2A en Cloud Run.

El registro automático solo descubre los recursos implementados en el mismo Google Cloud proyecto. Para registrar agentes implementados en diferentes proyectos, consulta el registro manual.

Verifica el registro

Para verificar que Agent Registry registró correctamente tus agentes, haz lo siguiente:

Console

  1. En la Google Cloud consola, 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 tiempo de ejecución y la ubicación.

  4. Filtra la lista por la ubicación del agente o su recurso de tiempo 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 tiempo de ejecución, haz clic en el menú Tiempo de ejecución , selecciona los tiempos 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 filtrando 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