Monitorize um agente

Esta página descreve como usar métricas incorporadas, métricas personalizadas e alertas para monitorizar os seus agentes no Vertex AI Agent Engine.

Vista geral

Pode usar o Vertex AI Agent Engine com o Cloud Monitoring sem configuração adicional. As métricas do agente incorporadas são recolhidas e visualizadas automaticamente nas páginas do Cloud Monitoring naGoogle Cloud consola.

Métricas integradas suportadas

As seguintes métricas de agentes são suportadas e associadas ao recurso monitorizado do Vertex AI Agent Engine aiplatform.googleapis.com/ReasoningEngine:

  • Contagem de pedidos
  • Latências de pedidos
  • Tempo de atribuição da CPU do contentor
  • Tempo de atribuição de memória do contentor

Consulte a lista completa de métricas da AI Platform para mais detalhes sobre os tipos de métricas, as unidades, as etiquetas, bem como a latência e o período de amostragem.

Veja as métricas de um agente

Pode ver as métricas integradas do seu agente na Google Cloud consola através do Explorador de métricas:

  1. Para receber autorização para ver métricas no Explorador de métricas, peça ao seu administrador para lhe conceder a função de Leitor de monitorização (roles/monitoring.viewer) no seu projeto.

  2. Aceda ao Explorador de métricas na Google Cloud consola:

    Aceda ao Metrics Explorer

  3. Selecione o seu projeto do Google Cloud .

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

  5. Introduza 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, de seguida, clique numa métrica, como Request count.

  7. Opcionalmente, defina filtros de etiquetas adicionais, o elemento de agregação e ajuste o intervalo de tempo.

Por predefinição, os gráficos no Explorador de métricas para a métrica Número de pedidos alinham os pontos de dados com um intervalo de tempo predefinido e representam os pontos de dados como pedidos por segundo (uma métrica de taxa).

Consulte métricas de um agente

Também pode consultar métricas através do Idioma de consulta do Prometheus (PromQL) ou da API Cloud Monitoring v3. O PromQL oferece mais opções para filtragem, agregação e transformação de métricas, enquanto a API Cloud Monitoring permite listar e consultar programaticamente todos os pontos de dados brutos.

Consulte métricas com PromQL

Pode usar o PromQL para alinhar e agregar pontos de dados com um intervalo de tempo personalizado e representar graficamente pontos de dados transformados como a contagem absoluta de pedidos (em vez de pedidos por segundo). O exemplo seguinte filtra os dados por ID da instância do motor 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]
)

Pode consultar a taxa de erros calculando a proporção de pedidos etiquetados com determinados códigos de resposta de erro (como 500) em relação ao número total de pedidos (percentagem de pedidos com falhas):

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 ver práticas recomendadas e restrições para métricas de rácios, consulte o artigo Acerca dos rácios de métricas. Para ver um exemplo de como definir um alerta para a métrica Taxa de erros, consulte o artigo Políticas de exemplo em JSON.

Consulte métricas com a Cloud Monitoring API

Pode usar a API Cloud Monitoring para fazer o seguinte:

  • Obtenha a definição do recurso monitorizado do Vertex AI Agent Engine

  • Liste as definições de métricas de agentes disponíveis

  • Consultar dados de intervalos temporais para request_count

Todas as métricas do agente estão associadas ao recurso monitorizado do Agent Engine aiplatform.googleapis.com/ReasoningEngine.

Pode invocar estas APIs através do APIs Explorer, de bibliotecas de clientes específicas do idioma ou da linha de comandos. Consulte a documentação para ler métricas através do APIs Explorer e das bibliotecas cliente. Os exemplos seguintes demonstram a utilização na linha de comandos, mais especificamente na ferramenta curl.

Obtenha a definição do recurso monitorizado do motor do agente

O comando seguinte obtém a definição do recurso monitorizado através de projects.monitoredResourceDescriptors, bem como todas as etiquetas disponíveis que podem ser usadas para filtragem:

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

As etiquetas devem incluir resource_container, location e reasoning_engine_id.

Liste as definições de métricas de agentes disponíveis

O comando seguinte usa projects.metricDescriptors para obter todas as métricas e filtros de etiquetas para o Agent Engine:

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

O resultado deve incluir a definição das seguintes métricas, bem como as respetivas 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 dados de intervalos temporais para request_count

Pode usar projects.timeSeries.list juntamente com parâmetros como interval, filter e aggregation para consultar dados de séries cronológicas.

O exemplo seguinte mostra como consultar os pontos de dados não processados 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 o seguinte:

  • PROJECT_ID: o ID do seu Google Cloud projeto.
  • RESOURCE_ID: o ID da instância do motor do agente. Isto nem sempre é obrigatório. Pode consultar várias instâncias do Agent 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 Tempo Universal Coordenado (UTC) e "2025-03-26T11:22:33-08:00" para a Hora Padrão do Pacífico (PST). Consulte a definição completa e mais exemplos no RFC 3339.

Deve receber uma resposta semelhante à seguinte:

{
  "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 ver mais detalhes sobre o formato de resposta.

Crie métricas personalizadas para um agente

Se as métricas de agente incorporadas não abrangerem o seu caso de utilização específico, pode definir métricas personalizadas. Pode criar métricas personalizadas através dos seguintes métodos:

Métricas baseadas em registos

Os passos seguintes demonstram como criar e usar uma métrica baseada em registos (tool_calling_count) para um exemplo de fluxo de trabalho em que vários agentes chamam várias ferramentas e quer contabilizar as invocações de ferramentas:

  1. Especifique a sua ferramenta para escrever uma entrada de registo sempre que for chamada. Por exemplo, "tool-\<tool-id\> invoked by agent-\<agent-id\>".

  2. Crie uma nova métrica baseada em registos do tipo contador através da Google Cloud consola:

    1. Aceda à página Métricas baseadas em registos na Google Cloud consola:

      Aceda a Métricas baseadas em registos

    2. Na secção Métricas definidas pelo utilizador, clique em Criar métrica. É apresentado o painel Criar métrica baseada em registos.

    3. Para Tipo de métrica, selecione Contador

    4. Na secção Detalhes, introduza o nome da métrica baseada em registos. Por exemplo, tool_calling_count. Opcionalmente, introduza a Descrição e as Unidades.

    5. Para a secção Seleção de filtros, faça o seguinte:

      1. Na lista pendente Selecionar projeto ou contentor de registos, selecione Registos do projeto

      2. No campo Criar filtro, introduza o filtro de registo através da linguagem de consulta de registo. Por 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 secção Etiquetas, clique no botão Adicionar etiqueta para adicionar duas novas etiquetas.

      1. Para a primeira etiqueta, faça o seguinte:

        1. No campo Nome do marcador, introduza tool.

        2. No campo Nome do campo, introduza textPayload.

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

      2. Para a segunda etiqueta, faça o seguinte:

        1. No campo Nome do marcador, introduza agent.

        2. No campo Nome do campo, introduza textPayload.

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

      1. Clique em Concluído.

    7. Clique em Criar métrica.

  3. Para ver a métrica tool_calling_count e os respetivos registos associados, faça o seguinte na Google Cloud consola:

    1. Aceda à página Explorador de métricas na Google Cloud consola:

      Aceda ao Metrics Explorer

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

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

    4. Clique na categoria de métricas Métricas baseadas em registos e, de seguida, clique em Logging/user/tool_calling_count. Ajuste o intervalo de tempo, se necessário.

    5. (Opcional) Filtre pelas etiquetas tool e agent.

      • Para obter a contagem total de invocações de uma ferramenta específica para todos os agentes, defina a etiqueta de filtro tool com o valor do ID dessa ferramenta.

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

      Opcionalmente, defina a opção Soma por como tool ou agent para obter a contagem total discriminada por diferentes ferramentas ou agentes.

Consulte o artigo Registo de um agente para ver instruções sobre como escrever registos de agentes e o artigo Vista geral das métricas baseadas em registos para ver mais detalhes sobre as métricas baseadas em registos.

Métricas definidas pelo utilizador

Os passos seguintes demonstram como criar e usar uma métrica definida pelo utilizador (token_count) para um exemplo de fluxo de trabalho em que vários agentes chamam vários modelos e quer calcular a contagem total de tokens consumidos (partindo do princípio de que acompanha o número de tokens desde o início da aplicação 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, que representa o número total de tokens desde o início da aplicação. Consulte o artigo Tipos e categorias de métricas para ver mais detalhes sobre as métricas Cumulative. As etiquetas model e agent representam o nome do modelo de linguagem (conteúdo extenso) (MDL/CE) de destino e o agente de invocação.

    1. Pode encontrar a métrica token_count no Explorador de métricas:

      1. Aceda à página Explorador de métricas na Google Cloud consola:

      Aceda ao Metrics Explorer

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

      2. Introduza Generic node na barra de pesquisa e clique em Métricas personalizadas.

      3. Clique em Contagem de tokens.

  2. Escreva 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 de os pontos de dados serem carregados através da API Cloud Monitoring, pode ver a nova métrica token_count através da Google Cloud consola:

    1. Aceda à página Explorador de métricas na Google Cloud consola:

      Aceda ao Metrics Explorer

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

    3. Introduza Generic node na barra de pesquisa e clique em Métricas personalizadas.

    4. Clique em Contagem de tokens. Ajuste o intervalo de tempo e configure os valores das etiquetas para model ou agent, se necessário.

Crie alertas para um agente

Pode usar métricas em combinação com alertas. Consulte a Vista geral dos alertas para ver mais detalhes.

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

  1. Aceda à página Alertas na Google Cloud consola:

    Aceder a Alertas

  2. Clique em Criar política. É apresentada a página Criar política de alertas.

    1. Para o Modo de configuração da política, selecione Criador.

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

    3. Na secção Adicionar filtros, configure opcionalmente filtros (como reasoning_engine_id, response_code).

    4. Na secção Transformar dados, ative/desative Janela dinâmica e Função de janela dinâmica para valores como 5min e 99th percentile (monitorize o percentil 99 da latência de pedidos durante o período de alinhamento de 5 minutos).

    5. Clicar em Seguinte.

  3. Na secção Configurar acionador de alerta, faça o seguinte:

    1. Selecione Limite para Tipos de condições.

    2. Selecione um Acionador de alerta, como Qualquer série cronológica viola.

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

    4. Introduza um valor limite, como 5000ms.

    5. Clicar em Seguinte.

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

    1. Selecione um ou mais canais de notificação. Consulte o artigo Faça a gestão dos canais de notificação para mais detalhes.

    2. (Opcional) Configure o assunto da notificação, a duração do encerramento automático do incidente, as etiquetas da aplicação, as etiquetas da política, o nível de gravidade e documentação adicional.

    3. Defina o nome da política na secção Atribua um nome à política de alerta, como latency-99p-alert.

    4. Clique em Criar política.

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

Pode encontrar mais exemplos de alertas em Políticas de exemplo em JSON.

Monitorize métricas de um agente

Pode usar o painel de controlo Vista geral do Agent Engine da Vertex AI para monitorizar o estado operacional e o desempenho dos seus agentes.

Veja o painel de controlo predefinido

  1. Aceda à página Painéis de controlo na Google Cloud consola:

    Aceder a Painéis de controlo

  2. Selecione o seu projeto do Google Cloud .

  3. No painel Os meus painéis de controlo, adicione o filtro Name:Vertex AI Agent Engine Overview.

  4. Clique em Vista geral do Agent Engine da Vertex AI para apresentar o painel de controlo do agente predefinido.

Personalize o painel de controlo predefinido

O painel de controlo predefinido contém apenas as métricas incorporadas do agente. Para adicionar as suas próprias métricas personalizadas ao painel de controlo, siga os passos abaixo para copiar e personalizar o painel de controlo predefinido:

  1. Abra o painel de controlo predefinido.

  2. Clique em Copiar painel de controlo. Na caixa de diálogo Copiar painel de controlo, clique em Copiar. É aberta a cópia do painel de controlo. Também pode encontrar a cópia do painel de controlo no painel Os meus painéis de controlo na categoria Personalizado.

  3. Na cópia do painel de controlo, siga estes passos para adicionar uma métrica:

    1. Clique em Adicionar widget. É apresentado o painel lateral Adicionar widget.

    2. Para Dados, selecione Métrica. É apresentado o painel lateral Configurar widget.

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

    4. Se a sua métrica personalizada for criada com métricas baseadas em registos:

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

      2. Clique na categoria de métricas Baseadas em registos e, de seguida, clique numa métrica, como Logging/user/tool_calling_count.

      3. Clique em Aplicar.

    5. Se a sua métrica personalizada for criada com métricas definidas pelo utilizador:

      1. Introduza Generic Node na barra de pesquisa e clique em Generic Node.

      2. Clique na categoria de métricas Métricas personalizadas e, de seguida, clique numa métrica, como Contagem de tokens.

      3. Clique em Aplicar.

    6. É apresentado um novo gráfico com a sua métrica personalizada no painel de controlo.

  4. Pode ajustar ainda mais o esquema do painel de controlo, por exemplo:

    1. Mova o widget mantendo o título do widget premido e arrastando-o para outra localização no mesmo painel de controlo.

    2. Redimensione o widget premindo sem soltar o canto inferior direito do widget e ajustando o respetivo tamanho.

Consulte o artigo Adicione gráficos e tabelas a um painel de controlo personalizado para ver mais detalhes sobre como adicionar gráficos de métricas através da linguagem de consulta Prometheus (PromQL), bem como tabelar as suas métricas.

Se configurou alertas personalizados, consulte o artigo Apresente políticas de alerta e alertas num painel de controlo para adicionar esses alertas ao seu painel de controlo.