Aller au contenu
English

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.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité
Leçon 9 sur 28 · Observabilité des agents d'IA : traces, coûts et pistes d'auditApprobations, personnes et temps d'attente
Aperçu du cours

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 mainEnviron 40 minutes

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 approve la 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.py est 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.

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.

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.

  • 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 vers approval.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.

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.

Deux vues en cascade à la même échelle, de 0 à 10 secondes. Trace 1, mercredi 14 octobre à 17 h 52, l'agent propose : invoke_agent support-resolver pendant 6,6 secondes, avec chat chat-strong (2160 en entrée, 47 en sortie, arrêt), execute_tool get_order (réussite), chat chat-strong (2426 en entrée, 218 en sortie, arrêt) et approval.request (nécessite un agent) à la fin. Entre les deux traces, un encadré en pointillés : attente de 15 h 25 min, aucun span ouvert; le lien relie les deux traces; wait_s = 55 505,4 est un attribut de la trace 2. Trace 2, jeudi 15 octobre à 9 h 17, Sam décide et le flux de travail écrit : approve support-resolution (approuvé par usr-sam) pendant 10 secondes, avec execute_tool request_refund (ERROR, délai dépassé, clé se terminant par 5bbb9f8a7e) pendant 10 secondes, puis execute_tool request_refund (terminé, clé se terminant par a7e-retry1) et execute_tool send_reply (envoyé).
Exécution R-1014-040 de la semaine rejouée : deux traces reliées par un lien de span, et l'attente comme écart, pas comme barre. Décision rejouée, dépassement de délai simulé, nouvelle tentative naïve et heure d'approbation.
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 :

Vue des traces de Grafana (Tempo) pour la trace « support-workflow : approve support-resolution », durée de 10,03 s, 4 spans. La liste des spans : approve support-resolution (10,03 s) avec une icône de lien à droite; dessous, execute_tool request_refund (10,02 s) marqué d'une icône d'erreur rouge, execute_tool request_refund (5,68 ms) et execute_tool send_reply (3,58 ms). Les barres montrent que le premier appel de remboursement prend les 10 secondes au complet.
Trace 2 du double remboursement dans Grafana (Tempo), issue de la semaine rejouée par l'équipe du cours à une vitesse multipliée par 1 000. L'heure de début est masquée : elle affichait le jour de l'exécution de l'équipe du cours. L'icône de lien sur le premier span ouvre la trace 1. L’image est en anglais.
  1. 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-m03
    cp $S/resolver/live.py resolver/
    cp $S/tests/test_approval_traces.py tests/
  2. Ouvrez resolver/live.py et lisez la chaîne de documentation. Trouvez ensuite approval.request dans start(), puis def 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().

  3. Exécutez les tests : python -m pytest -q. La dernière ligne indique 84 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.

  4. Supprimez work/ et rejouez le double remboursement avec les deux commandes de la dernière leçon : run, puis approve … --naive-retry.

  5. 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 en
    2 model call(s), 1 read(s), 2 write call(s), 4586 tokens in, 265 out, US$0.00000
    Trace 1 32de69cc4e8617aeb25415a04e601c6a … 6.6 s
    0.0 s |========================| 6.56 s invoke_agent support-resolver resolve rule W2
    0.0 s |========= | 2.39 s chat chat-strong 2160 in / 47 out - stop
    2.4 s | = | 0.00 s execute_tool get_order ok LK-793996
    2.4 s | ================| 4.17 s chat chat-strong 2426 in / 218 out - stop
    6.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 s
    0.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 797fbb5bbb9f8a7e
    10.0 s | =| 0.00 s execute_tool request_refund done LK-793996 9.95 RFD-LATE key 797fbb5bbb9f8a7e-retry1
    10.0 s | =| 0.00 s execute_tool send_reply sent
    Outcome: resolved
  6. 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.

  7. Affichez les deux spans que le lien relie : python show_spans.py approv.

    approval.request trace 32de69cc span 4e3da4d9 parent 030420ad
    larkfield.approval.limit = 100.0
    larkfield.approval.needs_role = agent
    larkfield.proposal.actions = 1
    approve support-resolution trace c204c637 span 71c71303 parent none
    larkfield.customer.id = C-61975
    …
    larkfield.approval.approver = usr-sam
    larkfield.approval.role = agent
    larkfield.approval.limit = 100.0
    larkfield.approval.wait_s = 0.0
    gen_ai.operation.name = approve
    larkfield.approval.decision = approved
    larkfield.run.id = T-90104-agent_structured-chat-strong-1
    …
    link to trace 32de69cc, span 4e3da4d9

    La dernière ligne de approve indique la trace et le span de approval.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.

  1. Lancez le traitement du billet de soutien :

    Fenêtre de terminal
    python -m resolver run T-90103 --variant agent_structured --model chat-strong

    La proposition liste deux actions, reship_item et create_return_label.

  2. Attendez environ une minute. Approuvez ensuite :

    Fenêtre de terminal
    python -m resolver approve T-90103-agent_structured-chat-strong-1 --as agent
    reship_item LK-640436: done (operation 221dccf204b80a63, 1 call(s))
    create_return_label LK-640436: done (operation 0f8c2e98df53719d, 1 call(s))
    Status: done
    Reply sent. Ticket: resolved.
  3. 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 s
    0.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 221dccf204b80a63
    0.0 s | ===== | 0.00 s execute_tool create_return_label done LK-640436 PLANTER key 0f8c2e98df53719d
    0.0 s | =======| 0.00 s execute_tool send_reply sent

    L’é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.

  4. Affichez les écritures avec python show_spans.py reship_item, puis python show_spans.py create_return_label. Les deux indiquent parent 4c9a3167 : l’identifiant du span approve (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?

Fenêtre de terminal
python -m resolver run T-65273
python -m resolver approve T-65273-agent-chat-small-1 --as agent
python -m obs trace T-65273
Le 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_approval

La 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é.

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.

Temps simulés : les 118 approbations de la semaine rejouée, à partir de larkfield.approval.wait_s sur les spans approve.
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 | language
0 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.

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é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.

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.

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.

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 par approve 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