Supervisa un agente

En esta página, se describe cómo usar métricas integradas, métricas personalizadas y alertas para supervisar tus agentes en Vertex AI Agent Engine.

Descripción general

Puedes usar Vertex AI Agent Engine con Cloud Monitoring sin ninguna configuración adicional. Las métricas del agente integrado se recopilan y visualizan automáticamente en las páginas de Cloud Monitoring en la consola deGoogle Cloud .

Métricas integradas compatibles

Las siguientes métricas de agentes son compatibles y se asocian con el recurso supervisado del motor de agentes de Vertex AI aiplatform.googleapis.com/ReasoningEngine:

  • Recuento de solicitudes
  • Latencias de las solicitudes
  • Tiempo de asignación de CPU del contenedor
  • Tiempo de asignación de memoria del contenedor

Consulta la lista completa de métricas de AI Platform para obtener más detalles sobre los tipos de métricas, las unidades, las etiquetas, así como la latencia y el período de muestreo.

Consulta las métricas de un agente

Puedes ver las métricas integradas de tu agente en la Google Cloud consola con el Explorador de métricas:

  1. Para obtener permiso para ver las métricas en el Explorador de métricas, pídele a tu administrador que te otorgue el rol de Visualizador de Monitoring (roles/monitoring.viewer) en tu proyecto.

  2. Ve al Explorador de métricas en la Google Cloud consola:

    Ir al Explorador de métricas

  3. Seleccionar tu Google Cloud proyecto.

  4. Haz clic en Seleccionar una métrica para abrir una barra de búsqueda.

  5. Ingresa Motor de razonamiento de Vertex AI en la barra de búsqueda y haz clic en Motor de razonamiento de Vertex AI.

  6. Haz clic en la categoría de métrica Reasoning_engine y, luego, en una métrica, como Request count.

  7. De manera opcional, establece filtros de etiquetas adicionales, el elemento de agregación y ajusta el intervalo de tiempo.

De forma predeterminada, los gráficos del Explorador de métricas para la métrica Recuento de solicitudes alinean los datos con un intervalo de tiempo predeterminado y los grafican como solicitudes por segundo (una métrica de frecuencia).

Cómo consultar métricas de un agente

También puedes consultar métricas a través del lenguaje de consulta de Monitoring (MQL), el lenguaje de consulta de Prometheus (PromQL) o la API de Cloud Monitoring v3. MQL y PromQL ofrecen más opciones para el filtrado, la agregación y la transformación de métricas, mientras que la API de Cloud Monitoring te permite enumerar y consultar de forma programática todos los datos sin procesar.

Consulta métricas con MQL o PromQL

Puedes usar MQL o PromQL para alinear y agregar datos con un intervalo de tiempo personalizado y graficar los datos transformados como el recuento absoluto de solicitudes (en lugar de solicitudes por segundo):

MQL 

fetch aiplatform.googleapis.com/ReasoningEngine
  | metric 'aiplatform.googleapis.com/reasoning_engine/request_count'
  | filter
      (resource.reasoning_engine_id == 'RESOURCE_ID')
      && (metric.response_code == 'RESPONSE_CODE')
  | align delta(10m)
  | every 10m

PromQL 

sum_over_time(
  increase(
      aiplatform_googleapis_com:reasoning_engine_request_count{
          monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
          reasoning_engine_id='RESOURCE_ID',
          response_code='RESPONSE_CODE'
      }
      [10m]
  )
  [10m:10m]
)

Para consultar la tasa de errores, calcula la proporción de las solicitudes etiquetadas con ciertos códigos de respuesta de error (como 500) con respecto a la cantidad total de solicitudes (porcentaje de solicitudes con errores):

MQL 

fetch aiplatform.googleapis.com/ReasoningEngine
  | metric 'aiplatform.googleapis.com/reasoning_engine/request_count'
  | filter resource.reasoning_engine_id == 'RESOURCE_ID'
  | { filter metric.response_code == '500' ; ident }
  | align rate(10m)
  | every 10m
  | group_by [], [value_request_count_aggregate: aggregate(value.request_count)]
  | ratio

PromQL 

sum_over_time(
  sum(
    rate(
      aiplatform_googleapis_com:reasoning_engine_request_count{
        monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
        reasoning_engine_id='RESOURCE_ID',
        response_code='500'
      }
      [10m]
    )
  )
  [10m:10m]
)
/
sum_over_time(
  sum(
    rate(
      aiplatform_googleapis_com:reasoning_engine_request_count{
        monitored_resource='aiplatform.googleapis.com/ReasoningEngine',
        reasoning_engine_id='RESOURCE_ID',
      }
      [10m]
    )
  )
  [10m:10m]
)

Para conocer las prácticas recomendadas y las restricciones de las métricas de proporción, consulta Acerca de las proporciones de las métricas. Para ver un ejemplo de cómo configurar una alerta para la métrica de tasa de error, consulta Ejemplos de políticas en JSON.

Consulta métricas con la API de Cloud Monitoring

Puedes usar la API de Cloud Monitoring para hacer lo siguiente:

  • Obtén la definición de recurso supervisado de Vertex AI Agent Engine

  • Lista de definiciones de métricas de agente disponibles

  • Cómo consultar datos de series temporales de request_count

Todas las métricas del agente están asociadas con el recurso supervisado del motor de agentes aiplatform.googleapis.com/ReasoningEngine.

Puedes invocar estas APIs a través del Explorador de APIs, las bibliotecas cliente específicas de un lenguaje o la línea de comandos. Consulta la documentación para leer métricas a través del Explorador de APIs y las bibliotecas cliente. En los siguientes ejemplos, se muestra el uso en la línea de comandos, más específicamente, la herramienta curl.

Obtén la definición de recurso supervisado del motor de agentes

El siguiente comando recupera la definición del recurso supervisado con projects.monitoredResourceDescriptors, así como todas las etiquetas disponibles que se pueden usar para filtrar:

gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/monitoredResourceDescriptors/aiplatform.googleapis.com/ReasoningEngine

Las etiquetas deben incluir resource_container, location y reasoning_engine_id.

Lista de definiciones de métricas de agente disponibles

El siguiente comando usa projects.metricDescriptors para recuperar todas las métricas y los filtros de etiquetas de Agent Engine:

gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/metricDescriptors?filter='metric.type=starts_with("aiplatform.googleapis.com/reasoning_engine")'

El resultado debe incluir la definición de las siguientes métricas, así como sus etiquetas específicas:

  • aiplatform.googleapis.com/reasoning_engine/request_count
  • aiplatform.googleapis.com/reasoning_engine/request_latencies
  • aiplatform.googleapis.com/reasoning_engine/cpu/allocation_time
  • aiplatform.googleapis.com/reasoning_engine/memory/allocation_time

Cómo consultar datos de series temporales de request_count

Puedes usar projects.timeSeries.list junto con parámetros como interval, filter y aggregation para consultar datos de series temporales.

En el siguiente ejemplo, se muestra cómo consultar los datos sin procesar de la métrica request_count para una instancia de agente específica durante un período específico:

gcurl https://monitoring.googleapis.com/v3/projects/PROJECT_ID/timeSeries?filter='metric.type="aiplatform.googleapis.com/reasoning_engine/request_count"%20AND%20resource.labels.reasoning_engine_id="RESOURCE_ID"&interval.endTime=2025-03-26T11:00:0.0-08:00&interval.startTime=2025-03-26T10:00:0.0-08:00'

Reemplaza lo siguiente:

  • PROJECT_ID: El ID de tu proyecto de Google Cloud .
  • RESOURCE_ID: El ID de la instancia de Agent Engine. Esto no siempre es obligatorio. Puedes consultar varias instancias de Agent Engine dentro del mismo proyecto.
  • interval.startTime y interval.endTime: El inicio (inclusive) y la finalización (excluyente) del intervalo de tiempo, en formato RFC 3339. Por ejemplo, "2025-03-26T11:22:33Z" para la hora universal coordinada (UTC) y "2025-03-26T11:22:33-08:00" para la hora estándar del Pacífico (PST). Consulta la definición completa y más ejemplos en la RFC 3339.

Deberías recibir una respuesta similar a la que figura a continuación:

{
  "timeSeries": [
    {
      "metric": {
        "labels": {
          "response_code": "200",
          "response_code_class": "2xx"
        },
        "type": "aiplatform.googleapis.com/reasoning_engine/request_count"
      },
      "resource": {
        "type": "aiplatform.googleapis.com/ReasoningEngine",
        "labels": {
          "reasoning_engine_id": "RESOURCE_ID",
          "location": "LOCATION",
          "project_id": "PROJECT_ID"
        }
      },
      "metricKind": "DELTA",
      "valueType": "INT64",
      "points": [
        {
          "interval": {
            "startTime": "2025-03-26T18:55:27.001Z",
            "endTime": "2025-03-26T18:56:27Z"
          },
          "value": {
            "int64Value": "25"
          }
        },
        {
          "interval": {
            "startTime": "2025-03-26T18:54:27.001Z",
            "endTime": "2025-03-26T18:55:27Z"
          },
          "value": {
            "int64Value": "36"
          }
        }
        // ... more data points ...
      ]
    }
    // ... potentially more time series with other response codes ...
  ],
  "unit": "1"
}

Consulta projects.timeSeries.list para obtener más detalles sobre el formato de la respuesta.

Crea métricas personalizadas para un agente

Si las métricas del agente integradas no cubren tu caso de uso específico, puedes definir métricas personalizadas. Puedes crear métricas personalizadas con los siguientes métodos:

Métricas basadas en registros

En los siguientes pasos, se muestra cómo crear y usar una métrica basada en registros (tool_calling_count) para un flujo de trabajo de ejemplo en el que varios agentes llaman a varias herramientas y deseas contar las invocaciones de herramientas:

  1. Especifica tu herramienta para que escriba una entrada de registro cada vez que se la llame. Por ejemplo, "tool-\<tool-id\> invoked by agent-\<agent-id\>".

  2. Crea una nueva métrica basada en registros de tipo de contador a través de la consola de Google Cloud :

    1. Ve a la página Métricas basadas en registros en la consola de Google Cloud :

      Ve a Métricas basadas en registros

    2. En la sección Métricas definidas por el usuario, haz clic en Crear métrica. Aparecerá el panel Crear métrica basada en registros.

    3. En Tipo de métrica, selecciona Contador.

    4. En la sección Detalles, ingresa el Nombre de la métrica basada en registros. Por ejemplo, tool_calling_count. De manera opcional, ingresa la Descripción y las Unidades.

    5. En la sección Selección de filtro, haz lo siguiente:

      1. En la lista desplegable Seleccionar proyecto o bucket de registros, selecciona Registros del proyecto.

      2. En el campo Build filter, ingresa el filtro de registro con el lenguaje de consulta de registro. Por ejemplo:

        resource.type="aiplatform.googleapis.com/ReasoningEngine"
resource.labels.reasoning_engine_id="RESOURCE_ID"
textPayload =~ "tool-\d+ invoked by agent-\d+" -- assuming both tool and agent IDs are numeric

    6. En la sección Etiquetas, haz clic en el botón Agregar etiqueta para agregar dos etiquetas nuevas.

      1. Para la primera etiqueta, haz lo siguiente:

        1. En el campo Label name, ingresa tool.

        2. En el campo Nombre del campo (Field name), ingresa textPayload.

        3. En el campo Expresión regular, ingresa (tool-\d+) invoked by agent-\d+.

      2. Para la segunda etiqueta, haz lo siguiente:

        1. En el campo Label name, ingresa agent.

        2. En el campo Nombre del campo (Field name), ingresa textPayload.

        3. En el campo Expresión regular, ingresa tool-\d+ invoked by (agent-\d+).

      1. Haz clic en Listo.

    7. Haz clic en Crear métrica.

  3. Para ver la métrica tool_calling_count y sus registros asociados, haz lo siguiente en la consola de Google Cloud :

    1. Ve a la página Explorador de métricas en la consola de Google Cloud :

      Ir al Explorador de métricas

    2. Haz clic en Seleccionar una métrica para abrir una barra de búsqueda.

    3. Ingresa Motor de razonamiento de Vertex AI en la barra de búsqueda y haz clic en Motor de razonamiento de Vertex AI.

    4. Haz clic en la categoría de métrica Métricas basadas en registros y, luego, en Logging/user/tool_calling_count. Si es necesario, ajusta el intervalo de tiempo.

    5. (Opcional) Filtra por las etiquetas tool y agent.

      • Para obtener el recuento total de invocaciones de una herramienta específica para todos los agentes, configura la etiqueta de filtro tool con el valor del ID de esa herramienta.

      • Para obtener el recuento total de invocaciones de un agente específico para todas las herramientas, configura la etiqueta de filtro agent con el valor de ese ID de agente.

      De manera opcional, establece Sumar por en tool o agent para obtener el recuento total desglosado por diferentes herramientas o agentes.

Consulta Cómo registrar un agente para obtener instrucciones sobre cómo escribir registros de agentes y Descripción general de las métricas basadas en registros para obtener más detalles sobre las métricas basadas en registros.

Métricas definidas por el usuario

En los siguientes pasos, se muestra cómo crear y usar una métrica definida por el usuario (token_count) para un flujo de trabajo de ejemplo en el que varios agentes llaman a varios modelos y deseas calcular el recuento total de tokens consumidos (suponiendo que realizas un seguimiento de la cantidad de tokens desde el inicio de la aplicación para cada agente de invocación y modelo de destino):

  1. Para definir el tipo de métrica personalizada, llama a projects.metricDescriptors.create con los siguientes parámetros:

    • name: Es una cadena de URL, como projects/PROJECT_ID.

    • Request body: Un objeto MetricDescriptor:

      {
  "name": "token_count",
  "description": "Token Consumed by models.",
  "displayName": "Token Count",
  "type": "custom.googleapis.com/token_count",
  "metricKind": "CUMULATIVE",
  "valueType": "INT64",
  "unit": "1",
  "labels": [
    {
      "key": "model",
      "valueType": "STRING",
      "description": "Model."
    },
    {
      "key": "agent",
      "valueType": "STRING",
      "description": "Agent."
    }
  ],
  "monitoredResourceTypes": [
    "generic_node"
  ]
}

      La métrica nueva token_count se crea con el tipo Cumulative, que representa la cantidad total de tokens desde el inicio de la aplicación. Consulta Categorías y tipos de métricas para obtener más detalles sobre las métricas de Cumulative. Las etiquetas model y agent representan el nombre del modelo de lenguaje grande (LLM) de destino y el agente de invocación.

    1. Puedes encontrar la métrica token_count en el Explorador de métricas:

      1. Ve a la página Explorador de métricas en la consola de Google Cloud :

      Ir al Explorador de métricas

      1. Haz clic en Seleccionar una métrica para abrir una barra de búsqueda.

      2. Ingresa Nodo genérico en la barra de búsqueda y haz clic en Métricas personalizadas.

      3. Haz clic en Recuento de tokens.

  2. Para escribir datos en la métrica nueva, llama a projects.timeSeries.create con los siguientes parámetros:

    • name: Es una cadena de URL, como projects/PROJECT_ID.

    • Request body: Es una lista de objetos TimeSeries:

      {
  "timeSeries": [
    {
      "metric": {
        "type": "custom.googleapis.com/token_count",
        "labels": {
          "model": "model-1",
          "agent": "agent-1"
        }
      },
      "resource": {
        "type": "generic_node",
        "labels": {
          "project_id": "PROJECT_ID",
          "node_id": "RESOURCE_ID",
          "namespace": "",
          "location": "us-central1"
        }
      },
      "points": [
        {
          "interval": {
            "startTime": "2025-03-26T10:00:00-08:00",
            "endTime": "2025-03-26T10:01:00-08:00"
          },
          "value": {
            "int64Value": 15
          }
        }
      ]
    },
    {
      "metric": {
        "type": "custom.googleapis.com/token_count",
        "labels": {
          "model": "model-1",
          "agent": "agent-2"
        }
      },
      "resource": {
        "type": "generic_node",
        "labels": {
          "project_id": "PROJECT_ID",
          "node_id": "RESOURCE_ID",
          "namespace": "",
          "location": "us-central1"
        }
      },
      "points": [
        {
          "interval": {
            "startTime": "2025-03-26T10:00:00-08:00",
            "endTime": "2025-03-26T10:01:00-08:00"
          },
          "value": {
            "int64Value": 20
          }
        }
      ]
    }
    // ... more time series ...
  ]
}

  3. Una vez que se suban los datos a través de la API de Cloud Monitoring, podrás ver la métrica nueva token_count a través de la consola de Google Cloud :

    1. Ve a la página Explorador de métricas en la consola de Google Cloud :

      Ir al Explorador de métricas

    2. Haz clic en Seleccionar una métrica para abrir una barra de búsqueda.

    3. Ingresa Nodo genérico en la barra de búsqueda y haz clic en Métricas personalizadas.

    4. Haz clic en Recuento de tokens. Ajusta el intervalo de tiempo y configura los valores de etiqueta para model o agent si es necesario.

Crea alertas para un agente

Puedes usar métricas en combinación con alertas. Consulta la descripción general de las alertas para obtener más detalles.

En el siguiente ejemplo, se muestra cómo crear una alerta de umbral para la métrica request_latencies para que recibas notificaciones cuando la latencia supere un valor predefinido durante una duración especificada:

  1. Ve a la página Alertas en la Google Cloud consola:

    Ve a las alertas

  2. Haz clic en Crear política. Se abrirá la página Crear política de alertas.

    1. En Policy configuration mode, selecciona Builder.

    2. En el menú desplegable Seleccionar una métrica, selecciona Vertex AI Reasoning Engine -> reasoning_engine -> Request Latency.

    3. En la sección Agregar filtros, configura filtros de forma opcional (como reasoning_engine_id, response_code).

    4. En la sección Transforma datos, activa o desactiva Ventana progresiva y Función de ventana progresiva en valores como 5min y 99th percentile (supervisa el percentil 99 de la latencia de la solicitud durante el período de alineación de 5 minutos).

    5. Haz clic en Siguiente.

  3. En la sección Configurar activador de alertas, haz lo siguiente:

    1. Selecciona Umbral en Tipos de condiciones.

    2. Selecciona un Activador de alertas, como Cualquier serie temporal es una infracción.

    3. Selecciona una Posición del umbral, como Umbral superior.

    4. Ingresa un valor de límite, como 5000ms.

    5. Haz clic en Siguiente.

  4. En la sección Configurar notificaciones y finalizar la alerta, haz lo siguiente:

    1. Selecciona uno o más canales de notificaciones. Consulta Administra canales de notificaciones para obtener más información.

    2. (Opcional) Configura el asunto de la notificación, la duración del cierre automático de incidentes, las etiquetas de la aplicación, las etiquetas de la política, el nivel de gravedad y la documentación adicional.

    3. Establece el nombre de la política en la sección Nombre de la política de alertas, como latency-99p-alert.

    4. Haz clic en Crear política.

En caso de un incidente, consulta Incidentes para políticas de alertas basadas en métricas para obtener más información sobre cómo confirmar y analizar el incidente, y silenciar la alerta.

Puedes encontrar más ejemplos de alertas en Políticas de ejemplo en JSON.

Supervisa las métricas de un agente

Puedes usar el panel Descripción general del motor de agentes de Vertex AI para supervisar el estado operativo y el rendimiento de tus agentes.

Cómo ver el panel predeterminado

  1. Ve a la página Paneles en la Google Cloud consola:

    Ir a Paneles

  2. Seleccionar tu Google Cloud proyecto.

  3. En el panel Mis paneles, agrega el filtro Name:Vertex AI Agent Engine Overview.

  4. Haz clic en Descripción general de Vertex AI Agent Engine para mostrar el panel predeterminado del agente.

Cómo personalizar el panel predeterminado

El panel predeterminado solo contiene las métricas integradas del agente. Para agregar tus propias métricas personalizadas al panel, sigue estos pasos para copiar y personalizar el panel predeterminado:

  1. Abre el panel predeterminado.

  2. Haz clic en Copiar panel. En el cuadro de diálogo Copiar panel, haz clic en Copiar. Se abrirá la copia del panel. También puedes encontrar la copia del panel en el panel Mis paneles, en la categoría Personalizado.

  3. En la copia del panel, sigue estos pasos para agregar una métrica:

    1. Haz clic en Agregar widget. Aparecerá el panel lateral Agregar widget.

    2. En Datos, selecciona Métrica. Aparecerá el panel lateral Configurar widget.

    3. Haz clic en Seleccionar una métrica para abrir una barra de búsqueda.

    4. Si tu métrica personalizada se crea con métricas basadas en registros, haz lo siguiente:

      1. Ingresa Vertex AI Reasoning Engine en la barra de búsqueda y haz clic en Vertex AI Reasoning Engine.

      2. Haz clic en la categoría de métrica Métricas basadas en registros y, luego, en una métrica, como Logging/user/tool_calling_count.

      3. Haz clic en Aplicar.

    5. Si tu métrica personalizada se crea con métricas definidas por el usuario, haz lo siguiente:

      1. Ingresa Nodo genérico en la barra de búsqueda y haz clic en Nodo genérico.

      2. Haz clic en la categoría de métrica Métricas personalizadas y, luego, en una métrica, como Cantidad de tokens.

      3. Haz clic en Aplicar.

    6. En el panel, aparecerá un gráfico nuevo que mostrará tu métrica personalizada.

  4. Puedes ajustar aún más el diseño del panel, por ejemplo:

    1. Para mover el widget, mantén presionado el título y arrástralo a otra ubicación en el mismo panel.

    2. Para cambiar el tamaño del widget, mantén presionada la esquina inferior derecha del widget y ajusta su tamaño.

Consulta Cómo agregar gráficos y tablas a un panel personalizado para obtener más detalles sobre cómo agregar gráficos de métricas con el Lenguaje de consulta de Monitoring (MQL) o el Lenguaje de consulta de Prometheus (PromQL), así como para tabularlas.

Si configuraste alertas personalizadas, consulta Cómo mostrar políticas de alertas y alertas en un panel para agregarlas a tu panel.