Approbations, personnes et temps d'attente
- Leçon 9
- 40 min
- Module 3 : Instrumenter le flux de travail
Où nous en sommes
Dans les deux dernières leçons, nous avons donné un span à chaque appel de modèle et d'outil. Mais les écritures du double remboursement ont produit leurs propres traces, sans exécution ni personne associée. Elles surviennent après une approbation, parfois le lendemain matin. Dans cette leçon, nous enregistrons l'approbation : qui a décidé, avec quel rôle et combien de temps l'exécution a attendu. Nous utilisons deux traces reliées par un lien. Commençons par une demande de consultation médicale.
Leçon 9 sur 28 · Observabilité des agents d'IA : traces, coûts et pistes d'auditApprobations, personnes et temps d'attente
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
Enregistrez une exécution qui attend l’approbation d’une personne et reprend des heures plus tard. Faites de l’approbation une deuxième trace, avec un lien de span vers la première. Enregistrez qui a décidé, avec quel rôle et quelle limite. Mesurez l’attente par un nombre, pas par un span ouvert.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- Les spans d’outils et d’écriture, l’identifiant d’opération et la clé d’idempotence, dans Appels d’outils, erreurs et nouvelles tentatives.
- Comment le flux de travail du cours sur les agents attend une approbation : il sauvegarde l’exécution, puis
python -m resolver approvela reprend. Chaque rôle a une limite d’approbation : un agent peut approuver jusqu’à 100, un chef d’équipe jusqu’à 500.
Ce qu’il vous faut sur votre ordinateur
- Le projet dans son état à la fin de la dernière leçon : 81 tests réussissent et
show_spans.pyest dans le dossier du projet. - Un terminal dans
observable-workflow, avec l’environnement virtuel actif.
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.
Une demande de consultation médicale
Section intitulée « Une demande de consultation médicale »Votre médecin de famille vous voit le lundi et rédige une demande de consultation auprès d’un spécialiste. La demande porte un numéro. Trois semaines plus tard, le spécialiste vous voit, lit la demande et rédige un rapport qui reprend ce numéro.
Ce sont deux visites, pas une seule longue visite. Personne ne laisse un chronomètre tourner dans la salle d’attente pendant trois semaines. Pourtant, tout le monde peut relier les deux visites, car le rapport indique le numéro de la demande. Et tout le monde peut calculer l’attente : c’est l’écart entre les deux dates sur les documents.
Le problème : les écritures n’ont ni exécution ni personne associée
Section intitulée « Le problème : les écritures n’ont ni exécution ni personne associée »À la fin de la dernière leçon, le double remboursement avait trois traces : l’exécution et deux spans d’écriture isolés. Les écritures portent l’opération et les clés, mais aucun identifiant d’exécution ni personne ayant approuvé. obs trace T-90104 affichait 0 write call(s) (aucun appel d’écriture) et le résultat waiting_approval (en attente d’approbation). Pourtant, le client avait reçu deux remboursements.
Grace pose la première question de tout audit : « Qui a approuvé ce remboursement, et quand? » La télémétrie ne peut pas répondre. Kwame en pose une autre : « Combien de temps nos clients attendent-ils une personne? » La télémétrie ne peut pas répondre non plus.
La cause vient de la structure du flux de travail. python -m resolver run propose une action et s’arrête. python -m resolver approve est un autre processus, qui démarre peut-être le lendemain matin. Lorsqu’il écrit, aucun span de l’exécution n’y est ouvert. Chaque span commence donc une nouvelle trace.
Un long span ou deux traces?
Section intitulée « Un long span ou deux traces? »La première idée est un span qui commence à la proposition et se termine à l’approbation. Tomás aime l’idée : « Alors la trace montre toute l’exécution. » Trois problèmes se posent :
- Un span reste en mémoire jusqu’à sa fin. Pour R-1014-040, cela dure 15 heures. Si le processus s’arrête pendant la nuit, le span est perdu et il ne reste aucun enregistrement de l’exécution.
- L’exécution ne tient pas dans un seul processus. L’approbation vient d’une autre commande ou d’un autre service. Aucun span ouvert ne peut y être terminé.
- La vue en cascade devient illisible. Seize secondes de travail deviennent de fines lignes aux extrémités d’une barre de 15 heures. De plus, le Collector du cours choisit les traces à conserver 10 secondes après l’arrivée du premier span (
decision_wait: 10s). C’est bien avant l’approbation.
Nous créons donc l’équivalent de la demande de consultation : deux traces reliées par un lien de span. Un lien de span est une référence d’un span vers un span d’une autre trace. Il contient l’identifiant de l’autre trace et du span, avec des attributs au besoin. Un parent dit : « Je fais partie de vous. » Un lien dit : « Je reprends à partir de vous », sans réunir les deux arbres.
Comment le flux de travail l’enregistre
Section intitulée « Comment le flux de travail l’enregistre »- La trace 1 se termine par un court span,
approval.request: le rôle autorisé à décider (needs_role), sa limite et le nombre d’actions. Le flux de travail sauvegarde les identifiants de trace et de span dans l’état sauvegardé de l’exécution, près de la proposition. - La trace 2 commence quand une personne décide. Son premier span est
approve support-resolution, avec un lien de span versapproval.request. Il enregistre l’identifiant d’exécution, l’identifiant de membre du personnel, le rôle, sa limite, la décision et l’attente en secondes (larkfield.approval.wait_s). Les écritures et la réponse sont ses enfants. - Une métrique enregistre aussi l’attente :
larkfield.approval.wait, un histogramme avec des classes allant de 1 minute à 1 jour. Les tableaux de bord et les alertes l’utilisent, comme le montre le module 7.
La personne qui approuve est usr-sam, un identifiant de membre du personnel, jamais un nom. Le premier span des deux traces porte l’identifiant d’exécution. Une recherche par exécution trouve donc les deux.
approve (approuver) est notre propre nom d’opération : aucune convention GenAI ne décrit encore la décision d’une personne. Le préfixe larkfield. indique que les attributs sont aussi les nôtres.
Exemple détaillé : 15 heures 25 minutes
Section intitulée « Exemple détaillé : 15 heures 25 minutes »Voici le double remboursement de la semaine rejouée, l’exécution R-1014-040, obtenu avec obs trace R-1014-040 --data data/telemetry/week :
| Trace 1 : la proposition | Trace 2 : la décision | |
|---|---|---|
| Début du premier span | Mercredi 14 octobre, 17 h 52 min 00 s | Jeudi 15 octobre, 9 h 17 min 12 s |
| Travail | 6,6 s : deux appels de modèle, une lecture, approval.request |
10,0 s : deux appels de remboursement, la réponse |
| Fin | 17 h 52 min 06,6 s, avec approval.request |
9 h 17 min 22 s |
| Attributs clés | larkfield.run.id = R-1014-040 |
le même identifiant d’exécution, approver = usr-sam, role = agent, limit = 100, wait_s = {w.double_refund_wait_s} |
L’attente va de la fin de approval.request au début de approve : de 17 h 52 min 06,6 s à 9 h 17 min 12 s. Cela donne 15 h 25 min 5 s, ou 55 505 secondes. Le temps d’attente de la personne n’est pas un span : c’est l’écart entre deux traces, et un nombre.
Description textuelle du diagramme
La trace 1 représente le travail de l’agent, soit 6,6 secondes, et se termine par approval.request. L’exécution attend ensuite 15 heures 25 minutes, sans span ouvert pendant l’attente. La trace 2 représente la décision de Sam et les écritures, soit 10 secondes. Son premier span porte un lien vers approval.request et l’attente sous l’attribut wait_s, soit 55 505,4 secondes. Sous ce span, le premier appel de remboursement dépasse le délai après 10 secondes. La nouvelle tentative avec une nouvelle clé réussit immédiatement : c’est le double remboursement, maintenant rattaché à la personne qui l’a approuvé.
Grafana affiche le même lien. Dans l’exécution de la semaine dans Grafana par l’équipe du cours, le premier span de la trace 2 a une icône de lien. Elle ouvre la trace 1 :

Ajouter les traces d’approbation à votre projet
Section intitulée « Ajouter les traces d’approbation à votre projet »-
Copiez la nouvelle version du flux de travail en production et son test :
Fenêtre de terminal S=../nextia-learning-labs/C31/snapshots/end-of-m03cp $S/resolver/live.py resolver/cp $S/tests/test_approval_traces.py tests/Fenêtre de terminal $S = "..\nextia-learning-labs\C31\snapshots\end-of-m03"Copy-Item $S\resolver\live.py resolver\Copy-Item $S\tests\test_approval_traces.py tests\Fenêtre de terminal S=../nextia-learning-labs/C31/snapshots/end-of-m03cp $S/resolver/live.py resolver/cp $S/tests/test_approval_traces.py tests/ -
Ouvrez
resolver/live.pyet lisez la chaîne de documentation. Trouvez ensuiteapproval.requestdansstart(), puisdef decide(pour la trace 2 :telemetry.link_to()crée le lien à partir de la référence sauvegardée. La réponse est maintenant aussi un span d’écriture,execute_tool send_reply, dans_send(). -
Exécutez les tests :
python -m pytest -q. La dernière ligne indique84 passed, 1 deselected(84 réussis, 1 exclu). Les nouveaux tests vérifient le lien, la personne qui approuve, l’attente et les deux écritures avec une opération et deux clés. -
Supprimez
work/et rejouez le double remboursement avec les deux commandes de la dernière leçon :run, puisapprove … --naive-retry. -
Lisez la trace :
python -m obs trace T-90104.Run T-90104-agent_structured-chat-strong-1 | ticket T-90104 | chat-strong (agent_structured) | release 2.0.0 | language en2 model call(s), 1 read(s), 2 write call(s), 4586 tokens in, 265 out, US$0.00000Trace 1 32de69cc4e8617aeb25415a04e601c6a … 6.6 s0.0 s |========================| 6.56 s invoke_agent support-resolver resolve rule W20.0 s |========= | 2.39 s chat chat-strong 2160 in / 47 out - stop2.4 s | = | 0.00 s execute_tool get_order ok LK-7939962.4 s | ================| 4.17 s chat chat-strong 2426 in / 218 out - stop6.6 s | =| 0.00 s approval.request needs agent... waited 0 min 00 s for a person (this trace has a link to 4e3da4d9776081b6 in trace 32de69cc...)Trace 2 c204c6376ffbcad2fa4d9e9ba7fca580 … 10.0 s0.0 s |========================| 10.01 s approve support-resolution approved by usr-sam (agent, limit 100)0.0 s |========================| 10.00 s execute_tool request_refund ERROR timeout LK-793996 9.95 RFD-LATE key 797fbb5bbb9f8a7e10.0 s | =| 0.00 s execute_tool request_refund done LK-793996 9.95 RFD-LATE key 797fbb5bbb9f8a7e-retry110.0 s | =| 0.00 s execute_tool send_reply sentOutcome: resolved -
Lisez la ligne entre les traces. Vous avez approuvé immédiatement, donc l’attente est de 0. Pourquoi pas les quelques secondes que vous avez prises pour taper? L’horloge d’exécution de la trace 1 avait 6,6 secondes d’avance sur l’horloge réelle, avec le temps de modèle enregistré. La trace 2 commence là où l’horloge de la trace 1 s’est arrêtée.
-
Affichez les deux spans que le lien relie :
python show_spans.py approv.approval.request trace 32de69cc span 4e3da4d9 parent 030420adlarkfield.approval.limit = 100.0larkfield.approval.needs_role = agentlarkfield.proposal.actions = 1approve support-resolution trace c204c637 span 71c71303 parent nonelarkfield.customer.id = C-61975…larkfield.approval.approver = usr-samlarkfield.approval.role = agentlarkfield.approval.limit = 100.0larkfield.approval.wait_s = 0.0gen_ai.operation.name = approvelarkfield.approval.decision = approvedlarkfield.run.id = T-90104-agent_structured-chat-strong-1…link to trace 32de69cc, span 4e3da4d9La dernière ligne de
approveindique la trace et le span deapproval.request: c’est le lien. Vos identifiants diffèrent, mais ils doivent correspondre entre eux.
Le double remboursement forme maintenant une histoire reliée : la proposition, la personne et les deux appels de remboursement sous sa décision.
Exercice guidé : une attente réelle et deux écritures
Section intitulée « Exercice guidé : une attente réelle et deux écritures »Le flux de travail mesure l’attente avec l’horloge réelle. Une attente réelle donne donc un nombre réel. T-90103 concerne une jardinière fissurée : chat-strong propose un remplacement et une étiquette de retour gratuite, soit deux écritures.
-
Lancez le traitement du billet de soutien :
Fenêtre de terminal python -m resolver run T-90103 --variant agent_structured --model chat-strongLa proposition liste deux actions,
reship_itemetcreate_return_label. -
Attendez environ une minute. Approuvez ensuite :
Fenêtre de terminal python -m resolver approve T-90103-agent_structured-chat-strong-1 --as agentreship_item LK-640436: done (operation 221dccf204b80a63, 1 call(s))create_return_label LK-640436: done (operation 0f8c2e98df53719d, 1 call(s))Status: doneReply sent. Ticket: resolved. -
Lisez la trace :
python -m obs trace T-90103.... waited 1 min 10 s for a person (this trace has a link to 8a5e151518170b24 in trace ed36a312...)Trace 2 fdef56b77b85f88ef78c5d9a4767cff3 … 0.0 s0.0 s |========================| 0.00 s approve support-resolution approved by usr-sam (agent, limit 100)0.0 s |============ | 0.00 s execute_tool reship_item done LK-640436 PLANTER x 1 key 221dccf204b80a630.0 s | ===== | 0.00 s execute_tool create_return_label done LK-640436 PLANTER key 0f8c2e98df53719d0.0 s | =======| 0.00 s execute_tool send_reply sentL’équipe du cours a attendu 75 secondes. La trace indique 1 min 10 s : la pause et la durée des commandes, moins les 6,8 secondes d’avance de l’horloge de la trace 1. Votre attente diffère.
-
Affichez les écritures avec
python show_spans.py reship_item, puispython show_spans.py create_return_label. Les deux indiquentparent 4c9a3167: l’identifiant du spanapprove(le vôtre diffère). Chaque écriture indique donc la décision qui l’a autorisée.
C’est la preuve demandée par la vérification de fin de ce module. Le parent d’un span d’écriture est la décision. La décision enregistre la personne et le rôle. Son lien mène à la demande dans la trace 1.
À vous de jouer : une approbation refusée par les règles
Section intitulée « À vous de jouer : une approbation refusée par les règles »Changez une condition : un remboursement supérieur à la limite d’un agent. T-65273 propose un remboursement qui nécessite un chef d’équipe. Faites une prédiction avant de l’exécuter : la trace 2 existe-t-elle? Qu’indique-t-elle, et quel est le résultat de l’exécution?
python -m resolver run T-65273python -m resolver approve T-65273-agent-chat-small-1 --as agentpython -m obs trace T-65273Le résultat de l’équipe du cours
Not approved: An agent may not approve this: it needs a team lead (refund approval limits). 3.9 s | =| 0.00 s approval.request needs team lead
... waited 0 min 00 s for a person (this trace has a link to 03c168924f495e56 in trace 35305645...)Trace 2 2e79d83acbd1f4cc570c021026888e74 … 0.0 s 0.0 s | | 0.00 s approve support-resolution refused_by_rules by usr-sam (agent, limit 100)
Outcome: waiting_approvalLa trace 2 existe et contient un span : la décision, refused_by_rules (refusée par les règles). Elle porte le statut ERROR (erreur), avec approval_refused (approbation refusée), et aucune écriture en dessous. L’exécution attend toujours un chef d’équipe. Une tentative refusée est aussi une preuve : elle montre que les limites ont fonctionné et qui a essayé.
Combien de temps les clients attendent-ils?
Section intitulée « Combien de temps les clients attendent-ils? »Les 118 approbations de la semaine donnent sa réponse à Kwame. Les temps sont simulés à partir des heures de présence du personnel de Larkfield : de 8 h 30 à 17 h 30 en semaine, et de 10 h à 16 h la fin de semaine. Une proposition faite en dehors de ces heures attend le lendemain matin.
Description textuelle du graphique
Sept barres pour 118 approbations. Moins de 5 minutes : 4. De 5 à 15 minutes : 20. De 15 à 30 minutes : 30. De 30 à 60 minutes : 34. De 1 à 4 heures : 5. De 4 à 8 heures : 6. Plus de 8 heures : 19, les propositions du soir qui ont attendu le lendemain matin.
L’attente médiane est de 31.8 minutes, mais le 95e centile est de 15.2 heures. De plus, 19 approbations ont attendu plus de 8 heures. Une moyenne masquerait cette répartition : la plupart des attentes sont courtes, mais un groupe attend toute la nuit. Le double remboursement faisait partie du groupe de nuit : proposé le mercredi soir, approuvé le jeudi matin.
Erreur courante
L'exécution n'a ni billet ni modèle
Symptôme : après une approbation, obs runs affiche une exécution dont les champs du billet et du modèle sont vides. obs trace affiche seulement la décision :
Run T-90104-agent_structured-chat-strong-1 | ticket | () | release | language0 model call(s), 0 read(s), 1 write call(s), 0 tokens in, 0 out, US$0.00000
Trace 1 f646ea8662f9d78d69feade02ea5eca9 … 0.0 s 0.0 s |========================| 0.00 s approve support-resolution approved by usr-sam (agent, limit 100)Le cours a créé cette situation volontairement : il a supprimé work/telemetry/traces.jsonl entre run et approve.
Cause : la trace 1 n’est pas dans les données. Un lien est seulement une référence : il ne copie pas la trace 1 dans la trace 2. Si un stockage supprime la trace 1, le lien ne mène à rien. En production, cela arrive quand l’échantillonnage décide trace par trace. Dans l’exécution de la semaine avec le Collector du cours, l’échantillonnage en fin de trace a conservé 275 traces sur 434. 99 exécutions ont perdu l’une de leurs deux traces.
Diagnostiquer : python show_spans.py approve affiche encore link to trace … (lien vers la trace…). Cherchez cet identifiant de trace dans votre stockage. S’il est absent, l’échantillonnage l’a exclu, il a été supprimé ou il n’a jamais été exporté.
Corriger : conservez les deux traces d’une exécution, ou aucune. Échantillonnez par identifiant d’exécution, pas par trace, et conservez chaque exécution avec une approbation. Excluez la décision elle-même de l’échantillonnage : le module 6 l’envoie à la piste d’audit, qui n’est jamais échantillonnée.
Quand diviser une exécution, et à quel prix
Section intitulée « Quand diviser une exécution, et à quel prix »Divisez une exécution en traces reliées dès qu’elle attend quelque chose hors du programme : une personne, une file d’attente de plusieurs heures ou une tâche planifiée. Gardez une seule trace quand l’attente est courte et reste dans le même processus, comme une nouvelle tentative après 2 secondes.
Deux traces ont un coût. Chaque recherche et chaque tableau de bord doivent les relier par identifiant d’exécution ou par le lien. Un stockage ou un échantillonneur peut aussi en supprimer une. Enregistrez toujours l’identifiant d’exécution sur le premier span des deux traces. Enregistrez l’attente comme attribut et comme métrique. Ainsi, personne n’a besoin des deux traces pour connaître l’attente d’un client.
La question d’audit de Grace nécessite toutefois plus qu’une trace. Un stockage de traces conserve les données pendant des semaines. Une approbation peut devoir être expliquée pendant des années. Le module 6 enregistre la même décision comme événement d’audit.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Tomás propose un seul span, de la proposition à l'approbation, « pour que la trace montre toute l'exécution ». Donnez deux raisons de refuser cette approche. Décrivez ce que le flux de travail enregistre à la place.
Afficher la réponse
Un span reste en mémoire jusqu’à sa fin. Pour R-1014-040, cela représente 15 heures. Il est perdu si le processus s’arrête. L’approbation vient d’un autre processus, où aucun span ouvert ne peut être terminé. De plus, une barre de 15 heures rend les 16 secondes de travail illisibles. À la place, la trace 1 se termine par un span approval.request. La trace 2 commence par approve support-resolution, qui contient un lien de span vers approval.request. Ce span enregistre l’identifiant d’exécution, l’identifiant d’employé de la personne qui approuve, le rôle, la limite, la décision et l’attente en secondes. L’attente est aussi une métrique de type histogramme.
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
Dans la semaine rejouée, l'attente médiane d'approbation est de 31,8 minutes. Pourquoi cela ne suffit-il pas pour répondre à « combien de temps nos clients attendent-ils une personne? »?
Afficher la réponse
Les attentes forment deux groupes. La plupart durent moins d’une heure, mais 19 sur 118 dépassent 8 heures. Ce sont les propositions du soir qui ont attendu le lendemain matin. Le 95e centile est de 15,2 heures. Une médiane ou une moyenne masque le groupe de nuit. Montrez la distribution, ou au moins un centile élevé et le nombre d’attentes au-delà d’un seuil. La métrique de type histogramme le permet.
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
Vérification de réalisation : avec votre propre télémétrie de T-90103 (ou du double remboursement), montrez quelle approbation a permis chaque écriture. Nommez les spans et les attributs qui le prouvent.
Afficher la réponse
Chaque span d’écriture (execute_tool reship_item et execute_tool create_return_label, ou les deux appels request_refund) a un parent : approve support-resolution dans la trace 2. Dans l’exécution de l’équipe du cours, python show_spans.py reship_item montre le parent 4c9a3167. Ce span approve enregistre larkfield.approval.approver = usr-sam, larkfield.approval.role = agent, larkfield.approval.limit = 100.0, larkfield.approval.decision = approved et larkfield.approval.wait_s. Son lien indique la trace et le span de approval.request dans la trace 1, qui précise le rôle requis. L’identifiant d’exécution figure sur le premier span de chaque trace.
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
- Une exécution qui attend une personne comprend deux traces : la trace 1 se termine par
approval.request(demande d’approbation). La trace 2 commence parapprove support-resolution(approuver la résolution de soutien) et un lien de span vers cette demande. - La décision enregistre l’identifiant d’exécution, l’identifiant d’employé de la personne qui approuve, le rôle, la limite, la décision et l’attente en secondes. Les écritures et la réponse sont ses enfants.
- L’attente est un intervalle et un nombre, jamais un span ouvert : 15 h 25 min pour le double remboursement. Dans la semaine rejouée, la médiane est de 31,8 minutes et 19 attentes dépassent 8 heures.
- Un lien est une référence : si un échantillonneur ou un système de stockage supprime une trace, l’exécution perd la moitié de son histoire.
Votre projet contient maintenant les fichiers des deux dernières leçons, plus live.py et tests/test_approval_traces.py, avec 84 tests qui réussissent. Le double remboursement forme une seule histoire reliée, du billet à la personne, puis aux deux appels de remboursement. Mais le flux de travail utilise deux processus, et sa recherche de commande peut passer par un serveur MCP. Ensuite, vous garderez l’histoire complète quand le travail passera à un autre processus de traitement ou à un autre processus.
Leçon suivante : Plusieurs agents et passages de relais