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 buscas en Agent Registry, puedes encontrar agentes existentes con las habilidades que necesitas, como un "Agente de políticas corporativas" o un "Agente de reservas de vuelos" existentes, en lugar de crear integraciones duplicadas desde cero.

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

Antes de comenzar

Antes de comenzar esta guía de inicio rápido, registra un agente en Agent Registry. También necesitarás el ID de tu proyecto para realizar estas tareas.

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

Roles obligatorios

Para obtener los permisos que necesitas para descubrir agentes en Agent Registry, pídele a tu administrador que te otorgue el rol de IAM Visualizador de la API de Agent Registry (roles/agentregistry.viewer) 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.

Enumera los agentes disponibles

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

Console

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

    Ir a Agent Registry

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

  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 todos los detalles 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: Es 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 del agente de A2A cuando está disponible.

Cómo 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 consola de Google Cloud , ve a Agent Registry:

    Ir a Agent Registry

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

  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 por las 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 por los 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

Filtra tu lista de agentes para que solo muestre los recursos que coincidan con pares clave-valor específicos, usando 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: 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 (URN) único a nivel global, puedes usar agentId='urn:agent:AGENT_URN'.

Cómo ver los detalles del agente

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

Console

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

    Ir a Agent Registry

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

  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 del tiempo de ejecución. Las pestañas como Sesiones, Playground, Recuerdos y Evaluación son capacidades específicas que se muestran para los agentes creados en entornos de ejecución administrados, como Vertex AI Agent Engine:

    • Descripción general: Detalles principales del agente, incluidos su nombre, identificador, ubicación, descripción y tiempo de ejecución. 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 la latencia, el tráfico, los errores y la inversión en 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, lo que te ayuda a administrar los costos y la experiencia del usuario. Para obtener más información, consulta la Descripción general de la observabilidad.
    • Registros: 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 de razonamiento complejos de varios agentes o errores de invocación de herramientas en tiempo real. Para obtener más información, consulta Cómo ver los registros del agente.
    • Seguridad: Hallazgos de Model Armor y Security Command Center, incluidos los incumplimientos de políticas de contenido, los riesgos de filtración de datos y las evaluaciones de cumplimiento Para obtener más información sobre la seguridad, consulta Cómo ver los resultados de seguridad.
    • Topología: Es 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 de MCP con los que interactúa. Para obtener más información sobre Agent Gateway, consulta la descripción general de Agent Gateway. Para obtener más información sobre la topología, consulta Cómo ver los gráficos de un agente registrado.
    • Identidad: Es el principal del agente que se usa para aplicar la política. Por ejemplo, usas esta identidad para configurar vinculaciones del proveedor 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: Es una interfaz de chat directa para probar el comportamiento del agente.
    • Recuerdos: Son 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 nuevas tareas de evaluación, subir métricas y evaluar el rendimiento cognitivo del agente y la confiabilidad del modelo en comparación con el tráfico real 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: Es 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 de tiempo de ejecución y la carga útil completa de la tarjeta de agente A2A, puedes vincular de forma segura tu agente a los flujos de trabajo del orquestador con el kit de desarrollo de agentes (ADK) o las solicitudes a la API estándar.

¿Qué sigue?