Supervisa un agente

En esta página, se describe cómo usar las métricas integradas, las métricas personalizadas y las 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 integradas del agente se recopilan y visualizan automáticamente en las páginas de Cloud Monitoring de la consola deGoogle Cloud .

Métricas integradas admitidas

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

  • 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, 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 consola de Google Cloud con el Explorador de métricas:

  1. Para obtener permiso para ver 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 consola de Google Cloud :

    Ir al Explorador de métricas

  3. Seleccionar tu Google Cloud proyecto.

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

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

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

  7. De manera opcional, puedes establecer filtros de etiquetas adicionales, un elemento de agregación y ajustar el intervalo.

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 representan como solicitudes por segundo (una métrica de frecuencia).

Consulta métricas de un agente

También puedes consultar las métricas a través del lenguaje de consulta de Prometheus (PromQL) o la API de Cloud Monitoring v3. PromQL ofrece 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 puntos de datos sin procesar.

Consulta métricas con PromQL

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

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]
)

Puedes consultar la tasa de errores calculando 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 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 conocer las prácticas recomendadas y las restricciones relacionadas con las métricas de proporción, consulta Acerca de las proporciones de métricas. Para ver un ejemplo de cómo establecer una alerta para la métrica de tasa de errores, 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 del recurso supervisado de Vertex AI Agent Engine

  • Enumera las definiciones de métricas del agente disponibles

  • Consultar datos de series temporales para request_count

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

Puedes invocar estas APIs a través del Explorador de APIs, las bibliotecas cliente específicas del 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, específicamente la herramienta curl.

Obtén la definición del recurso supervisado de Agent Engine

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.

Enumera las definiciones de métricas del agente disponibles

El siguiente comando usa projects.metricDescriptors para recuperar todos los filtros de etiquetas y métricas 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 para 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 puntos de datos sin procesar de la métrica request_count para una instancia de agente específica durante un período determinado:

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: Es el ID de la instancia de Agent Engine. No siempre es necesario. Puedes realizar consultas en varias instancias de Agent Engine dentro del mismo proyecto.
  • interval.startTime y interval.endTime: Son el inicio (inclusive) y el final (exclusive) del intervalo, 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 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 integradas del agente 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 contador a través de la Google Cloud consola:

    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 Crear filtro, ingresa el filtro de registros con el lenguaje de consulta de Logging. 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 Nombre de la etiqueta, 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 Nombre de la etiqueta, 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 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 Selecciona una métrica para abrir una barra de búsqueda.

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

    4. Haz clic en la categoría de métricas 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, establece 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 del ID de ese agente.

      De manera opcional, configura la opción Sum By 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 invocador y modelo objetivo):

  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 nueva métrica token_count se crea con el tipo Cumulative, que representa la cantidad total de tokens desde el inicio de la aplicación. Consulta Tipos y categorías 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) objetivo 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 Selecciona 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. Llama a projects.timeSeries.create con los siguientes parámetros para escribir puntos de datos en la métrica nueva:

    • 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 suben los puntos de datos a través de la API de Cloud Monitoring, puedes ver la nueva métrica 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 Selecciona 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 las etiquetas 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 de modo que recibas notificaciones cuando la latencia supere un valor predefinido durante un período específico:

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

    Ve a las alertas

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

    1. En Modo de configuración de políticas, selecciona Compilador.

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

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

    4. En la sección Transform data, activa Rolling window y Rolling window function para establecer valores como 5min y 99th percentile (supervisa el percentil 99 de la latencia de 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 condición.

    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 muestra en JSON.

Supervisa las métricas de un agente

Puedes usar el panel de descripción general de Vertex AI Agent Engine para supervisar el rendimiento y el estado operativo de tus agentes.

Visualiza el panel predeterminado

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

    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.

Personaliza 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 Selecciona una métrica para abrir una barra de búsqueda.

    4. Si tu métrica personalizada se creó con métricas basadas en registros, ten en cuenta 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étricas 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 creó con métricas definidas por el usuario, haz lo siguiente:

      1. Ingresa Generic Node en la barra de búsqueda y haz clic en Generic Node.

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

      3. Haz clic en Aplicar.

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

  4. También puedes ajustar 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 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 Prometheus (PromQL) y cómo tabular tus métricas.

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