Les conventions GenAI pour les exécutions d'agents
- Leçon 5
- 40 min
- Module 2 : OpenTelemetry pour les agents
Où nous en sommes
Dans la dernière leçon, nous avons fait d'une exécution une trace, et notre flux de travail a enregistré son premier span. Mais si chaque équipe nomme ses attributs à sa façon, aucun outil ne peut tous les lire. Dans cette leçon, nous utilisons les conventions OpenTelemetry pour l'IA générative. Elles nomment les exécutions d'agents, les appels de modèles et d'outils, ainsi que les jetons, les modèles et les erreurs. Nous commençons par l'étiquette d'un emballage alimentaire.
Leçon 5 sur 28 · Observabilité des agents d'IA : traces, coûts et pistes d'auditLes conventions GenAI pour les exécutions d'agents
1. Pourquoi les agents ont besoin de leur propre observabilité
2. OpenTelemetry pour les agents
3. Instrumenter le flux de travail
4. Trouver les défaillances des agents dans Grafana
5. Le coût
6. Pistes d'audit
7. Alertes, niveaux de service et qualité
8. Outils : Langfuse, les autres et l'inspecteur d'exécutions
Ce que vous saurez faire
Donnez à chaque span d’une exécution d’agent les noms que les outils comprennent déjà. Ils nomment l’opération, le modèle, les jetons, l’outil, la version de la requête et l’erreur. Fixez la version de ces noms, car ils changent encore.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- Les spans, les traces, le span racine et l’horloge d’exécution, vus dans Spans, traces et contexte.
- Ce que sont un appel de modèle et un appel d’outil dans le flux de travail, vus dans Agents d’IA et orchestration des flux de travail.
Ce qu’il vous faut sur votre ordinateur
- Votre projet tel qu’il était à la fin de la dernière leçon : les fichiers des spans copiés, 79 tests réussis.
Testé sur macOS (Apple silicon) avec Python 3.12.13. Les commandes Windows et Linux sont écrites, mais n’ont pas été exécutées.
L’étiquette d’un emballage alimentaire
Section intitulée « L’étiquette d’un emballage alimentaire »Prenez deux boîtes de céréales de deux entreprises. Chaque boîte porte une étiquette nutritionnelle. Les étiquettes utilisent les mêmes mots, « Énergie », « Lipides », « Sucres », avec les mêmes unités, pour la même portion. Vous pouvez donc comparer les deux boîtes en quelques secondes, sans connaître les entreprises.
Les entreprises n’ont pas choisi ces mots. Une règle les impose, et cette règle change parfois : on ajoute une ligne ou on change un nom. Quand la règle change, une entreprise attentive indique la version de la règle que son étiquette suit.
La télémétrie a le même besoin. Les attributs d’un span sont son étiquette. Si chaque équipe écrit ses propres mots, aucun outil ne peut comparer deux exécutions.
Le problème : un nom qu’aucun outil ne connaît
Section intitulée « Le problème : un nom qu’aucun outil ne connaît »Voici une petite expérience tirée de l’exercice de ce module. Plus loin dans cette leçon, vous ajoutez un span pour l’étape de réponse du flux de travail. Supposons que vous écriviez la clé de l’opération gen_ai.operation, un nom qui semble correct :
attrs = {"gen_ai.operation": c.OP_TOOL, c.TOOL_NAME: "send_reply", ...}L’exécution fonctionne, et obs trace affiche le span. Mais il n’affiche aucune information à son sujet :
0.0 s | | 0.00 s execute_tool send_reply 0.0 s | | 0.00 s invoke_agent support-resolver reply_only rule W1obs lit l’attribut gen_ai.operation.name pour déterminer la nature d’un span. Sans cet attribut, le span n’est qu’un nom. Il n’a ni état « envoyé » ni état « échoué ». Un décompte ultérieur des appels d’outils l’omettrait. Les requêtes Grafana du cours et les autres outils fonctionnent de la même façon. L’équipe du cours a aussi envoyé la semaine rejouée à Langfuse, un outil conçu pour les traces d’applications d’IA. Le module 8 l’utilise. Langfuse a déterminé le type des spans à partir des noms d’opérations GenAI. Il a trouvé 718 appels de modèles, 750 appels d’outils et 316 exécutions d’agents. Une seule mauvaise clé, et un span disparaît de toutes les vues.
Il faut donc convenir des noms, et chaque span doit les utiliser exactement.
L’idée : les conventions sémantiques
Section intitulée « L’idée : les conventions sémantiques »OpenTelemetry publie des conventions sémantiques : des noms convenus pour les spans, les attributs et les métriques. Ainsi, tout outil peut lire la télémétrie de toute application. Les conventions sémantiques GenAI couvrent l’IA générative : les appels de modèles, les agents et les outils. Leurs noms d’attributs commencent par gen_ai..
Elles nomment trois types de spans nécessaires à une exécution d’agent. Le nom de l’opération, gen_ai.operation.name, indique le type d’un span :
| Opération | Nom du span | Ce que c’est | Dans notre flux de travail |
|---|---|---|---|
invoke_agent |
invoke_agent {agent name} |
une exécution d’un agent | invoke_agent support-resolver |
invoke_workflow |
invoke_workflow {workflow name} |
une exécution où du code, ou plusieurs agents, choisissent les étapes | invoke_workflow support-resolution (fixe, routeur, deux processus) |
chat |
chat {model} |
un appel à un modèle | chat chat-strong |
execute_tool |
execute_tool {tool name} |
un appel d’outil | execute_tool get_order |
Notre projet utilise aussi approve (approuver) pour la décision d’une personne. Aucune convention ne définit cette opération : elle nous appartient, et les leçons du module 3 le précisent là où elle apparaît.
Les attributs décrivent ensuite chaque span. Ils contiennent le modèle demandé, le modèle qui a répondu et les jetons. Ils contiennent la raison de l’arrêt du modèle, le nom de l’outil, le nom et la version de la requête, et l’erreur.
Exemple détaillé : trois spans du double remboursement
Section intitulée « Exemple détaillé : trois spans du double remboursement »Lisez les attributs de vrais spans de la semaine enregistrée, tous tirés de l’exécution R-1014-040 :
Description textuelle du diagramme
Chaque carte représente un span et certains de ses attributs. L’exécution d’agent contient les totaux et les identifiants de l’exécution. L’appel de modèle contient le modèle demandé, celui qui a répondu, les jetons, la raison de l’arrêt et les informations de requête. L’appel d’outil contient le nom et le type de l’outil, ainsi que l’indication de lecture ou d’écriture et l’état propres à Larkfield. L’appel de remboursement échoué contient error.type = timeout et l’état de span ERROR (erreur).
Suivez maintenant les valeurs :
- Le modèle demandé et le modèle qui a répondu. L’appel de modèle contient
gen_ai.request.model = chat-strong: le nom utilisé par le flux de travail. Il contient aussigen_ai.response.model = gpt-6.1-sol-2026-09-29: la version exacte du modèle qui a répondu, selon le fournisseur. Un nom commechat-strongpeut pointer vers un nouveau modèle demain. Le modèle de réponse vous indique lequel c’était. - Les jetons. Le premier appel de modèle a utilisé 2 160 jetons d’entrée et 47 de sortie. Le deuxième appel en a utilisé 2 426 en entrée et 218 en sortie. Le span racine contient les sommes : 2 160 + 2 426 = 4 586 en entrée, et 47 + 218 = 265 en sortie. Les attributs des jetons sont
gen_ai.usage.input_tokensetgen_ai.usage.output_tokens, sur chaque appel de modèle. - Pourquoi le modèle s’est arrêté.
gen_ai.response.finish_reasons = stop: le modèle a terminé sa réponse. D’autres valeurs, commelength(longueur) outool_calls(appels d’outils), indiquent qu’il a manqué de place ou demandé un outil. - La requête, sans son texte.
gen_ai.prompt.name = agent_structurednomme le fichier de requête.gen_ai.prompt.version = 39329efacorrespond aux 8 premiers caractères d’un hachage SHA-256 de ce fichier et du fichier de politique. Un hachage est une empreinte : le même texte donne toujours la même valeur, et un mot modifié en donne une autre. Vous pouvez donc voir que deux exécutions ont utilisé des requêtes différentes sans stocker un mot de la requête. - Les erreurs. L’appel de remboursement dont le délai a expiré contient
error.type = timeout, un nom des conventions principales d’OpenTelemetry, et l’état de span ERROR. Les deux sont nécessaires : l’état indique que l’étape a échoué, eterror.typeindique comment.
Vous pouvez produire vous-même la version de la requête. Dans le dossier du projet :
python -c "from resolver.telemetry import prompt_version; print(prompt_version('agent_structured'))"39329efaC’est la même valeur que sur le span. Changez un mot dans resolver/prompts/agent_structured.md, relancez la commande, et la valeur change. Annulez ensuite votre modification.
Ce que les conventions excluent
Section intitulée « Ce que les conventions excluent »Les conventions définissent aussi des attributs pour le texte lui-même : gen_ai.input.messages, gen_ai.output.messages et gen_ai.system_instructions. Ils exigent une activation explicite : l’instrumentation ne doit pas les enregistrer sans votre demande. Les conventions avertissent qu’ils sont « susceptibles de contenir des informations sensibles ». Notre flux de travail ne les enregistre jamais : OBS_CAPTURE_CONTENT est à off (désactivé). La dernière leçon de ce module les supprime aussi dans le Collector, au cas où une bibliothèque les ajouterait.
Nos propres noms
Section intitulée « Nos propres noms »Certains éléments dont Larkfield a besoin n’ont pas de convention. Par exemple : le billet de soutien, l’identifiant du client, la version publiée, une lecture ou une écriture et la clé d’idempotence d’un remboursement. Le projet leur donne son propre préfixe, larkfield.. Un outil qui ne les connaît pas les affiche comme de simples attributs. Ils n’entrent jamais en conflit avec un futur nom gen_ai.. La règle pour chaque nom du projet : il contient un décompte, un état, un identifiant ou le nom d’un modèle ou d’un outil. Il ne contient jamais de texte.
Les conventions sont encore en développement
Section intitulée « Les conventions sont encore en développement »Les conventions GenAI ont l’état développement. Cet état signifie qu’un nom peut encore changer ou disparaître dans une version ultérieure. Nous l’avons constaté pendant la création du cours. Le site OpenTelemetry a déplacé les pages GenAI vers un nouveau dépôt, open-telemetry/semantic-conventions-genai. Ce dépôt n’a pas encore de version publiée, et son README indique « Schema URL : TODO » (URL du schéma : à faire). Entre-temps, le paquet Python opentelemetry-semantic-conventions 0.66b1 contient encore les anciens noms, tous marqués comme obsolètes et déplacés.
Le déplacement a changé les noms eux-mêmes, pas seulement leur emplacement :
Description textuelle du diagramme
À gauche, les noms de la version 1.44.0 des conventions principales. À droite, les noms au commit fixé du nouveau dépôt GenAI. La durée d’un appel de modèle a un nouveau nom. L’histogramme unique des jetons est devenu deux compteurs, un pour les jetons d’entrée et un pour les jetons de sortie. Les exécutions d’agents et les appels d’outils ont reçu leurs propres métriques de durée. Le projet écrit tous ces noms une seule fois, dans resolver/conventions.py.
Le projet fait donc trois choses, et vous pouvez faire de même dans votre travail :
- Fixer la version. Ce cours utilise le dépôt GenAI au commit (version enregistrée)
9ffc7e00, à l’état développement. Cette référence est écrite à un seul endroit. - Écrire les noms une seule fois. Chaque nom est une constante dans
resolver/conventions.py. Le reste du code utilise seulement ces constantes, jamais une chaîne comme"gen_ai.usage.input_tokens". Le code n’importe même pas les constantes du paquet Python, car ce sont les anciens noms. - Prévoir les changements de noms. Quand vous changez la référence fixée, vous modifiez un fichier et lancez les tests. Un tableau de bord ou une alerte qui utilise un nom doit changer en même temps.
Ouvrez la référence fixée :
grep -n "PINNED" -A7 resolver/conventions.pySelect-String -Path resolver\conventions.py -Pattern "PINNED" -Context 0,7grep -n "PINNED" -A7 resolver/conventions.pyLe bloc qui commence à la ligne 14 nomme le dépôt et le commit complet 9ffc7e00c639be7712e544e3e54331e885dccf84. Il indique aussi l’état development (développement) et les conventions principales 1.44.0. La ligne en dessous définit SCHEMA_URL comme le schéma de la version principale, car le dépôt GenAI n’en a pas encore.
À vous : un span pour la réponse
Section intitulée « À vous : un span pour la réponse »Le flux de travail envoie la réponse au client dans resolver/live.py, dans la fonction _send. C’est une écriture : le client reçoit un message. Mais aucun span ne l’enregistre encore. Ajoutez-en un avec les bons attributs, et affichez-le dans obs trace.
Voici la fonction actuelle :
def _send(state, world) -> str: """Send the reply to the customer (a mock help desk). 'sent' or 'failed'.""" try: helpdesk.send_reply(world, state.run_id, state.proposal.reply) return "sent" except ServiceError: return "failed"-
Choisissez le nom et les attributs du span à partir du tableau et de l’exemple détaillé. C’est un appel d’outil, son outil est
send_reply, et c’est une écriture. Utilisez seulement les constantes deconventions.py, quelive.pyimporte déjà sous le nomc. -
Entourez l’appel d’un span. La fonction utilitaire du projet
telemetry.get().span(name, attributes)démarre un span sur l’horloge d’exécution. Elle en fait le span courant dans le blocwith. -
Quand l’envoi réussit, définissez
larkfield.reply.statusàsent(envoyé). Quand il échoue, définissez-le àfailed(échoué). Définissez aussierror.typeet l’état du span à ERROR. -
Exécutez un billet et lisez sa trace :
Fenêtre de terminal python -m resolver run T-80008python -m obs trace T-80008 -
Exécutez-le encore avec une défaillance simulée du service de soutien, et relisez la trace :
Fenêtre de terminal python -m resolver run T-80008 --fault send_reply:unavailablepython -m obs trace T-80008 -
Vérifiez qu’aucune donnée privée n’a quitté l’application et que les tests réussissent encore :
Fenêtre de terminal python -m obs check-redaction work/telemetrypython -m pytest -q
Essayez vous-même avant de poursuivre la lecture.
Une réponse et la sortie du cours
from opentelemetry.trace import Status, StatusCode # with the other imports at the top
def _send(state, world) -> str: """Send the reply to the customer (a mock help desk). 'sent' or 'failed'.""" attrs = {c.OPERATION: c.OP_TOOL, c.TOOL_NAME: "send_reply", c.TOOL_TYPE: "function", c.TOOL_KIND: "write", c.TICKET_ID: state.task_id} with telemetry.get().span("execute_tool send_reply", attrs) as span: try: helpdesk.send_reply(world, state.run_id, state.proposal.reply) span.set_attribute(c.REPLY_STATUS, "sent") return "sent" except ServiceError as e: span.set_attribute(c.REPLY_STATUS, "failed") span.set_attribute(c.ERROR_TYPE, e.code) span.set_status(Status(StatusCode.ERROR, e.code)) return "failed"La première exécution, à l’étape 4 :
Trace 1 2b8bc035a939318923c1f9eaf2da8277 … 0.0 s 0.0 s | | 0.00 s execute_tool send_reply sent 0.0 s | | 0.00 s invoke_agent support-resolver reply_only rule W1L’exécution avec la défaillance, à l’étape 5. Le flux de travail affiche Reply failed. Ticket: handed to person. (Réponse échouée. Billet : transmis à une personne.), et la trace indique :
Trace 1 10c8900ca208d9854d8280000471cc25 … 0.0 s 0.0 s | | 0.00 s execute_tool send_reply ERROR failed 0.0 s | | 0.00 s invoke_agent support-resolver reply_only rule W1
Outcome: handed_to_personcheck-redaction a vérifié 4 spans sans trouver de problème, et les tests réussissent encore : 79 passed, 1 deselected (79 réussis, 1 non sélectionné).
Regardez l’ordre des deux lignes. Votre span s’affiche au-dessus de son parent, mais son retrait indique qu’il est un enfant. Les deux spans commencent et se terminent au même instant sur l’horloge d’exécution : aucun span de modèle n’a encore avancé l’horloge. obs ne peut donc pas les trier par heure. Le retrait, qui vient de l’identifiant du span parent, fait foi. Dans le module 3, les spans de modèles avancent l’horloge, et l’ordre redevient naturel.
Pourquoi ne pas enregistrer le texte de la réponse pour voir ce que le client a reçu? Parce que le texte contient des données personnelles, et que de nombreuses personnes et de nombreux outils lisent le span. L’état et l’identifiant du billet répondent à la question de l’opérateur : le client a-t-il reçu une réponse? Le service de soutien conserve le texte pour les personnes autorisées à le lire.
Gardez votre modification ou annulez-la, à votre choix. Le module 3 remplace _send par la version de l’instantané, qui enregistre le même span avec une fonction utilitaire partagée.
Erreur courante
Le span est là, mais obs n'affiche aucun état
Symptôme : obs trace affiche execute_tool send_reply sans rien après le nom, même quand la réponse a été envoyée.
Cause : une clé ne correspond pas au nom exact de la convention. Par exemple, "gen_ai.operation" au lieu de gen_ai.operation.name. obs détermine qu’un span est un appel d’outil à partir de gen_ai.operation.name = execute_tool. Il ne lit donc pas l’état de l’outil. Le même span serait aussi absent d’une requête Grafana sur les appels d’outils.
Diagnostic : ouvrez work/telemetry/traces.jsonl et trouvez les attributs du span. Comparez chaque clé avec resolver/conventions.py.
Correction : utilisez les constantes (c.OPERATION, c.TOOL_NAME), jamais une chaîne tapée à la main. Un mauvais nom de constante provoque immédiatement une AttributeError; une mauvaise chaîne échoue sans signaler d’erreur.
Quand suivre les conventions, et ce que cela coûte
Section intitulée « Quand suivre les conventions, et ce que cela coûte »Suivez-les pour chaque span qu’un outil partagé lira : exécutions d’agents, appels de modèles, appels d’outils, erreurs. Grafana, Langfuse et les autres outils affichent alors vos exécutions sans correspondance personnalisée. Ajoutez vos propres noms préfixés pour ce que les conventions ne couvrent pas.
Le coût, c’est le changement. À l’état développement, les noms changent, comme ils l’ont fait pendant la création de ce cours. Une version fixée, un fichier de noms et des tests font du changement une petite tâche planifiée plutôt qu’un tableau de bord brisé. Ne copiez pas les noms d’un billet de blogue ou d’une ancienne version de bibliothèque sans vérifier la version fixée.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Omar demande : « Les conventions sont encore en développement. Pourquoi ne pas attendre leur stabilisation et utiliser nos propres noms entre-temps? » Que répondez-vous?
Afficher la réponse
Nos propres noms fonctionneraient dans notre code, mais aucun outil ne les comprendrait. Les requêtes de Grafana, les types de Langfuse et d’autres outils lisent les noms GenAI. Langfuse a attribué un type aux 2 027 spans de la semaine rejouée à partir des noms d’opérations GenAI. Attendre exige une correspondance pour chaque outil maintenant, puis un changement complet des noms plus tard. Nous suivons plutôt les noms en développement, fixés à un commit (version enregistrée) et écrits une seule fois dans conventions.py. Ainsi, un petit changement suffit quand ils évoluent. Nous avons vu ce changement pendant le cours : de nouveaux noms de métriques et deux compteurs de jetons.
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Vérifiez votre compréhension
Un collègue ajoute un span pour l'outil de remboursement avec ces attributs : tool = 'refund', tokens = 0, ticket_text = le message du client. Nommez trois problèmes et écrivez les attributs que vous utiliseriez.
Afficher la réponse
Premièrement, tool n’est pas la clé de la convention. Utilisez gen_ai.operation.name = execute_tool et gen_ai.tool.name = request_refund, avec le nom de span execute_tool request_refund. Deuxièmement, les jetons appartiennent aux appels de modèle, pas aux appels d’outils : un span d’outil n’a aucun attribut de jetons. Troisièmement, le texte du billet contient des données personnelles et ne doit jamais figurer dans un span. Ajoutez gen_ai.tool.type = function, l’attribut de Larkfield larkfield.tool.kind = write, l’identifiant de commande et le montant. En cas d’échec, ajoutez error.type et le statut ERROR (erreur).
Votre réponse contient-elle les points principaux de la nôtre ?
Connectez-vous et inscrivez-vous au cours pour enregistrer vos réponses. Chaque vérification compte pour le certificat.
Récapitulatif
- Les conventions sémantiques définissent des noms communs pour que chaque outil puisse lire la télémétrie de chaque application. Les conventions GenAI nomment les exécutions d’agents (
invoke_agent,invoke_workflow), les appels de modèle (chat) et les appels d’outils (execute_tool). - Un appel de modèle enregistre le modèle demandé, le modèle qui a répondu et les jetons en entrée et en sortie. Il enregistre aussi la raison de fin, le nom de la requête et l’empreinte de sa version, jamais son texte.
- Erreurs :
error.typeet le statut ERROR du span, les deux. - Les noms propres à Larkfield portent le préfixe
larkfield.et contiennent uniquement des comptes, des statuts, des identifiants et des noms. - Les conventions GenAI sont en développement : le cours fixe le commit
9ffc7e00et écrit chaque nom une seule fois dansresolver/conventions.py. Il prévoit que ces noms évolueront. - Votre flux de travail peut maintenant enregistrer sa réponse sous
execute_tool send_reply, qu’elle soit envoyée ou que l’envoi échoue.
Vous pouvez maintenant nommer chaque étape d’une exécution pour que les outils la comprennent. Mais nos spans vont encore dans des fichiers sur votre ordinateur. Où devraient-ils aller en production, et qui retire les données qui ne doivent pas sortir? Ensuite, vous placerez l’OpenTelemetry Collector entre l’application et les outils.
Leçon suivante : Le Collector