Observabilité pour les développeurs d'agents d'IA

Si vous développez des agents d'IA, vous pouvez instrumenter vos applications avec OpenTelemetry pour observer comment vos agents raisonnent, appellent des outils et répondent aux requêtes. Ce guide explique comment capturer la télémétrie des agents à l'aide de frameworks tels que LangGraph et Agent Development Kit (ADK), et comment analyser les requêtes et les réponses multimodales dans Cloud Trace.

Instrumenter les agents pour comprendre leur comportement

Lorsque vous développez ou gérez des applications d'IA générative, les données de télémétrie capturent les étapes de raisonnement, les appels d'outils et les interactions externes de vos agents autonomes. Ces données sont utiles pour les raisons suivantes :

  • Comprendre le comportement non déterministe : étant donné que le processus de raisonnement d'un agent n'est pas déterministe, la télémétrie est le seul moyen fiable d'inspecter les décisions prises par un agent et les outils qu'il sélectionne.
  • Résoudre les problèmes et diagnostiquer les erreurs : les traces vous aident à identifier les requêtes d'API ayant échoué, les boucles d'exécution infinies et les goulots d'étranglement de latence dans les workflows d'agents distribués.
  • Assurer la gouvernance et valider le trafic : la télémétrie vous permet de visualiser les flux de communication (par exemple, dans la topologie des applications) pour vérifier que vos agents ne communiquent qu'avec des agents autorisés, des serveurs MCP et des points de terminaison externes.
  • Évaluer la qualité et le coût de la sortie : la collecte des requêtes, des réponses et de l'utilisation des jetons vous aide à évaluer la précision du modèle, à détecter les hallucinations et à optimiser la consommation des ressources.

Comment instrumenter vos applications d'IA générative

Pour instrumenter votre application, vous devez générer des données de télémétrie et les envoyer à un emplacement où elles peuvent être stockées, interrogées et analysées. Par exemple, lorsque votre instrumentation envoie des données de télémétrie à votre Google Cloud projet, vous pouvez utiliser Google Cloud Observability pour afficher et analyser ces données.

Cloud Trace extrait automatiquement les événements des étendues écrites par les applications d'IA générative lorsque ces étendues sont conformes aux conventions sémantiques pour les étendues et les événements. Pour en savoir plus sur ces conventions, consultez les documents suivants :

Cloud Trace peut également afficher des requêtes et des réponses multimodales. Dans ce scénario, vos requêtes et vos réponses ne sont pas associées à vos données de trace. Elles sont stockées dans un bucket Cloud Storage. Pour en savoir plus sur cette configuration, consultez Collecter et afficher des requêtes et des réponses multimodales.

Bonnes pratiques

Nous vous recommandons d'instrumenter votre application avec OpenTelemetry, un projet Open Source qui fournit un framework unifié pour l'instrumentation d'applications. Les exemples d'instrumentation listés dans ce document utilisent OpenTelemetry.

Nous vous recommandons également de stocker vos requêtes et vos réponses dans un bucket Cloud Storage plutôt que dans une entrée de journal :

  • Vous disposez d'un contrôle précis sur le contenu du bucket Cloud Storage. Par exemple, vous pouvez supprimer des conversations individuelles stockées dans un bucket. Toutefois, vous ne pouvez pas supprimer des entrées de journal individuelles.

  • Les buckets Cloud Storage peuvent stocker des objets beaucoup plus volumineux que la taille maximale d'une entrée de journal, qui est limitée à 256 Kio. Cloud Logging répond avec une erreur INVALID_ARGUMENT et supprime les données si les données reçues dépassent la taille maximale de l'entrée de journal. Si la commande se termine sans erreur, mais que des champs individuels dépassent leurs limites de taille, Cloud Logging tronque ces données.

Pour en savoir plus sur OpenTelemetry, consultez Qu'est-ce qu'OpenTelemetry ?.

Exemples d'instrumentation

Pour commencer à instrumenter les agents, consultez les exemples d'applications et les guides suivants :

  • Collecter et afficher des requêtes et des réponses multimodales explique comment configurer un agent LangGraph ReAct ou un agent d'IA générative créé avec ADK pour collecter des requêtes et des réponses multimodales. Il explique également comment procéder comme suit :

    • Stocker les requêtes et les réponses dans un bucket Cloud Storage.
    • Afficher les requêtes et les réponses sur la page Explorateur Trace.
    • Analyser les requêtes et les réponses avec BigQuery.
    • Évaluer les requêtes et les réponses avec le SDK Vertex AI pour Python.

  • Instrumenter un agent LangGraph ReAct avec OpenTelemetry explique comment utiliser OpenTelemetry pour instrumenter une application d'IA générative qui utilise le framework LangChain ou LangGraph. Il fournit également un lien vers un exemple d'application que vous pouvez télécharger et exécuter. L'exemple d'application collecte des requêtes et des réponses textuelles.

  • Instrumenter des applications ADK avec OpenTelemetry explique comment activer l'instrumentation intégrée qui collecte la télémétrie à partir des actions clés de l'agent. La télémétrie inclut les requêtes textuelles et les réponses de l'agent. Il fournit également un lien vers un exemple d'application que vous pouvez télécharger et exécuter. L'exemple d'application collecte des requêtes et des réponses textuelles.

  • Examiner les appels MCP à l'aide de Trace explique comment configurer votre application pour transmettre le contexte de trace aux serveurs MCP Google Cloud distants, ce qui permet à ces serveurs d'associer des étendues à une trace.