Surveiller un agent

Cette page explique comment utiliser des métriques intégrées, des métriques personnalisées et des alertes pour surveiller vos agents dans Vertex AI Agent Engine.

Présentation

Vous pouvez utiliser Vertex AI Agent Engine avec Cloud Monitoring sans aucune configuration supplémentaire. Les métriques d'agent intégrées sont automatiquement collectées et visualisées sur les pages Cloud Monitoring de la consoleGoogle Cloud .

Métriques intégrées acceptées

Les métriques d'agent suivantes sont acceptées et associées à la ressource surveillée aiplatform.googleapis.com/ReasoningEngine de Vertex AI Agent Engine :

  • Nombre de requêtes
  • Latences des requêtes
  • Durée d'allocation du processeur du conteneur
  • Durée d'allocation de la mémoire du conteneur

Consultez la liste complète des métriques AI Platform pour en savoir plus sur les types de métriques, les unités, les étiquettes, la latence et la période d'échantillonnage.

Afficher les métriques d'un agent

Vous pouvez afficher les métriques intégrées de votre agent dans la Google Cloud console à l'aide de l'explorateur de métriques:

  1. Pour obtenir l'autorisation d'afficher les métriques dans l'explorateur de métriques, demandez à votre administrateur de vous accorder le rôle Lecteur Monitoring (roles/monitoring.viewer) sur votre projet.

  2. Accédez à l'explorateur de métriques dans la console Google Cloud  :

    Accéder à l'explorateur de métriques

  3. Sélectionnez votre projet Google Cloud .

  4. Cliquez sur Sélectionner une métrique pour ouvrir une barre de recherche.

  5. Saisissez Vertex AI Reasoning Engine dans la barre de recherche, puis cliquez sur Vertex AI Reasoning Engine.

  6. Cliquez sur la catégorie de métriques Reasoning_engine, puis sur une métrique, par exemple Nombre de requêtes.

  7. Vous pouvez également définir des filtres d'étiquettes supplémentaires et un élément d'agrégation ainsi qu'ajuster la période.

Par défaut, les graphiques de l'explorateur de métriques pour la métrique Nombre de requêtes alignent les points de données avec un intervalle de temps par défaut et tracent les points de données sous forme de requêtes par seconde (métrique de taux).

Interroger les métriques d'un agent

Vous pouvez également interroger les métriques à l'aide du langage MQL (Monitoring Query Language), du langage PromQL (Prometheus Query Language) ou de l'API Cloud Monitoring v3. MQL et PromQL offrent plus d'options pour le filtrage, l'agrégation et la transformation des métriques, tandis que l'API Cloud Monitoring permet de lister et d'interroger de manière programmatique tous les points de données bruts.

Interroger les métriques avec MQL ou PromQL

Vous pouvez utiliser MQL ou PromQL pour aligner et agréger des points de données avec un intervalle de temps personnalisé, et tracer des points de données transformés en tant que nombre de requêtes absolues (plutôt que sous forme de requêtes par seconde) :

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

Vous pouvez interroger le taux d'erreur en calculant le rapport entre les requêtes étiquetées avec certains codes de réponse d'erreur (tels que 500) et le nombre total de requêtes (pourcentage de requêtes ayant échoué) :

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

Pour connaître les bonnes pratiques et les restrictions concernant les métriques de ratio, consultez À propos des ratios de métriques. Pour savoir comment définir une alerte pour la métrique de taux d'erreur, consultez Exemples de règles au format JSON.

Interroger des métriques avec l'API Cloud Monitoring

Vous pouvez utiliser l'API Cloud Monitoring pour effectuer les opérations suivantes :

  • Obtenir la définition de la ressource surveillée Vertex AI Agent Engine

  • Lister les définitions de métriques d'agent disponibles

  • Interroger les données de séries temporelles pour request_count

Toutes les métriques d'agent sont associées à la ressource surveillée Agent Engine aiplatform.googleapis.com/ReasoningEngine.

Vous pouvez appeler ces API à l'aide d'APIs Explorer, des bibliothèques clientes propres aux langages ou de la ligne de commande. Consultez la documentation concernant la lecture de métriques avec APIs Explorer et les bibliothèques clientes. Les exemples suivants illustrent l'utilisation dans la ligne de commande, plus précisément dans l'outil curl.

Obtenir la définition de la ressource surveillée Agent Engine

La commande suivante récupère la définition de la ressource surveillée à l'aide de projects.monitoredResourceDescriptors ainsi que toutes les étiquettes disponibles pouvant être utilisées pour le filtrage :

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

Les étiquettes doivent inclure resource_container, location et reasoning_engine_id.

Lister les définitions de métriques d'agent disponibles

La commande suivante utilise projects.metricDescriptors pour récupérer toutes les métriques et tous les filtres d'étiquettes pour Agent Engine :

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

Le résultat doit inclure la définition des métriques suivantes ainsi que leurs étiquettes spécifiques :

  • 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

Interroger les données de séries temporelles pour request_count

Vous pouvez utiliser projects.timeSeries.list avec des paramètres tels que interval, filter et aggregation pour interroger des données de séries temporelles.

L'exemple suivant montre comment interroger les points de données bruts de la métrique request_count pour une instance d'agent spécifique au cours d'une période donnée :

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'

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • RESOURCE_ID : ID de l'instance Agent Engine. Il n'est pas toujours obligatoire. Vous pouvez interroger plusieurs instances Agent Engine dans le même projet.
  • interval.startTime et interval.endTime : début (inclusif) et fin (exclusive) de l'intervalle de temps, au format RFC 3339. Par exemple, "2025-03-26T11:22:33Z" pour le temps universel coordonné (UTC) et "2025-03-26T11:22:33-08:00" pour l'heure normale du Pacifique (PST). Pour obtenir la définition complète et d'autres exemples, consultez RFC 3339.

Vous devriez obtenir un résultat semblable à celui-ci :

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

Consultez projects.timeSeries.list pour en savoir plus sur le format de réponse.

Créer des métriques personnalisées pour un agent

Si les métriques d'agent intégrées ne couvrent pas votre cas d'utilisation spécifique, vous pouvez définir des métriques personnalisées. Vous pouvez créer des métriques personnalisées à l'aide des méthodes suivantes :

Métriques basées sur les journaux

Les étapes suivantes montrent comment créer et utiliser une métrique basée sur les journaux (tool_calling_count) pour un exemple de workflow dans lequel plusieurs agents appellent plusieurs outils. Vous souhaitez comptabiliser les appels d'outils :

  1. Spécifiez que votre outil doit écrire une entrée de journal chaque fois qu'il est appelé. Par exemple, "tool-\<tool-id\> invoked by agent-\<agent-id\>".

  2. Créez une métrique basée sur les journaux de type compteur à l'aide de la console Google Cloud  :

    1. Accédez à la page Métriques basées sur les journaux dans la console Google Cloud  :

      Accéder à la page "Métriques basées sur les journaux"

    2. Dans la section Métriques définies par l'utilisateur, cliquez sur Créer une métrique. Le volet Créer une métrique basée sur les journaux s'affiche.

    3. Dans le champ Type de métrique, sélectionnez Compteur.

    4. Dans la section Détails, saisissez le nom de la métrique basée sur les journaux. Par exemple, tool_calling_count. (Facultatif) Saisissez la description et les unités.

    5. Dans la section Sélection du filtre, procédez comme suit :

      1. Dans la liste déroulante Sélectionner un projet ou un bucket de journaux, sélectionnez Journaux du projet.

      2. Dans le champ Créer un filtre, saisissez le filtre de journal à l'aide du langage de requête Logging. Exemple :

        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. Dans la section Étiquettes, cliquez sur le bouton Ajouter une étiquette pour en ajouter deux.

      1. Pour la première étiquette, procédez comme suit :

        1. Dans le champ Nom de l'étiquette, saisissez tool.

        2. Dans le champ Nom du champ, saisissez textPayload.

        3. Dans le champ Expression régulière, saisissez (tool-\d+) invoked by agent-\d+.

      2. Pour la seconde étiquette, procédez comme suit :

        1. Dans le champ Nom de l'étiquette, saisissez agent.

        2. Dans le champ Nom du champ, saisissez textPayload.

        3. Dans le champ Expression régulière, saisissez tool-\d+ invoked by (agent-\d+).

      1. Cliquez sur OK.

    7. Cliquez sur Créer une métrique.

  3. Pour afficher la métrique tool_calling_count et les journaux associés, procédez comme suit dans la console Google Cloud  :

    1. Accédez à la page Explorateur de métriques dans la console Google Cloud  :

      Accéder à l'explorateur de métriques

    2. Cliquez sur Sélectionner une métrique pour ouvrir une barre de recherche.

    3. Saisissez Vertex AI Reasoning Engine dans la barre de recherche, puis cliquez sur Vertex AI Reasoning Engine.

    4. Cliquez sur la catégorie de métriques Métriques basées sur les journaux, puis sur Logging/user/tool_calling_count. Ajustez la période si nécessaire.

    5. (Facultatif) Filtrez sur les étiquettes tool et agent.

      • Pour obtenir le nombre total d'appels d'un outil spécifique pour tous les agents, définissez l'étiquette de filtre tool avec la valeur de cet ID d'outil.

      • Pour obtenir le nombre total d'appels d'un agent spécifique pour tous les outils, définissez l'étiquette de filtre agent avec la valeur de cet ID d'agent.

      Vous pouvez également définir Somme par sur tool ou agent pour obtenir le nombre total ventilé selon les différents outils ou agents.

Consultez Journaliser un agent pour savoir comment écrire des journaux d'agent et Présentation des métriques basées sur les journaux pour en savoir plus sur les métriques basées sur les journaux.

Métriques définies par l'utilisateur

Les étapes suivantes montrent comment créer et utiliser une métrique définie par l'utilisateur (token_count) pour un exemple de workflow dans lequel plusieurs agents appellent plusieurs modèles. Vous souhaitez calculer le nombre total de jetons consommés (en supposant que vous suivez le nombre de jetons depuis le démarrage de l'application pour chaque agent appelant et modèle cible) :

  1. Définissez le type de métrique personnalisée en appelant projects.metricDescriptors.create avec les paramètres suivants :

    • name : chaîne d'URL, par exemple projects/PROJECT_ID.

    • Request body : objet 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 métrique token_count est créée avec le genre Cumulative, qui représente le nombre total de jetons depuis le démarrage de l'application. Pour en savoir plus sur les métriques Cumulative, consultez Genres et types de métriques. Les étiquettes model et agent représentent le nom du grand modèle de langage (LLM) cible et de l'agent appelant.

    1. La métrique token_count est disponible dans l'explorateur de métriques :

      1. Accédez à la page Explorateur de métriques dans la console Google Cloud  :

      Accéder à l'explorateur de métriques

      1. Cliquez sur Sélectionner une métrique pour ouvrir une barre de recherche.

      2. Saisissez Nœud générique dans la barre de recherche, puis cliquez sur Métriques personnalisées.

      3. Cliquez sur Nombre de jetons.

  2. Écrivez des points de données dans la nouvelle métrique en appelant projects.timeSeries.create avec les paramètres suivants :

    • name : chaîne d'URL, par exemple projects/PROJECT_ID.

    • Request body : liste d'objets 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. Une fois les points de données importés avec l'API Cloud Monitoring, vous pouvez afficher la nouvelle métrique token_count à l'aide de la console Google Cloud  :

    1. Accédez à la page Explorateur de métriques dans la console Google Cloud  :

      Accéder à l'explorateur de métriques

    2. Cliquez sur Sélectionner une métrique pour ouvrir une barre de recherche.

    3. Saisissez Nœud générique dans la barre de recherche, puis cliquez sur Métriques personnalisées.

    4. Cliquez sur Nombre de jetons. Ajustez la période et configurez les valeurs d'étiquette pour model ou agent si nécessaire.

Créer des alertes pour un agent

Vous pouvez utiliser des métriques conjointement avec des alertes. Pour en savoir plus, consultez Aperçu des alertes.

L'exemple suivant montre comment créer une alerte de seuil pour la métrique request_latencies afin de recevoir des notifications lorsque la latence dépasse une valeur prédéfinie pendant une durée spécifiée :

  1. Accédez à la page Alertes dans la console Google Cloud  :

    Accéder à la page "Alertes"

  2. Cliquez sur Créer une règle. La page Créer une règle d'alerte s'ouvre.

    1. Dans le champ Mode de configuration des règles, sélectionnez Compilateur.

    2. Dans le menu déroulant Sélectionner une métrique, sélectionnez Vertex AI Reasoning Engine > reasoning_engine > Request Latency.

    3. Dans la section Ajouter des filtres, configurez éventuellement des filtres (par exemple, reasoning_engine_id ou response_code).

    4. Dans la section Transformer les données, définissez Fenêtre glissante et Fenêtrage glissant sur des valeurs telles que 5min et 99th percentile (surveillez le 99e centile de la latence de requête sur la période d'alignement de cinq minutes).

    5. Cliquez sur Suivant.

  3. Dans la section Configurer un déclencheur d'alerte, procédez comme suit :

    1. Sélectionnez Seuil pour Types de condition.

    2. Sélectionnez un déclencheur d'alerte, tel que À chaque infraction de série temporelle.

    3. Sélectionnez une position du seuil, par exemple Au-dessus du seuil.

    4. Saisissez une valeur de seuil, telles que 5000ms.

    5. Cliquez sur Suivant.

  4. Dans la section Configurer des notifications et finaliser l'alerte, procédez comme suit :

    1. Sélectionnez un ou plusieurs canaux de notification. Pour en savoir plus, consultez Gérer les canaux de notification.

    2. (Facultatif) Configurez l'objet de la notification, le délai pour la fermeture automatique de l'incident, les étiquettes d'application, les étiquettes de règle, le niveau de gravité et la documentation supplémentaire.

    3. Dans la section Nom de la règle d'alerte, définissez le nom de la règle, par exemple latency-99p-alert.

    4. Cliquez sur Créer une règle.

En cas d'incident, consultez Incidents liés aux règles d'alerte basées sur des métriques pour en savoir plus sur la confirmation et l'analyse de l'incident, ainsi que sur la désactivation de l'alerte.

Pour obtenir plus d'exemples d'alertes, consultez Exemples de règles au format JSON.

Surveiller les métriques d'un agent

Vous pouvez utiliser le tableau de bord général de Vertex AI Agent Engine pour surveiller l'état opérationnel et les performances de vos agents.

Afficher le tableau de bord par défaut

  1. Accédez à la page Tableaux de bord dans la console Google Cloud  :

    Accéder à la page "Tableaux de bord"

  2. Sélectionnez votre projet Google Cloud .

  3. Dans le volet Mes tableaux de bord, ajoutez le filtre Name:Vertex AI Agent Engine Overview.

  4. Cliquez sur Tableau de bord général Vertex AI Agent Engine pour afficher le tableau de bord par défaut de l'agent.

Personnaliser le tableau de bord par défaut

Le tableau de bord par défaut ne contient que les métriques intégrées de l'agent. Pour ajouter vos propres métriques personnalisées au tableau de bord, copiez et personnalisez le tableau de bord par défaut de la manière suivante :

  1. Ouvrez le tableau de bord par défaut.

  2. Cliquez sur Copier le tableau de bord. Dans la boîte de dialogue Copier le tableau de bord, cliquez sur Copier. La copie du tableau de bord s'ouvre. Vous pouvez également trouver cette copie dans le volet Mes tableaux de bord, sous la catégorie Personnalisés.

  3. Dans la copie du tableau de bord, ajoutez une métrique de la manière suivante :

    1. Cliquez sur Ajouter le widget. Le panneau latéral Ajouter le widget s'affiche.

    2. Dans le champ Données, sélectionnez Métrique. Le panneau latéral Configurer le widget s'affiche.

    3. Cliquez sur Sélectionner une métrique pour ouvrir une barre de recherche.

    4. Si vous avez créé votre métrique personnalisée à l'aide de métriques basées sur les journaux :

      1. Saisissez Vertex AI Reasoning Engine dans la barre de recherche, puis cliquez sur Vertex AI Reasoning Engine.

      2. Cliquez sur la catégorie de métriques Métriques basées sur les journaux, puis sur une métrique, par exemple Logging/user/tool_calling_count.

      3. Cliquez sur Appliquer.

    5. Si vous avez créé votre métrique personnalisée à l'aide de métriques définies par l'utilisateur :

      1. Saisissez Nœud générique dans la barre de recherche, puis cliquez sur Nœud générique.

      2. Cliquez sur la catégorie de métriques Métriques personnalisées, puis sur une métrique, par exemple Nombre de jetons.

      3. Cliquez sur Appliquer.

    6. Un nouveau graphique affichant la métrique personnalisée s'affiche dans le tableau de bord.

  4. Vous pouvez également ajuster la disposition du tableau de bord. Par exemple :

    1. Pour déplacer votre widget, appuyez de manière prolongée sur son titre et faites-le glisser vers un autre emplacement du même tableau de bord.

    2. Pour redimensionner votre widget, appuyez de manière prolongée sur son angle inférieur droit et ajustez sa taille.

Pour en savoir plus sur l'ajout de graphiques de métriques à l'aide de MQL (Monitoring Query Language) ou PromQL (Prometheus Query Language) ainsi que sur la mise en tableau de vos métriques, consultez Ajouter des graphiques et des tableaux à un tableau de bord personnalisé.

Si vous avez configuré des alertes personnalisées, consultez Afficher des règles d'alerte et des alertes dans un tableau de bord pour ajouter ces alertes à votre tableau de bord.