Monitorar um agente

Nesta página, descrevemos como usar métricas integradas, personalizadas e alertas para monitorar seus agentes no Vertex AI Agent Engine.

Visão geral

É possível usar o Vertex AI Agent Engine com o Cloud Monitoring sem nenhuma configuração extra. As métricas do agente integradas são coletadas e visualizadas automaticamente nas páginas do Cloud Monitoring no consoleGoogle Cloud .

Métricas integradas com suporte

As métricas de agente a seguir são compatíveis e associadas ao recurso monitorado do Vertex AI Agent Engine aiplatform.googleapis.com/ReasoningEngine:

  • Contagem de solicitações
  • Latências da solicitação
  • Tempo de alocação de CPU do contêiner
  • Tempo de alocação de memória do contêiner

Consulte a lista completa de métricas do AI Platform para mais detalhes sobre tipos, unidades, rótulos, latência e período de amostragem.

Conferir as métricas de um agente

É possível conferir as métricas integradas do agente no console Google Cloud usando o Metrics Explorer:

  1. Para receber a permissão de visualizar métricas no Metrics Explorer, peça ao administrador para conceder a você o papel de Leitor do Monitoring (roles/monitoring.viewer) no projeto.

  2. Acesse o Metrics Explorer no console Google Cloud :

    Acessar o Metrics Explorer

  3. Selecionar o projeto Google Cloud .

  4. Clique em Selecionar uma métrica para abrir uma barra de pesquisa.

  5. Digite Vertex AI Reasoning Engine na barra de pesquisa e clique em Vertex AI Reasoning Engine.

  6. Clique na categoria de métricas Reasoning_engine e em uma métrica, como Contagem de solicitações.

  7. Se preferir, defina outros filtros de rótulo, elemento de agregação e ajuste o período.

Por padrão, os gráficos no Metrics Explorer para a métrica Contagem de solicitações alinham os pontos de dados com um intervalo de tempo padrão e representam os pontos de dados como solicitações por segundo (uma métrica de taxa).

Consultar métricas de um agente

Também é possível consultar métricas usando a Linguagem de consulta do Monitoring (MQL), a Linguagem de consulta do Prometheus (PromQL) ou a API Cloud Monitoring v3. O MQL e o PromQL oferecem mais opções de filtragem, agregação e transformação de métricas, enquanto a API Cloud Monitoring permite listar e consultar de forma programática todos os pontos de dados brutos.

Consultar métricas com MQL ou PromQL

É possível usar MQL ou PromQL para alinhar e agregar pontos de dados com um intervalo de tempo personalizado e representar os pontos de dados transformados como a contagem de solicitações absolutas (em vez de solicitações 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]
)

É possível consultar a taxa de erros calculando a proporção das solicitações marcadas com determinados códigos de resposta de erro (como 500) para o número total de solicitações (porcentagem de solicitações com falha):

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 conferir as práticas recomendadas e as restrições de métricas de proporção, consulte Sobre as proporções das métricas. Para conferir um exemplo de como definir um alerta para a métrica de taxa de erros, consulte Políticas de amostra em JSON.

Consultar métricas com a API Cloud Monitoring

Você pode usar a API Cloud Monitoring para fazer o seguinte:

  • Receber a definição do recurso monitorado do Vertex AI Agent Engine

  • Listar as definições de métricas do agente disponíveis

  • Consultar dados de série temporal para request_count

Todas as métricas do agente são associadas ao recurso monitorado aiplatform.googleapis.com/ReasoningEngine do agente.

É possível invocar essas APIs pelo APIs Explorer, bibliotecas de cliente específicas da linguagem ou linha de comando. Consulte a documentação para ler as métricas pelo APIs Explorer e pelas bibliotecas de cliente. Os exemplos a seguir demonstram o uso na linha de comando, mais especificamente a ferramenta curl.

Acessar a definição do recurso monitorado do Agente do mecanismo

O comando a seguir recupera a definição do recurso monitorado usando projects.monitoredResourceDescriptors, além de todos os rótulos disponíveis que podem ser usados para filtrar:

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

Os rótulos precisam incluir resource_container, location e reasoning_engine_id.

Listar as definições de métricas do agente disponíveis

O comando a seguir usa projects.metricDescriptors para extrair todas as métricas e filtros de rótulos do agente:

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

O resultado precisa incluir a definição das métricas a seguir, além dos rótulos específicos:

  • 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 dados de série temporal para request_count

É possível usar projects.timeSeries.list com parâmetros como interval, filter e aggregation para consultar dados de séries temporais.

O exemplo a seguir mostra como consultar os pontos de dados brutos da métrica request_count de uma instância de agente específica durante um 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'

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • RESOURCE_ID: o ID da instância do mecanismo do agente. Isso nem sempre é necessário. É possível fazer consultas em várias instâncias do Agente Engine no mesmo projeto.
  • interval.startTime e interval.endTime: o início (inclusive) e o fim (exclusivo) do intervalo de tempo, no formato RFC 3339. Por exemplo, "2025-03-26T11:22:33Z" para o horário universal coordenado (UTC) e "2025-03-26T11:22:33-08:00" para o horário padrão do Pacífico (PST). Consulte a definição completa e mais exemplos na RFC 3339.

Você receberá uma resposta semelhante a esta:

{
  "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"
}

Consulte projects.timeSeries.list para mais detalhes sobre o formato da resposta.

Criar métricas personalizadas para um agente

Se as métricas integradas do agente não atenderem ao seu caso de uso específico, defina métricas personalizadas. É possível criar métricas personalizadas usando os seguintes métodos:

Métricas com base em registros

As etapas a seguir demonstram como criar e usar uma métrica com base em registros (tool_calling_count) para um fluxo de trabalho de exemplo em que vários agentes chamam várias ferramentas e você quer contar as invocações de ferramentas:

  1. Especifique a ferramenta para gravar uma entrada de registro toda vez que ela for chamada. Por exemplo, "tool-\<tool-id\> invoked by agent-\<agent-id\>".

  2. Crie uma nova métrica com base em registros do tipo contador no console Google Cloud :

    1. Acesse a página Métricas com base em registros no console Google Cloud :

      Acessar "Métricas com base em registros"

    2. Na seção Métricas definidas pelo usuário, clique em Criar métrica. O painel Criar métrica com base em registros é exibido.

    3. Em Tipo de métrica, selecione Contador.

    4. Na seção Detalhes, insira o Nome da métrica com base em registros. Por exemplo, tool_calling_count. Opcionalmente, insira a Descrição e as Unidades.

    5. Na seção Seleção de filtro, faça o seguinte:

      1. Na lista suspensa Selecionar bucket do projeto ou do registro, selecione Registros do projeto.

      2. No campo Criar filtro, insira o filtro de registro usando a linguagem de consulta de geração de registros. Exemplo:

        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. Na seção Rótulos, adicione dois novos rótulos clicando no botão Adicionar rótulo.

      1. Para o primeiro rótulo, faça o seguinte:

        1. No campo Nome do rótulo, insira tool.

        2. No campo Nome do campo, insira textPayload.

        3. No campo Expressão regular, insira (tool-\d+) invoked by agent-\d+.

      2. Para o segundo rótulo, faça o seguinte:

        1. No campo Nome do rótulo, insira agent.

        2. No campo Nome do campo, insira textPayload.

        3. No campo Expressão regular, insira tool-\d+ invoked by (agent-\d+).

      1. Clique em Concluído.

    7. Clique em Criar métrica.

  3. Para conferir a métrica tool_calling_count e os registros associados, faça o seguinte no console Google Cloud :

    1. Acesse a página Metrics Explorer no console Google Cloud :

      Acessar o Metrics Explorer

    2. Clique em Selecionar uma métrica para abrir uma barra de pesquisa.

    3. Digite Vertex AI Reasoning Engine na barra de pesquisa e clique em Vertex AI Reasoning Engine.

    4. Clique na categoria Métricas com base em registros e em Logging/user/tool_calling_count. Ajuste o período, se necessário.

    5. (Opcional) Filtre pelos rótulos tool e agent.

      • Para receber a contagem total de invocações de uma ferramenta específica para todos os agentes, defina o rótulo de filtro tool com o valor desse ID.

      • Para receber a contagem total de invocações de um agente específico para todas as ferramentas, defina o rótulo de filtro agent com o valor desse ID de agente.

      Se preferir, defina Soma por como tool ou agent para receber a contagem total dividida por ferramentas ou agentes diferentes.

Consulte Gerar registros de um agente para instruções sobre como gravar registros de agentes e Visão geral das métricas com base em registros para mais detalhes sobre as métricas com base em registros.

Métricas definidas pelo usuário

As etapas a seguir demonstram como criar e usar uma métrica definida pelo usuário (token_count) para um fluxo de trabalho de exemplo em que vários agentes chamam vários modelos e você quer calcular a contagem total de tokens consumidos (assumindo que você rastreia o número de tokens desde a inicialização do aplicativo para cada agente de invocação e modelo de destino):

  1. Defina o tipo de métrica personalizada chamando projects.metricDescriptors.create com os seguintes parâmetros:

    • name: uma string de URL, como projects/PROJECT_ID

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

      A nova métrica token_count é criada com o tipo Cumulative, representando o número total de tokens desde a inicialização do aplicativo. Consulte Tipos e classes de métricas para mais detalhes sobre as métricas Cumulative. Os identificadores model e agent representam o nome do modelo de linguagem grande (LLM) de destino e do agente de invocação.

    1. Você pode encontrar a métrica token_count no Metrics Explorer:

      1. Acesse a página Metrics Explorer no console Google Cloud :

      Acessar o Metrics Explorer

      1. Clique em Selecionar uma métrica para abrir uma barra de pesquisa.

      2. Digite Nó genérico na barra de pesquisa e clique em Métricas personalizadas.

      3. Clique em Contagem de tokens.

  2. Grave pontos de dados na nova métrica chamando projects.timeSeries.create com os seguintes parâmetros:

    • name: uma string de URL, como projects/PROJECT_ID

    • Request body: uma 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. Depois que os pontos de dados forem enviados pela API Cloud Monitoring, você poderá conferir a nova métrica token_count no console Google Cloud :

    1. Acesse a página Metrics Explorer no console Google Cloud :

      Acessar o Metrics Explorer

    2. Clique em Selecionar uma métrica para abrir uma barra de pesquisa.

    3. Digite Nó genérico na barra de pesquisa e clique em Métricas personalizadas.

    4. Clique em Contagem de tokens. Ajuste o período e configure os valores de rótulo para model ou agent, se necessário.

Criar alertas para um agente

Você pode usar métricas em combinação com alertas. Consulte Visão geral de alertas para mais detalhes.

O exemplo a seguir demonstra como criar um alerta de limite para a métrica request_latencies para receber notificações quando a latência ultrapassa um valor predefinido por um período especificado:

  1. Acesse a página Alertas no console Google Cloud :

    Acessar o alerta

  2. Clique em Criar política. A página Criar política de alertas é aberta.

    1. Em Modo de configuração da política, selecione Builder.

    2. No menu suspenso Selecionar uma métrica, selecione Vertex AI Reasoning Engine -> reasoning_engine -> Request Latency.

    3. Na seção Adicionar filtros, configure os filtros (por exemplo, reasoning_engine_id, response_code).

    4. Na seção Transformar dados, mude a Janela contínua e a Função de janela contínua para valores como 5min e 99th percentile (monitore o 99º percentil da latência da solicitação no período de alinhamento de cinco minutos).

    5. Clique em Próxima.

  3. Na seção Configurar o gatilho de alerta, faça o seguinte:

    1. Selecione Limite em Tipos de condição.

    2. Selecione um Gatilho de alerta, como Qualquer violação de série temporal.

    3. Selecione uma Posição do limite, como Acima do limite.

    4. Insira um valor limite, como 5000ms.

    5. Clique em Próxima.

  4. Na seção Configurar notificações e finalizar alerta, faça o seguinte:

    1. Selecione um ou mais canais de notificação. Consulte Gerenciar canais de notificação para mais detalhes.

    2. (Opcional) Configure o assunto da notificação, a duração do fechamento automático do incidente, os rótulos do aplicativo, os rótulos da política, o nível de gravidade e a documentação adicional.

    3. Defina o nome da política na seção Nomear a política de alertas, como latency-99p-alert.

    4. Clique em Criar política.

Em caso de incidente, consulte Incidentes para políticas de alertas baseadas em métricas para mais informações sobre como reconhecer e investigar o incidente e desativar o alerta.

Confira mais exemplos de alertas em Políticas de amostra em JSON.

Monitorar as métricas de um agente

Use o painel de visão geral do Vertex AI Agent Engine para monitorar a integridade operacional e o desempenho dos agentes.

Acessar o painel padrão

  1. Acesse a página Painéis no Google Cloud console:

    Ir para "Painéis"

  2. Selecionar o projeto Google Cloud .

  3. No painel Meus painéis, adicione o filtro Name:Vertex AI Agent Engine Overview.

  4. Clique em Visão geral do Vertex AI Agent Engine para mostrar o painel de agentes padrão.

Personalizar o painel padrão

O painel padrão contém apenas as métricas integradas do agente. Para adicionar suas próprias métricas personalizadas ao painel, siga estas etapas para copiar e personalizar o painel padrão:

  1. Abra o painel padrão.

  2. Clique em Copiar painel. Na caixa de diálogo Copiar painel, clique em Copiar. A cópia do painel é aberta. Você também pode encontrar a cópia do painel no painel Meus painéis, na categoria Personalizado.

  3. Na cópia do painel, siga estas etapas para adicionar uma métrica:

    1. Clique em Adicionar widget. O painel lateral Adicionar widget vai aparecer.

    2. Em Dados, selecione Métrica. O painel lateral Configurar widget será exibido.

    3. Clique em Selecionar uma métrica para abrir uma barra de pesquisa.

    4. Se a métrica personalizada for criada usando métricas com base em registros:

      1. Digite Vertex AI Reasoning Engine na barra de pesquisa e clique em Vertex AI Reasoning Engine.

      2. Clique na categoria Métricas com base em registros e selecione uma métrica, como Logging/user/tool_calling_count.

      3. Clique em Aplicar.

    5. Se a métrica personalizada for criada usando métricas definidas pelo usuário:

      1. Digite Nó genérico na barra de pesquisa e clique em Nó genérico.

      2. Clique na categoria Métricas personalizadas e em uma métrica, como Contagem de tokens.

      3. Clique em Aplicar.

    6. Um novo gráfico mostrando a métrica personalizada aparece no painel.

  4. Você pode ajustar ainda mais o layout do painel, por exemplo:

    1. Para mover o widget, mantenha o título dele pressionado e arraste para outro local no mesmo painel.

    2. Para redimensionar o widget, pressione o canto inferior direito dele e ajuste o tamanho.

Consulte Adicionar gráficos e tabelas a um painel personalizado para mais detalhes sobre como adicionar gráficos de métricas usando a Linguagem de consulta do Monitoring (MQL) ou a Linguagem de consulta do Prometheus (PromQL), além de como tabulá-las.

Se você configurou alertas personalizados, consulte Exibir políticas de alerta e alertas em um painel para adicionar esses alertas ao seu painel.