Monitorizar un agente

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

Información general

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

Métricas integradas admitidas

Se admiten las siguientes métricas de agente, que están asociadas al recurso monitorizado aiplatform.googleapis.com/ReasoningEngine de Vertex AI Agent Engine:

• Número de solicitudes
• Latencias de solicitudes
• Tiempo de asignación de CPU del contenedor
• Tiempo de asignación de memoria de contenedor

Consulta la lista completa de métricas de AI Platform para obtener más información sobre los tipos de métricas, las unidades, las etiquetas, la latencia y el periodo de muestreo.

Ver las métricas de un agente

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

1. Para obtener permiso para ver métricas en Explorador de métricas, pide a tu administrador que te asigne el rol Lector de Monitoring (roles/monitoring.viewer) en tu proyecto.

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

   Ir a Explorador de métricas

3. Selecciona tu proyecto de Google Cloud .

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

5. Escribe Vertex AI Reasoning Engine en la barra de búsqueda y haz clic en Vertex AI Reasoning Engine.

6. Haga clic en la categoría de métrica Reasoning_engine y, a continuación, en una métrica, como Recuento de solicitudes.

7. También puedes definir filtros de etiquetas adicionales, un elemento de agregación y ajustar el periodo.

De forma predeterminada, los gráficos de Explorador de métricas de la métrica Número de solicitudes alinean los puntos de datos con un intervalo de tiempo predeterminado y los representan como solicitudes por segundo (una métrica de tasa).

Nota: Las etiquetas se clasifican como etiquetas de recursos (comunes a todas las métricas, como resource_container, location y reasoning_engine_id) o etiquetas de métricas (específicas de métricas concretas, como response_code para la métrica Recuento de solicitudes). Consulta Componentes del modelo de métricas para obtener más información sobre las etiquetas.

Consultar métricas de un agente

También puedes consultar métricas a través de Prometheus Query Language (PromQL) o de la API Cloud Monitoring v3. PromQL ofrece más opciones para filtrar, agregar y transformar métricas, mientras que la API Cloud Monitoring te permite enumerar y consultar de forma programática todos los puntos de datos sin procesar.

Consultar métricas con PromQL

Puedes usar PromQL para alinear y agregar puntos de datos con un intervalo de tiempo personalizado y representar los puntos de datos transformados como el recuento de solicitudes absoluto (en lugar de solicitudes por segundo). En el siguiente ejemplo, se filtran los datos por ID de instancia de Agent Engine (RESOURCE_ID) y código de respuesta (RESPONSE_CODE):

Nota: En las consultas de PromQL del explorador de métricas, el intervalo de tiempo predeterminado se representa con ${__interval} y se configura automáticamente en función del intervalo de tiempo. El valor de ${__interval} es proporcional al intervalo de tiempo seleccionado. Si consultas la métrica durante un periodo más largo, el valor de ${__interval} se configura dinámicamente con un valor mayor. Consulta Alineación: regularización en la serie para obtener más información sobre la alineación de series temporales.

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 solicitudes etiquetadas con determinados códigos de respuesta de error (como 500) con respecto al número total de solicitudes (porcentaje de solicitudes fallidas):

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 consultar las prácticas recomendadas y las restricciones de las métricas de ratio, consulte el artículo Acerca de los ratios de métricas. Para ver un ejemplo de cómo definir una alerta para la métrica de tasa de errores, consulta Ejemplos de políticas en JSON.

Consultar métricas con la API de Cloud Monitoring

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

• Obtener la definición de recurso monitorizado de Vertex AI Agent Engine

• Lista de definiciones de métricas de agente disponibles

• Consultar datos de series temporales de request_count

Todas las métricas de agente están asociadas al recurso monitorizado Agent Engine aiplatform.googleapis.com/ReasoningEngine.

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

Nota: Debes autenticar tus solicitudes al llamar a la API con curl. Consulta Autenticación para usar REST para obtener más información. Este alias de shell puede ser útil: $ alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'.

Obtener la definición del recurso monitorizado de Agent Engine

El siguiente comando obtiene la definición del recurso monitorizado mediante 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 obtener 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

Consultar datos de series temporales de request_count

Puede 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 puntos de datos sin procesar de la métrica request_count de una instancia de agente específica durante un periodo concreto:

Nota: Algunos caracteres deben tener codificación URL.

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'

Haz los cambios siguientes:

• PROJECT_ID: tu ID de proyecto Google Cloud .
• RESOURCE_ID: ID de instancia de Agent Engine. No siempre es obligatorio. Puedes hacer consultas en varias instancias de Agent Engine del mismo proyecto.
• interval.startTime y interval.endTime: el inicio (inclusive) y el final (exclusive) del intervalo de tiempo, en formato RFC 3339. Por ejemplo, "2025-03-26T11:22:33Z" para el tiempo universal coordinado (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 RFC 3339.

Deberías recibir una respuesta similar a la siguiente:

{
  "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 información sobre el formato de la respuesta.

Crear métricas personalizadas para un agente

Si las métricas de agente predefinidas no se ajustan a tu caso de uso específico, puedes definir métricas personalizadas. Puede crear métricas personalizadas con los siguientes métodos:

• Métricas basadas en registros: observa las tendencias y los patrones de un gran volumen de entradas de registro.

• Métricas definidas por el usuario: métricas que no están definidas por Google Cloud, como la captura de datos específicos de la aplicación o datos del sistema del lado del cliente.

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) en un flujo de trabajo de ejemplo en el que varios agentes llaman a varias herramientas y quieres contar las invocaciones de herramientas:

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

2. Crea una métrica basada en registros de tipo contador mediante la Google Cloud consola:

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

      Ir a Métricas basadas en registros

   2. En la sección Métricas definidas por el usuario, haga 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, introduce el nombre de la métrica basada en registros. Por ejemplo, tool_calling_count. Si quiere, puede introducir la Descripción y las Unidades.

   5. En la sección Selección de filtros, haga lo siguiente:

      1. En la lista desplegable Seleccionar proyecto o contenedor de registro, selecciona Registros del proyecto.

      2. En el campo Crear filtro, introduce 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, añade dos etiquetas nuevas haciendo clic en el botón Añadir etiqueta.

      1. Para la primera etiqueta, haz lo siguiente:

         1. En el campo Nombre de la etiqueta, introduce tool.

         2. En el campo Nombre del campo, introduce textPayload.

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

      2. Para la segunda etiqueta, haz lo siguiente:

         1. En el campo Nombre de la etiqueta, introduce agent.

         2. En el campo Nombre del campo, introduce textPayload.

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

      Nota: Si estos registros de invocación de herramientas ya están disponibles en el proyecto, haz clic en Vista previa para probar las expresiones regulares de tool y agent.
      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 Google Cloud consola:

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

      Ir a Explorador de métricas

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

   3. Escribe Vertex AI Reasoning Engine en la barra de búsqueda y haz clic en Vertex AI Reasoning Engine.

   4. Haga clic en la categoría de métrica Métricas basadas en registros y, a continuación, en Logging/user/tool_calling_count. Ajusta el periodo si es necesario.

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

      • Para obtener el número total de invocaciones de una herramienta específica para todos los agentes, asigna a la etiqueta de filtro tool el valor del ID de esa herramienta.

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

      También puedes definir Sum By (Sumar por) como tool o agent para obtener el recuento total desglosado por diferentes herramientas o agentes.

Nota: Las nuevas métricas basadas en registros se asocian al mismo recurso monitorizado por el agente aiplatform.googleapis.com/ReasoningEngine, por lo que puedes usar etiquetas como reasoning_engine_id para filtrar y agregar datos.

Consulta Registrar un agente para obtener instrucciones sobre cómo escribir registros de agentes y Información general sobre 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 pasos siguientes se muestra cómo crear y usar una métrica definida por el usuario (token_count) en un flujo de trabajo de ejemplo en el que varios agentes llaman a varios modelos y quieres calcular el recuento total de tokens consumidos (suponiendo que monitorizas el número de tokens desde el inicio de la aplicación para cada agente y modelo de destino que se invoca):

1. Defina el tipo de métrica personalizada llamando a projects.metricDescriptors.create con los siguientes parámetros:

   • name: 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 nueva métrica token_count se crea con el tipo Cumulative, que representa el número total de tokens desde el inicio de la aplicación. Consulta más información sobre los tipos y clases de métricas de Cumulative. Las etiquetas model y agent representan el nombre del modelo de lenguaje extenso (LLM) de destino y del agente de invocación.

   1. Puede encontrar la métrica token_count en el explorador de métricas:

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

      Ir a Explorador de métricas

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

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

      3. Haz clic en Recuento de tokens.

   Nota: Solo tiene que hacer este paso una vez.

2. Escribe puntos de datos en la nueva métrica llamando a projects.timeSeries.create con los siguientes parámetros:

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

   • Request body: 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 ...
       ]
     }
     

     Nota: Cada combinación de los valores de la etiqueta forma una serie temporal, que debe registrarse individualmente en la solicitud projects.timeSeries.create. Este paso debe realizarse periódicamente desde tu código. El recuento value no disminuye hasta que se restablece a cero al reiniciar la aplicación. Consulta las métricas de CUMULATIVE en TimeInterval para ver los requisitos específicos de startTime y endTime.

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

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

      Ir a Explorador de métricas

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

   3. Escribe 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 periodo y configura los valores de las etiquetas de model o agent si es necesario.

Nota: Las métricas definidas por el usuario nuevas no están asociadas al recurso monitorizado Agent Engine aiplatform.googleapis.com/ReasoningEngine. Consulta el artículo Descripción general de las métricas definidas por el usuario para obtener más información sobre cómo crear y usar métricas definidas por el usuario.

Crear alertas para un agente

Puede usar métricas en combinación con alertas. Consulta más información en el resumen de las alertas.

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

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

   Ir a Alertas

2. Haz clic enCreate Policy (Crear política). Se abrirá la página Crear política de alertas.

   1. En Modo de configuración de la política, selecciona Creador.

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

   3. En la sección Añadir filtros, puede configurar filtros (como reasoning_engine_id o response_code).

   4. En la sección Transform data (Transformar datos), activa Rolling window (Ventana móvil) y Rolling window function (Función de ventana móvil) para asignarles valores como 5min y 99th percentile (monitoriza el percentil 99 de la latencia de las solicitudes durante el periodo de alineación de 5 minutos).

   5. Haz clic en Siguiente.

3. En la sección Configurar activador de alerta, haga lo siguiente:

   1. Selecciona Umbral en Tipos de condición.

   2. Seleccione un Activador de alerta, como Cualquier serie temporal infringe.

   3. Selecciona una posición del umbral, como Por encima del umbral.

   4. Introduce un valor de umbral, como 5000ms.

   5. Haz clic en Siguiente.

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

   1. Selecciona uno o varios canales de notificación. Consulta más información en el artículo Gestionar canales de notificación.

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

   3. En la sección Dar nombre a la política de alertas, asigna un nombre a la política, como latency-99p-alert.

   4. Haz clic en Crear política.

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

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

Monitorizar métricas de un agente

Puedes usar el panel de control Vista general de Vertex AI Agent Engine para monitorizar el estado operativo y el rendimiento de tus agentes.

Ver el panel de control predeterminado

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

   Ir a Paneles

2. Selecciona tu proyecto de Google Cloud .

3. En el panel Mis paneles de control, añade el filtro Name:Vertex AI Agent Engine Overview.

4. Haga clic en Resumen de Vertex AI Agent Engine para ver el panel de control del agente predeterminado.

Personalizar el panel de control predeterminado

El panel de control predeterminado solo contiene las métricas integradas del agente. Para añadir sus propias métricas personalizadas al panel de control, siga estos pasos para copiar y personalizar el panel predeterminado:

1. Abre el panel de control predeterminado.

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

3. En la copia del panel de control, sigue estos pasos para añadir una métrica:

   1. Haz clic en Añadir widget. Aparecerá el panel lateral Añadir 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:

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

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

      3. Haz clic en Aplicar.

   5. Si su métrica personalizada se crea con métricas definidas por el usuario:

      1. Escribe Generic Node (Nodo genérico) en la barra de búsqueda y haz clic en Generic Node.

      2. Haga clic en la categoría de métrica Métricas personalizadas y, a continuación, en una métrica, como Recuento de tokens.

      3. Haz clic en Aplicar.

   6. En el panel de control se muestra un nuevo gráfico con la métrica personalizada.

4. También puedes ajustar el diseño del panel de control. Por ejemplo:

   1. Para mover un widget, mantén pulsado su título y arrástralo a otra ubicación del mismo panel de control.

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

Consulta Añadir gráficos y tablas a un panel de control personalizado para obtener más información sobre cómo añadir gráficos de métricas con Prometheus Query Language (PromQL), así como tabular tus métricas.

Si ha configurado alertas personalizadas, consulte el artículo Mostrar políticas y alertas en un panel de control para añadir estas alertas a su panel de control.