Monitorar um agente

Nesta página, descrevemos como usar métricas integradas, métricas 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 configuração adicional. As métricas do agente integrado são coletadas e visualizadas automaticamente nas páginas do Cloud Monitoring no console doGoogle Cloud .

Métricas integradas com suporte

As seguintes métricas de agente 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 da 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 de métricas, unidades, rótulos, além de latência e período de amostragem.

Conferir métricas de um agente

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

  1. Para ter permissão para ver métricas no Explorador de métricas, peça ao administrador para conceder a você o papel de Leitor do Monitoring (roles/monitoring.viewer) no seu 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 Reasoning Engine do Vertex AI Agent Builder na barra de pesquisa e clique em Reasoning Engine do Vertex AI Agent Builder.

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

  7. Se quiser, defina outros filtros de rótulo, um 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 pontos de dados com um intervalo de tempo padrão e representam pontos de dados como solicitações por segundo (uma métrica de taxa).

Para agentes baseados no Kit de Desenvolvimento de Agente, também é possível conferir as métricas do agente no console do Google Cloud usando o painel do Vertex AI Agent Engine.

Consultar métricas de um agente

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

Consultar métricas com PromQL

Você pode usar o PromQL para alinhar e agregar pontos de dados com um intervalo de tempo personalizado e representar pontos de dados transformados como a contagem absoluta de solicitações (em vez de solicitações por segundo). O exemplo a seguir filtra os dados por ID da instância do mecanismo do agente (RESOURCE_ID) e código de resposta (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]
)

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

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 restrições das métricas de proporção, consulte Sobre as proporções de métricas. Para 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

Com a API Cloud Monitoring, é possível 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 de agente estão associadas ao recurso monitorado do Agent Engine aiplatform.googleapis.com/ReasoningEngine.

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

Receber a definição do recurso monitorado do Agent Engine

O comando a seguir recupera a definição do recurso monitorado usando projects.monitoredResourceDescriptors, bem como todos os rótulos disponíveis que podem ser usados para filtragem:

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 recuperar todas as métricas e filtros de rótulo do Agent Engine:

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 seguintes métricas e seus 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érie temporal.

O exemplo a seguir mostra como consultar os pontos de dados brutos da métrica request_count para 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 Agent Engine. Nem sempre é obrigatório. É possível consultar várias instâncias do Agent Engine no mesmo projeto.
  • interval.startTime e interval.endTime: o início (inclusivo) e o fim (exclusivo) do intervalo de tempo, no formato RFC 3339. Por exemplo, "2025-03-26T11:22:33Z" para o Tempo 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, você poderá definir métricas personalizadas. É possível criar métricas personalizadas usando os seguintes métodos:

Métricas com base em registros

As etapas a seguir mostram 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 sua ferramenta para gravar uma entrada de registro sempre que ela for chamada. Por exemplo, "tool-\<tool-id\> invoked by agent-\<agent-id\>".

  2. Crie uma 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 aparece.

    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 filtros, faça o seguinte:

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

      2. No campo Criar filtro, insira o filtro de registros usando a linguagem de consulta do Logging. 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 Reasoning Engine do Vertex AI Agent Builder na barra de pesquisa e clique em Reasoning Engine do Vertex AI Agent Builder.

    4. Clique na categoria de métrica 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 do filtro tool com o valor do ID dessa ferramenta.

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

      Se quiser, defina a opção Somar por como tool ou agent para receber a contagem total dividida por diferentes ferramentas ou agentes.

Consulte Registrar 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 essas métricas.

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 (supondo que você acompanhe 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 de métricas para mais detalhes sobre as métricas Cumulative. Os rótulos 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 por upload pela API Cloud Monitoring, você poderá conferir a nova métrica token_count no console do 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

É possível 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 que você receba notificações quando a latência ultrapassar um valor predefinido por um período especificado:

  1. Acesse a página Alertas no console do 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 Criador.

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

    3. Na seção Adicionar filtros, configure filtros opcionais, como reasoning_engine_id e response_code.

    4. Na seção Transformar dados, alterne Janela contínua e Função de janela contínua para valores como 5min e 99th percentile. Isso monitora o 99º percentil da latência da solicitação durante o 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 para 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 de aplicativo e de 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 baseados em métricas para mais informações sobre como confirmar e investigar o incidente e silenciar o alerta.

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

Monitorar métricas de um agente

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

Acessar o painel padrão

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

    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 Agent Engine da Vertex AI para mostrar o painel padrão do agente.

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 será 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 vai aparecer.

    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 Reasoning Engine do Vertex AI Agent Builder na barra de pesquisa e clique em Reasoning Engine do Vertex AI Agent Builder.

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

      3. Clique em Aplicar.

    5. Se a métrica personalizada foi 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 de métrica Métricas personalizadas e em uma métrica, como Contagem de tokens.

      3. Clique em Aplicar.

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

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

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

    2. Para redimensionar o widget, pressione o canto inferior direito 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 Prometheus (PromQL) e como tabular suas métricas.

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