Monitorare un agente

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

Panoramica

Puoi utilizzare Vertex AI Agent Engine utilizzando Cloud Monitoring senza alcuna configurazione o configurazione aggiuntiva. Le metriche dell'agente integrate vengono raccolte e visualizzate automaticamente nelle pagine di Cloud Monitoring della console.Google Cloud

Metriche integrate supportate

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

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

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

Visualizzare le metriche di un agente

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

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

  2. Vai a Esplora metriche nella Google Cloud console:

    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 e poi su una metrica, ad esempio Numero richieste.

  7. Facoltativamente, imposta filtri delle etichette aggiuntivi, l'elemento di aggregazione e modifica 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 li tracciano come richieste al secondo (una metrica di frequenza).

Eseguire query sulle metriche per un agente

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

Esegui query sulle metriche con MQL o PromQL

Puoi utilizzare MQL o PromQL per allineare e aggregare i punti dati con un intervallo di tempo personalizzato e tracciare i punti dati trasformati come conteggio delle richieste assoluto (anziché richieste al secondo):

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

Puoi eseguire query sul tasso di errori calcolando il rapporto tra le richieste etichettate con determinati codici di risposta di errore (ad es. 500) e il numero totale di richieste (percentuale di richieste non riuscite):

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

Per le best practice e le limitazioni relative alle metriche relative ai rapporti, consulta Informazioni sui rapporti delle metriche. Per un esempio di come impostare un avviso per la metrica del tasso di errore, consulta Criteri di esempio in JSON.

Esegui query sulle metriche con l'API Cloud Monitoring

Puoi utilizzare l'API Cloud Monitoring per:

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

  • Elenca le 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 dall'Agent Engine aiplatform.googleapis.com/ReasoningEngine.

Puoi richiamare queste API tramite Explorer API, librerie client specifiche per il linguaggio 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 lo strumento curl.

Ottenere la definizione della risorsa monitorata del motore dell'agente

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

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.

Elenca le definizioni delle metriche dell'agente disponibili

Il seguente comando utilizza projects.metricDescriptors per recuperare tutte le metriche e i filtri delle 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, nonché 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 dell'agente specifica durante una finestra temporale specifica:

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. Questa operazione non è sempre obbligatoria. Puoi eseguire query su più istanze di Agent Engine all'interno dello stesso project.
  • interval.startTime e interval.endTime: inizio (incluso) e fine (escluso) dell'intervallo di tempo, in 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 schemi ricorrenti 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 dei dati di sistema lato client.

Metriche basate su log

I passaggi che seguono 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 contare le chiamate degli 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 basata su log di tipo contatore tramite la Google Cloud console:

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

      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 della metrica basata su log. Ad esempio, tool_calling_count. Se vuoi, inserisci Descrizione e Unità.

    5. Per la sezione Selezione filtro:

      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 log. 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 relativi log associati, procedi nel seguente modo nella console: Google Cloud

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

      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, quindi su Logging/user/tool_calling_count. Se necessario, modifica l'intervallo di tempo.

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

      • Per ottenere il conteggio totale delle invocazioni di 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 invocazioni per un agente specifico per tutti gli strumenti, imposta l'etichetta del filtro agent con il valore dell'ID agente.

      Se vuoi, imposta Sommario per su tool o agent per ottenere il conteggio totale suddiviso per diversi strumenti o agenti.

Consulta Logging an agent (Eseguire il logging di un agente) per istruzioni su come scrivere i log dell'agente e consulta la Panoramica delle metriche basate su log per ulteriori dettagli sulle metriche basate su log.

Metriche definite dall'utente

I passaggi che seguono 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 vuoi calcolare il conteggio totale dei token consumati (supponendo che tu monitori il numero di token dall'avvio dell'applicazione per ogni agente di chiamata 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 tipi di metriche. Le etichette model e agent rappresentano il nome del modello linguistico di grandi dimensioni (LLM) di destinazione e dell'agente invocante.

    1. Puoi trovare la metrica token_count in Esplora metriche:

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

      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 Google Cloud console:

      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.

Creare avvisi per un agente

Puoi utilizzare le metriche in combinazione con gli avvisi. Per ulteriori dettagli, consulta la 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 Google Cloud console:

    Vai ad Avvisi

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

    1. In Modalità di configurazione dei criteri, seleziona Generatore.

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

    3. Nella sezione Aggiungi filtri, se vuoi, configura 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 della richiesta durante il periodo di allineamento di 5 minuti).

    5. Fai clic su Avanti.

  3. Nella sezione Configurare l'attivatore dell'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 ulteriori dettagli, consulta la sezione Gestire i canali di notifica.

    2. (Facoltativo) Configura l'oggetto della notifica, la durata della chiusura automatica degli incidenti, le etichette delle applicazioni, le etichette delle norme, il livello di gravità e la documentazione aggiuntiva.

    3. Imposta il nome del criterio nella sezione Assegna un nome alla policy di avviso, ad esempiolatency-99p-alert.

    4. Fai clic su Crea criterio.

In caso di incidente, consulta Incidenti per i criteri di avviso basati su metriche per saperne di più su come confermare e esaminare l'incidente e disattivare l'avviso.

Puoi trovare altri esempi di avvisi in Criteri di esempio in JSON.

Monitorare le metriche di un agente

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

Visualizzare la dashboard predefinita

  1. Vai alla pagina Dashboard nella Google Cloud console:

    Accedi 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 predefinite dell'agente. Per aggiungere le tue metriche personalizzate alla dashboard, segui i passaggi riportati di seguito 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, quindi su una metrica, come 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 regolane le dimensioni.

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

Se hai configurato avvisi personalizzati, consulta Visualizzare criteri e avvisi in una dashboard per aggiungerli alla tua dashboard.