Monitorare un agente

Questa pagina descrive come utilizzare metriche, metriche personalizzate e avvisi integrati per monitorare gli agenti in Vertex AI Agent Engine.

Panoramica

Puoi utilizzare Vertex AI Agent Engine con Cloud Monitoring senza configurazioni aggiuntive. Le metriche dell'agente integrate vengono raccolte e visualizzate automaticamente nelle pagine di Cloud Monitoring nella consoleGoogle Cloud .

Metriche integrate supportate

Le seguenti metriche dell'agente sono supportate e associate alla risorsa monitorata Vertex AI Agent Engine aiplatform.googleapis.com/ReasoningEngine:

  • Conteggio delle richieste
  • Latenze di richiesta
  • Tempo di allocazione CPU container
  • Tempo di allocazione della memoria del container

Per ulteriori dettagli su tipi, unità ed etichette delle metriche, nonché su latenza e periodo di campionamento, consulta l'elenco completo delle metriche di AI Platform.

Visualizzare le metriche per un agente

Puoi visualizzare le metriche integrate dell'agente nella console Google Cloud utilizzando Esplora metriche:

  1. Per ottenere l'autorizzazione a visualizzare le metriche in Metrics Explorer, chiedi all'amministratore di concederti il ruolo Visualizzatore Monitoring (roles/monitoring.viewer) sul progetto.

  2. Vai a Esplora metriche nella console Google Cloud :

    Vai a Esplora metriche

  3. Selezionare il tuo progetto Google Cloud .

  4. Fai clic su Seleziona una metrica per aprire una barra di ricerca.

  5. Inserisci Vertex AI Reasoning Engine nella barra di ricerca e fai clic su Vertex AI Reasoning Engine.

  6. Fai clic sulla categoria di metriche Reasoning_engine, poi su una metrica, ad esempio Conteggio richieste.

  7. (Facoltativo) Imposta filtri per le etichette aggiuntivi, l'elemento di aggregazione e regola l'intervallo di tempo.

Per impostazione predefinita, i grafici in Metrics Explorer per la metrica Conteggio richieste allineano i punti dati a un intervallo di tempo predefinito e tracciano i punti dati come richieste al secondo (una metrica di frequenza).

Metriche delle query per un agente

Puoi anche eseguire query sulle metriche tramite Prometheus Query Language (PromQL) o API Cloud Monitoring v3. PromQL offre più opzioni per il filtraggio, l'aggregazione e la trasformazione delle metriche, mentre l'API Cloud Monitoring consente di elencare ed eseguire query in modo programmatico su tutti i punti di dati non elaborati.

Eseguire query sulle metriche con PromQL

Puoi utilizzare PromQL per allineare e aggregare i punti dati con un intervallo di tempo personalizzato e tracciare i punti dati trasformati come conteggio assoluto delle richieste (anziché richieste al secondo). L'esempio seguente filtra i dati in base all'ID istanza del motore dell'agente (RESOURCE_ID) e al codice di risposta (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]
)

Puoi eseguire query sulla percentuale di errori calcolando il rapporto tra le richieste etichettate con determinati codici di risposta agli errori (ad esempio 500) e il numero totale di richieste (percentuale di richieste non riuscite):

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

Per best practice e limitazioni per le metriche di rapporto, consulta Informazioni sui rapporti tra metriche. Per un esempio di come impostare un avviso per la metrica Tasso di errore, consulta Policy di esempio in formato JSON.

Eseguire query sulle metriche con l'API Cloud Monitoring

Puoi utilizzare l'API Cloud Monitoring per:

  • Recupera la definizione della risorsa monitorata di Vertex AI Agent Engine

  • Elenco delle definizioni delle metriche dell'agente disponibili

  • Esegui query sui dati delle serie temporali per request_count

Tutte le metriche dell'agente sono associate alla risorsa monitorata di Agent Engine aiplatform.googleapis.com/ReasoningEngine.

Puoi richiamare queste API tramite Explorer API, librerie client specifiche per i vari linguaggi o la riga di comando. Consulta la documentazione per leggere le metriche tramite Explorer API e le librerie client. Gli esempi riportati di seguito mostrano l'utilizzo nella riga di comando, in particolare dello strumento curl.

Recupera la definizione della risorsa monitorata del motore dell'agente

Il comando seguente recupera la definizione della risorsa monitorata utilizzando projects.monitoredResourceDescriptors, nonché tutte le etichette disponibili che possono essere utilizzate per il filtraggio:

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

Le etichette devono includere resource_container, location e reasoning_engine_id.

Elenco delle definizioni delle metriche dell'agente disponibili

Il seguente comando utilizza projects.metricDescriptors per recuperare tutti i filtri per metriche ed etichette per Agent Engine:

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

Il risultato deve includere la definizione delle seguenti metriche e le relative etichette specifiche:

  • 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

Esegui query sui dati delle serie temporali per request_count

Puoi utilizzare projects.timeSeries.list insieme a parametri come interval, filter e aggregation per eseguire query sui dati delle serie temporali.

L'esempio seguente mostra come eseguire query sui punti dati non elaborati per la metrica request_count per un'istanza agente specifica durante un intervallo di tempo specifico:

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'

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • RESOURCE_ID: l'ID istanza del motore agente. Questo non è sempre obbligatorio. Puoi eseguire query su più istanze di Agent Engine all'interno dello stesso progetto.
  • interval.startTime e interval.endTime: l'inizio (incluso) e la fine (esclusa) dell'intervallo di tempo, nel formato RFC 3339. Ad esempio, "2025-03-26T11:22:33Z" per il fuso orario UTC (Coordinated Universal Time) e "2025-03-26T11:22:33-08:00" per il fuso orario PST (Pacific Standard Time). Consulta la definizione completa e altri esempi nella RFC 3339.

Dovresti ricevere una risposta simile alla seguente:

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

Per ulteriori dettagli sul formato della risposta, consulta projects.timeSeries.list.

Creare metriche personalizzate per un agente

Se le metriche dell'agente integrate non coprono il tuo caso d'uso specifico, puoi definire metriche personalizzate. Puoi creare metriche personalizzate utilizzando i seguenti metodi:

  • Metriche basate su log: osserva tendenze e pattern in un volume elevato di voci di log.

  • Metriche definite dall'utente: metriche non definite da Google Cloud, ad esempio l'acquisizione di dati specifici dell'applicazione o di dati di sistema lato client.

Metriche basate su log

I seguenti passaggi mostrano come creare e utilizzare una metrica basata su log (tool_calling_count) per un flusso di lavoro di esempio in cui più agenti chiamano più strumenti e vuoi conteggiare le chiamate agli strumenti:

  1. Specifica lo strumento per scrivere una voce di log ogni volta che viene chiamato. Ad esempio, "tool-\<tool-id\> invoked by agent-\<agent-id\>".

  2. Crea una nuova metrica dei contatori basata su log tramite la console Google Cloud :

    1. Vai alla pagina Metriche basate su log nella console Google Cloud :

      Vai a Metriche basate su log

    2. Nella sezione Metriche definite dall'utente, fai clic su Crea metrica. Viene visualizzato il riquadro Crea metrica basata su log.

    3. Per Tipo di metrica, seleziona Contatore.

    4. Nella sezione Dettagli, inserisci il Nome metrica basata su log. Ad esempio, tool_calling_count. (Facoltativo) Inserisci la Descrizione e le Unità.

    5. Per la sezione Selezione filtro, segui questi passaggi:

      1. Nell'elenco a discesa Seleziona il bucket di progetto o di log, seleziona Log di progetto.

      2. Nel campo Crea filtro, inserisci il filtro dei log utilizzando il linguaggio di query di logging. Ad esempio:

        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. Per la sezione Etichette, aggiungi due nuove etichette facendo clic sul pulsante Aggiungi etichetta.

      1. Per la prima etichetta:

        1. Nel campo Nome etichetta, inserisci tool.

        2. Nel campo Nome campo, inserisci textPayload.

        3. Nel campo Espressione regolare, inserisci (tool-\d+) invoked by agent-\d+.

      2. Per la seconda etichetta:

        1. Nel campo Nome etichetta, inserisci agent.

        2. Nel campo Nome campo, inserisci textPayload.

        3. Nel campo Espressione regolare, inserisci tool-\d+ invoked by (agent-\d+).

      1. Fai clic su Fine.

    7. Fai clic su Crea metrica.

  3. Per visualizzare la metrica tool_calling_count e i log associati, segui questi passaggi nella console Google Cloud :

    1. Vai alla pagina Esplora metriche nella console Google Cloud :

      Vai a Esplora metriche

    2. Fai clic su Seleziona una metrica per aprire una barra di ricerca.

    3. Inserisci Vertex AI Reasoning Engine nella barra di ricerca e fai clic su Vertex AI Reasoning Engine.

    4. Fai clic sulla categoria di metriche Metriche basate su log, poi fai clic su Logging/user/tool_calling_count. Se necessario, regola l'intervallo di tempo.

    5. (Facoltativo) Filtra in base alle etichette tool e agent.

      • Per ottenere il conteggio totale delle invocazioni per uno strumento specifico per tutti gli agenti, imposta l'etichetta del filtro tool con il valore dell'ID dello strumento.

      • Per ottenere il conteggio totale delle chiamate per un agente specifico per tutti gli strumenti, imposta l'etichetta del filtro agent con il valore dell'ID agente.

      (Facoltativo) Imposta Somma per su tool o agent per ottenere il conteggio totale suddiviso per diversi strumenti o agenti.

Consulta Logging di un agente per istruzioni su come scrivere i log dell'agente e la panoramica delle metriche basate su log per ulteriori dettagli sulle metriche basate su log.

Metriche definite dall'utente

I seguenti passaggi mostrano come creare e utilizzare una metrica definita dall'utente (token_count) per un flusso di lavoro di esempio in cui più agenti chiamano più modelli e tu vuoi calcolare il conteggio totale dei token utilizzati (supponendo di monitorare il numero di token dall'avvio dell'applicazione per ogni agente chiamante e modello di destinazione):

  1. Definisci il tipo di metrica personalizzata chiamando projects.metricDescriptors.create con i seguenti parametri:

    • name: una stringa URL, ad esempio projects/PROJECT_ID

    • Request body: un oggetto 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 nuova metrica token_count viene creata con il tipo Cumulative, che rappresenta il numero totale di token dall'avvio dell'applicazione. Per ulteriori dettagli sulle metriche Cumulative, consulta la sezione Tipi e generi di metriche. Le etichette model e agent rappresentano il nome del modello linguistico di grandi dimensioni (LLM) di destinazione e dell'agente chiamante.

    1. Puoi trovare la metrica token_count in Esplora metriche:

      1. Vai alla pagina Esplora metriche nella console Google Cloud :

      Vai a Esplora metriche

      1. Fai clic su Seleziona una metrica per aprire una barra di ricerca.

      2. Inserisci Nodo generico nella barra di ricerca e fai clic su Metriche personalizzate.

      3. Fai clic su Conteggio token.

  2. Scrivi i punti dati nella nuova metrica chiamando projects.timeSeries.create con i seguenti parametri:

    • name: una stringa URL, ad esempio projects/PROJECT_ID

    • Request body: un elenco di oggetti 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 volta caricati i punti dati tramite l'API Cloud Monitoring, puoi visualizzare la nuova metrica token_count tramite la console Google Cloud :

    1. Vai alla pagina Esplora metriche nella console Google Cloud :

      Vai a Esplora metriche

    2. Fai clic su Seleziona una metrica per aprire una barra di ricerca.

    3. Inserisci Nodo generico nella barra di ricerca e fai clic su Metriche personalizzate.

    4. Fai clic su Conteggio token. Modifica l'intervallo di tempo e configura i valori delle etichette per model o agent, se necessario.

Crea avvisi per un agente

Puoi utilizzare le metriche in combinazione con gli avvisi. Per ulteriori dettagli, vedi Panoramica degli avvisi.

L'esempio seguente mostra come creare un avviso di soglia per la metrica request_latencies in modo da ricevere notifiche quando la latenza supera un valore predefinito per una durata specificata:

  1. Vai alla pagina Avvisi nella console Google Cloud :

    Vai ad Avvisi

  2. Fai clic su Crea criterio. Viene visualizzata la pagina Crea policy di avviso.

    1. In Modalità di configurazione delle norme, seleziona Generatore.

    2. Nel menu a discesa Seleziona una metrica, seleziona Vertex AI Reasoning Engine -> reasoning_engine -> Request Latency.

    3. Nella sezione Aggiungi filtri, configura facoltativamente i filtri (ad esempio reasoning_engine_id, response_code).

    4. Nella sezione Trasforma i dati, imposta Finestra mobile e Funzione finestra mobile su valori come 5min e 99th percentile (monitora il 99° percentile della latenza delle richieste nel periodo di allineamento di 5 minuti).

    5. Fai clic su Avanti.

  3. Nella sezione Configura trigger avviso, segui questi passaggi:

    1. Seleziona Soglia per Tipi di condizione.

    2. Seleziona un Attivatore di avvisi, ad esempio Qualsiasi violazione della serie temporale.

    3. Seleziona una Posizione soglia, ad esempio Sopra la soglia.

    4. Inserisci un valore di soglia, ad esempio 5000ms.

    5. Fai clic su Avanti.

  4. Nella sezione Configura le notifiche e finalizza l'avviso, segui questi passaggi:

    1. Seleziona uno o più canali di notifica. Per saperne di più, consulta la pagina Gestire i canali di notifica.

    2. (Facoltativo) Configura l'oggetto della notifica, la durata della chiusura automatica dell'incidente, le etichette dell'applicazione, le etichette delle policy, il livello di gravità e la documentazione aggiuntiva.

    3. Imposta il nome della policy nella sezione Assegna un nome alla policy di avviso, ad esempio latency-99p-alert.

    4. Fai clic su Crea criterio.

In caso di incidente, consulta Incidenti per le policy di avviso basate su metriche per saperne di più su come riconoscere e analizzare l'incidente e disattivare l'avviso.

Puoi trovare altri esempi di avvisi in Policy di esempio in formato JSON.

Monitorare le metriche per un agente

Puoi utilizzare la dashboard Panoramica di Vertex AI Agent Engine per monitorare l'integrità operativa e le prestazioni dei tuoi agenti.

Visualizzare la dashboard predefinita

  1. Vai alla pagina Dashboard nella console Google Cloud :

    Vai a Dashboard

  2. Selezionare il tuo progetto Google Cloud .

  3. Nel riquadro Le mie dashboard, aggiungi il filtro Name:Vertex AI Agent Engine Overview.

  4. Fai clic su Panoramica di Vertex AI Agent Engine per visualizzare la dashboard dell'agente predefinita.

Personalizzare la dashboard predefinita

La dashboard predefinita contiene solo le metriche integrate dell'agente. Per aggiungere le tue metriche personalizzate alla dashboard, segui questi passaggi per copiare e personalizzare la dashboard predefinita:

  1. Apri la dashboard predefinita.

  2. Fai clic su Copia dashboard. Nella finestra di dialogo Copia dashboard, fai clic su Copia. Viene aperta la copia della dashboard. Puoi trovare la copia della dashboard anche nel riquadro Le mie dashboard nella categoria Personalizzata.

  3. Nella copia della dashboard, segui questi passaggi per aggiungere una metrica:

    1. Fai clic su Aggiungi widget. Viene visualizzato il riquadro laterale Aggiungi widget.

    2. Per Dati, seleziona Metrica. Viene visualizzato il riquadro laterale Configura widget.

    3. Fai clic su Seleziona una metrica per aprire una barra di ricerca.

    4. Se la metrica personalizzata viene creata utilizzando metriche basate su log:

      1. Inserisci Vertex AI Reasoning Engine nella barra di ricerca e fai clic su Vertex AI Reasoning Engine.

      2. Fai clic sulla categoria di metriche Metriche basate su log, poi fai clic su una metrica, ad esempio Logging/user/tool_calling_count.

      3. Fai clic su Applica.

    5. Se la metrica personalizzata viene creata utilizzando metriche definite dall'utente:

      1. Inserisci Nodo generico nella barra di ricerca e fai clic su Nodo generico.

      2. Fai clic sulla categoria di metriche Metriche personalizzate, poi su una metrica, ad esempio Conteggio token.

      3. Fai clic su Applica.

    6. Nella dashboard viene visualizzato un nuovo grafico che mostra la metrica personalizzata.

  4. Puoi modificare ulteriormente il layout della dashboard, ad esempio:

    1. Sposta il widget tenendo premuto il titolo e trascinandolo in un'altra posizione nella stessa dashboard.

    2. Ridimensiona il widget tenendo premuto l'angolo in basso a destra e regolandone le dimensioni.

Per ulteriori dettagli sull'aggiunta di grafici delle metriche utilizzando Prometheus Query Language (PromQL) e sulla tabulazione delle metriche, consulta Aggiungere grafici e tabelle a una dashboard personalizzata.

Se hai configurato avvisi personalizzati, consulta la sezione Visualizzare criteri di avviso e avvisi in una dashboard per aggiungere questi avvisi alla dashboard.