Guía de inicio rápido: Descubre un agente

Discovery es el mecanismo principal para acelerar el desarrollo con cargas de trabajo de agentes. Si realizas búsquedas en el Registro de agentes, puedes encontrar agentes existentes con las habilidades que necesitas, como un "Agente de política corporativa" o un "Agente de reserva de vuelos" existentes, en lugar de crear integraciones duplicadas desde cero.

En esta guía de inicio rápido, se muestra cómo descubrir agentes registrados en el Registro de agentes.

Antes de comenzar

Antes de comenzar esta guía de inicio rápido, registra un agente en el Registro de agentes. También necesitas el ID del proyecto para realizar estas tareas.

Para usar los comandos de gcloud CLI en este documento, asegúrate de haber configurado tu Google Cloud CLI Cloud.

Roles obligatorios

Para obtener los permisos que necesitas para descubrir agentes en el Registro de agentes, pídele a tu administrador que te otorgue el Visualizador de la API de Agent Registry (roles/agentregistry.viewer) rol de IAM en el proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Mostrar lista de agentes disponibles

Consulta una lista completa de todos los agentes registrados e indexados en el registro:

Console

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

    Ir al Registro de agentes

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste el Registro de agentes.

  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. Para ver los detalles completos de un agente, haz clic en su nombre.

gcloud

Para enumerar todos los agentes en una ubicación específica, usa el comando agents list:

gcloud alpha agent-registry agents list \
  --project=PROJECT_ID \
  --location=REGION

Reemplaza lo siguiente:

  • PROJECT_ID: El ID del proyecto
  • REGION: La región del registro

El resultado se ve como en el siguiente ejemplo:

- name: projects/1234567890/locations/us-central1/agents/my-travel-agent
  displayName: Travel Orchestrator Agent
  description: 'Decomposes natural language travel requests into sub-tasks.'
  version: 1.0.0
  protocols:
    - type: A2A_AGENT
      protocolVersion: "0.3"
      interfaces:
        - url: https://api.example.com/.well-known/agent-card.json
          protocolBinding: HTTP_JSON
  attributes:
    agentregistry.googleapis.com/system/Framework:
      framework: "google-adk"
    agentregistry.googleapis.com/system/RuntimeIdentity:
      identity: "principal://..."
  card:
    type: A2A_AGENT_CARD
    content: {...}

El campo card contiene el contenido completo de la tarjeta de agente A2A cuando está disponible.

Filtrar agentes registrados

Si tienes varios agentes o si deseas confirmar el registro de un agente específico, puedes filtrar la lista por los metadatos del agente:

Console

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

    Ir al Registro de agentes

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste el Registro de agentes.

  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

Filtra tu lista de agentes para que solo muestre los recursos que coincidan con pares clave-valor específicos con la marca --filter:

gcloud alpha 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'.

Ver detalles del agente

Si has identificado un agente que deseas usar, puedes recuperar sus metadatos completos, incluido su extremo de tiempo de ejecución y la lista completa de habilidades:

Console

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

    Ir al Registro de agentes

  2. En el selector de proyectos, selecciona el Google Cloud proyecto en el que configuraste el Registro de agentes.

  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. Haz clic en el nombre del agente que deseas ver.

    La página de detalles incluye pestañas para los detalles del agente.

  5. Haz clic en la pestaña correspondiente para ver los detalles específicos del agente.

    La disponibilidad de las funciones depende de tu tiempo de ejecución. Las pestañas como Sesiones, Playground, Memorias y Evaluación son capacidades específicas que se muestran para los agentes compilados en tiempos de ejecución administrados, como Vertex AI Agent Engine:

    • Descripción general: Detalles principales del agente, incluidos el nombre, el identificador, la ubicación, la descripción y el tiempo de ejecución del agente. En la descripción general, también se muestran las habilidades y el URI del recurso, que necesitas para compilar consultas en el gráfico de topología.
    • Observabilidad: Estadísticas centradas en la aplicación, como latencia, tráfico, errores y gasto de tokens. Esta pestaña se integra con las herramientas de Google Cloud Observability para mostrar métricas de rendimiento en tiempo real y la utilización a nivel del sistema para ayudarte a administrar los costos y la experiencia del usuario. Para obtener más información, consulta la descripción general de Observabilidad.
    • Seguimientos: La ruta exacta de una conversación paso a paso, incluido el formato detallado de los mensajes de entrada y del asistente para depurar bucles complejos de razonamiento de varios agentes o errores de invocación de herramientas en tiempo real. Para obtener más información, consulta Visualiza seguimientos de agentes.
    • Seguridad: Resultados de Model Armor y Security Command Center, incluidas las infracciones de la política de contenido, los riesgos de filtración de datos y las evaluaciones de cumplimiento. Para obtener más información sobre la seguridad, consulta Visualiza resultados de seguridad.
    • Topología: Un mapa visual de las relaciones y los flujos de tráfico entre un agente, su puerta de enlace de agente asignada y los servidores MCP con los que interactúa. Para obtener más información sobre la puerta de enlace de agente, consulta la descripción general de la puerta de enlace de agente. Para obtener más información sobre la topología, consulta Visualiza gráficos para un agente registrado.
    • Identidad: La entidad de seguridad del agente que se usa para la aplicación de políticas. Usas esta identidad, por ejemplo, para configurar vinculaciones de proveedores de autenticación para la autenticación en herramientas y recursos.
    • Sesiones: Historial de conversaciones persistente y seguimiento de las interacciones activas con el agente.
    • Playground: Una interfaz de chat directa para probar el comportamiento del agente.
    • Memorias: Funciones de personalización a largo plazo que generan o recuerdan detalles de conversaciones anteriores con el agente para preservar el contexto en las interacciones.
    • Evaluación: Detalles de todas las tareas de evaluación del agente. Esta pestaña te permite crear tareas de evaluación nuevas, subir métricas y evaluar el rendimiento cognitivo del agente y la confiabilidad del modelo en comparación con el tráfico en vivo o las simulaciones sintéticas.

gcloud

Para ver los metadatos detallados de un agente específico, usa el comando agents describe:

gcloud alpha agent-registry agents describe AGENT_NAME \
  --project=PROJECT_ID \
  --location=REGION

Reemplaza lo siguiente:

  • AGENT_NAME: El nombre de tu agente, por ejemplo, my-travel-agent
  • PROJECT_ID: El ID del proyecto
  • REGION: La región del registro

Con el extremo del agente, las definiciones de habilidades y los metadatos de solo salida, como el framework subyacente, la identidad del tiempo de ejecución y la carga útil completa de la tarjeta de agente A2A, puedes vincular de forma segura tu agente a tus flujos de trabajo del orquestador con el Kit de desarrollo de agentes (ADK) o las solicitudes de API estándar.

¿Qué sigue?