Plusieurs agents et passages de relais
- Leçon 10
- 35 min
- Module 3 : Instrumenter le flux de travail
Où nous en sommes
Dans la dernière leçon, une exécution en attente d'une personne gardait une histoire cohérente : deux traces, reliées par un lien. Mais le flux de travail propose une conception où deux processus partagent un billet de soutien. Sa recherche de commande peut aussi s'exécuter dans un autre processus, par un serveur MCP. Dans cette leçon, nous transmettons le contexte de trace dans les deux cas, pour préserver toute l'histoire. Nous commençons par un changement de quart à l'hôpital.
Leçon 10 sur 28 · Observabilité des agents d'IA : traces, coûts et pistes d'auditPlusieurs agents et passages de relais
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
Gardez une seule trace quand le travail d’une exécution passe à un autre processus. Placez le contexte de trace dans le message de passage de relais et dans la requête MCP. Lisez-le à l’autre bout. Enregistrez aussi le passage de relais : qui transmet à qui, et si le contexte est arrivé.
Avant de commencerCe qu’il faut savoir et avoir sous la main
Ce que vous devez savoir
- La propagation du contexte et l’en-tête
traceparent, dans Spans, traces et contexte. - La conception à deux processus du cours sur les agents,
workers: un enquêteur lit la commande et rédige un rapport. Un résolveur décide à partir du rapport, pour le même billet. - Pour la partie MCP : ce que sont un serveur MCP et un appel d’outil, dans MCP : connecter les applications d’IA aux outils et aux données. Cette partie est facultative.
Ce qu’il vous faut sur votre ordinateur
- Le projet dans l’état laissé par la dernière leçon : 84 tests réussissent et
show_spans.pyest dans le dossier du projet. - Un terminal dans
observable-workflow, avec l’environnement virtuel activé. La partie MCP installe un paquet supplémentaire,mcp.
Testé sur macOS (Apple silicon) avec Python 3.12.13 et le SDK MCP 2.3.0. Les commandes Windows et Linux sont écrites, mais n’ont pas été exécutées.
Un changement de quart à l’hôpital
Section intitulée « Un changement de quart à l’hôpital »À 7 h, l’infirmière de nuit passe le relais à celle de jour. Elle donne une courte note : les événements de la nuit, les points à surveiller et le numéro de dossier du patient. L’infirmière de jour écrit tout ce qu’elle fait dans ce dossier.
Si la note omet le numéro de dossier, l’infirmière de jour fait quand même son travail. Mais elle l’inscrit dans un nouveau dossier vide. Le lendemain matin, un médecin lit le dossier du patient et ne voit rien après 7 h. Le travail a eu lieu, mais il manque une partie de l’histoire.
La note doit contenir la référence à l’histoire, pas seulement les faits. C’est toute l’idée de cette leçon.
Le problème : deux processus, deux histoires
Section intitulée « Le problème : deux processus, deux histoires »Dans la conception workers, l’enquêteur lit la commande, puis transmet un rapport au résolveur. En production, les deux sont des processus distincts : le rapport est un message de l’un à l’autre. Ici, le projet fonctionne de la même façon : le résolveur prend son parent dans le message, pas dans la mémoire du processus.
Le projet possède un réglage qui omet la référence, comme lors d’un passage de relais négligent. L’équipe du cours a exécuté le même billet deux fois avec le code de cette leçon, avec et sans le contexte. Vous exécuterez les mêmes commandes après la prochaine section :
python -m resolver run T-90103 --variant workersOBS_HANDOFF_CONTEXT=off python -m resolver run T-90103 --variant workerspython -m obs runsDans PowerShell, définissez d’abord la variable, $env:OBS_HANDOFF_CONTEXT = "off", exécutez le billet, puis supprimez-la avec Remove-Item Env:OBS_HANDOFF_CONTEXT. La liste des exécutions semble normale :
run ticket started outcome model tools appr cost US$ secs model flagsT-90103-workers-chat-small-1 T-90103 … asked_customer 3 1 0 0.00000 4.9 chat-small -T-90103-workers-chat-small-2 T-90103 … asked_customer 3 1 0 0.00000 4.9 chat-small -2 run(s), 0 flaggedLes deux exécutions ont effectué trois appels de modèle et un appel d’outil. obs runs regroupe les spans (intervalles de travail) par identifiant d’exécution, donc il les trouve tous. Mais un stockage de traces comme Tempo regroupe les spans par trace. Regardez la trace de la deuxième exécution :
Trace 1 aed2bc3da6441e9d985419a7153381da … 4.9 s 0.0 s |========================| 4.94 s invoke_workflow support-resolution ask_customer rule W5 0.0 s |================= | 3.46 s invoke_agent investigator finished 0.0 s |====== | 1.26 s chat chat-small 694 in / 21 out - tool_calls 1.3 s | = | 0.00 s execute_tool get_order ok LK-640436 1.3 s | =========== | 2.20 s chat chat-small 942 in / 259 out - tool_calls 4.9 s | =| 0.00 s execute_tool send_reply sent
Trace 2 cd65f9ddbf0b8f6e1177ccde15517aaa … 1.5 s 0.0 s |========================| 1.49 s chat chat-small 2143 in / 92 out - stop 0.0 s |========================| 1.49 s invoke_agent resolver handoff context missingLa trace 1 a un trou de 3,5 à 4,9 secondes. L’exécution dure 4,94 secondes, mais ses enfants se terminent à 3,46 secondes. La décision, l’appel qui a choisi de demander une photo au client, se trouve dans une autre trace, sans parent. Dans Grafana, la recherche de la trace de ce billet montre l’enquêteur et la réponse, mais pas la décision. C’est le dossier vide de l’infirmière de jour.
L’idée : le contexte voyage dans le message
Section intitulée « L’idée : le contexte voyage dans le message »La propagation du contexte comporte deux étapes. L’expéditeur écrit le contexte de trace courant dans le message. Le destinataire le lit d’abord et en fait le parent de son travail. Le format standard du W3C tient sur une ligne, le traceparent :
00-7dad6f36…-ea73cacf…-01Il contient quatre parties : la version (00), l’identifiant de trace (32 caractères hexadécimaux), l’identifiant du span parent (16 caractères) et les indicateurs (01 : échantillonné). Avec l’identifiant de trace et celui du span parent, le span du destinataire rejoint le même arbre.
Description textuelle du diagramme
Le travail de l’enquêteur se termine par un rapport de 17 éléments. Le flux de travail place le rapport dans un message pour le résolveur, avec le contexte de trace courant comme traceparent. Celui-ci désigne la trace 7dad6f36 et le span ea73cacf, le span d’exécution du flux de travail. Le résolveur lit d’abord le traceparent, puis démarre son propre span, dont le parent est le span ea73cacf. Sans le traceparent, le span du résolveur n’a pas de parent et démarre une nouvelle trace.
Le passage de relais devient lui aussi une preuve. Le span du résolveur enregistre larkfield.handoff.from = investigator, larkfield.handoff.to = resolver, la taille du rapport (larkfield.handoff.report_items) et larkfield.handoff.context : propagated (propagé) ou missing (manquant). Chaque processus possède aussi son propre identifiant d’agent : support-workflow/investigator et support-workflow/resolver. Le premier span de l’exécution est maintenant invoke_workflow support-resolution, car le code, et non un agent, décide de l’ordre des deux processus.
Un passage de relais défectueux ne doit pas masquer l’exécution. Quand le contexte manque, le span du résolveur enregistre quand même l’identifiant d’exécution. C’est pourquoi obs runs a trouvé les deux exécutions. Une recherche par identifiant d’exécution fonctionne toujours; seul l’arbre est brisé.
Ajouter le passage de relais et MCP à votre projet
Section intitulée « Ajouter le passage de relais et MCP à votre projet »-
Copiez les fichiers de cette leçon : les deux processus (
agent.py), le client et le serveur MCP, les dépendances MCP et les deux tests.Fenêtre de terminal S=../nextia-learning-labs/C31/snapshots/end-of-m03cp $S/resolver/agent.py $S/resolver/mcp_tools.py $S/resolver/mcp_server.py resolver/cp $S/requirements-mcp.txt .cp $S/tests/test_handoff.py $S/tests/test_mcp.py tests/Fenêtre de terminal $S = "..\nextia-learning-labs\C31\snapshots\end-of-m03"Copy-Item $S\resolver\agent.py, $S\resolver\mcp_tools.py, $S\resolver\mcp_server.py resolver\Copy-Item $S\requirements-mcp.txt .Copy-Item $S\tests\test_handoff.py, $S\tests\test_mcp.py tests\Fenêtre de terminal S=../nextia-learning-labs/C31/snapshots/end-of-m03cp $S/resolver/agent.py $S/resolver/mcp_tools.py $S/resolver/mcp_server.py resolver/cp $S/requirements-mcp.txt .cp $S/tests/test_handoff.py $S/tests/test_mcp.py tests/ -
Ouvrez
resolver/agent.pyet trouvezhandoff_message. Cette fonction construit le message avec le rapport et, quandOBS_HANDOFF_CONTEXTvauton(activé), avectraceparent. Trouvez ensuiteobserve.agent_span("resolver", model, parent_message=message). Dansresolver/observe.py,agent_spanlit le traceparent dans le message et en fait le contexte parent. -
Exécutez les tests :
python -m pytest -q. Sans le paquet MCP, la dernière ligne indique86 passed, 1 skipped, 1 deselected(86 réussis, 1 ignoré, 1 exclu). Le test ignoré est celui de MCP.tests/test_handoff.pyvérifie les deux cas : une trace avec le contexte, deux traces sans lui. -
Supprimez
work/et exécutez les deux commandes du problème ci-dessus. Lisez ensuite la première exécution :python -m obs trace T-90103-workers-chat-small-1.Trace 1 7dad6f369cd6a8ffa30ff4069b8d28c7 … 5.0 s0.0 s |========================| 4.96 s invoke_workflow support-resolution ask_customer rule W50.0 s |================= | 3.46 s invoke_agent investigator finished0.0 s |====== | 1.26 s chat chat-small 694 in / 21 out - tool_calls1.3 s | = | 0.00 s execute_tool get_order ok LK-6404361.3 s | =========== | 2.20 s chat chat-small 942 in / 259 out - tool_calls3.5 s | ========| 1.49 s chat chat-small 2143 in / 92 out - stop3.5 s | ========| 1.49 s invoke_agent resolver handoff context propagated4.9 s | =| 0.01 s execute_tool send_reply sentUne seule trace. Le span du résolveur commence à 3,5 secondes, là où l’enquêteur a terminé, et contient son appel de modèle.
obs traceaffiche l’appel de modèle du résolveur juste au-dessus de son span, car les deux commencent au même moment. -
Affichez les spans des deux processus :
python show_spans.py invoke_agent. Le résolveur de la première exécution indiqueparent ea73cacf(parent ea73cacf; votre identifiant sera différent). C’est l’identifiant du spaninvoke_workflow, le span courant au moment de l’écriture du message. Le résolveur de la deuxième exécution indiqueparent none(aucun parent) etlarkfield.handoff.context = missing.
Les deux exécutions du même billet, côte à côte :
Description textuelle du diagramme
Avec le contexte, une trace contient le flux de travail, l’enquêteur avec ses deux appels et sa lecture, le résolveur avec son appel, et la réponse. Sans le contexte, la trace 1 contient l’enquêteur et la réponse, avec un trou là où le résolveur a travaillé. La trace 2 contient le résolveur et son appel, seuls, sans parent : elle commence à zéro sur sa propre horloge.
Passer à un autre processus : la recherche de commande par MCP
Section intitulée « Passer à un autre processus : la recherche de commande par MCP »Le cours sur les agents propose un serveur MCP facultatif pour la recherche de commande. Avec RESOLVER_TOOLS=mcp, le flux de travail le démarre comme deuxième processus et appelle son outil get_order. C’est une véritable frontière entre processus, pas une simulation.
Vous n’écrivez pas la propagation ici. Le SDK Python MCP, version 2.3.0, s’instrumente lui-même. Son client crée un span pour chaque requête et place le traceparent dans le champ params._meta de la requête. Son serveur le lit. Une condition : le SDK utilise le fournisseur de traceurs global d’OpenTelemetry. Le flux de travail doit donc enregistrer son propre fournisseur comme fournisseur global. resolver/mcp_tools.py le fait une fois par processus, dans _global_provider().
Description textuelle du diagramme
Dans le span execute_tool get_order, le flux de travail demande au client MCP d’appeler l’outil. Le client du SDK crée un span CLIENT, MCP send tools/call get_order, et place le traceparent dans le champ _meta de la requête. Le processus serveur le lit et crée un span SERVER, tools/call get_order, dans la même trace, comme enfant du span client. Les deux processus écrivent leurs spans dans le même dossier de télémétrie, donc la trace contient les deux côtés.
-
Installez le paquet MCP :
python -m pip install -r requirements-mcp.txt. Exécutez ensuite les tests à nouveau : la dernière ligne indique87 passed, 1 deselected(87 réussis, 1 exclu). -
Supprimez
work/. Exécutez le billet avec la recherche MCP et lisez sa trace. Chaque appel démarre le serveur, donc l’exécution prend environ une seconde de plus.Fenêtre de terminal RESOLVER_TOOLS=mcp python -m resolver run T-80008python -m obs trace T-80008Fenêtre de terminal $env:RESOLVER_TOOLS = "mcp"python -m resolver run T-80008Remove-Item Env:RESOLVER_TOOLSpython -m obs trace T-80008Fenêtre de terminal RESOLVER_TOOLS=mcp python -m resolver run T-80008python -m obs trace T-80008Trace 1 0b3cc8d8dfb66eda60e19ca6dae8bcfe … 4.5 s0.0 s |========================| 4.48 s invoke_agent support-resolver reply_only rule W10.0 s |===== | 0.96 s chat chat-small 2169 in / 21 out - tool_calls1.0 s | ============= | 2.33 s execute_tool get_order ok LK-5811061.0 s | ===== | 1.00 s MCP send initialize1.9 s | = | 0.00 s initialize2.0 s | = | 0.01 s MCP send tools/call get_order2.0 s | = | 0.01 s tools/call get_order ok2.0 s | = | 0.00 s MCP send tools/list2.0 s | = | 0.00 s tools/list3.3 s | =======| 1.18 s chat chat-small 2411 in / 96 out - tool_calls4.5 s | =| 0.01 s execute_tool send_reply sent -
Trouvez le span du serveur avec
python show_spans.py tools/call. Pourtools/call get_order,parent(parent) correspond à l’identifiant du spanMCP send tools/call get_order, dans la même trace. Il contient aussimcp.method.name = tools/call, un nom choisi par le SDK, pas par nous.
Deux choses semblent étranges dans cette trace, mais toutes deux reflètent la réalité. Le SDK envoie aussi initialize (initialiser) et tools/list (liste des outils), le démarrage du protocole. Ces requêtes ont donc aussi des spans. Et les décalages ne sont pas exacts. Les spans du SDK utilisent l’horloge réelle. Ceux du flux de travail utilisent l’horloge d’exécution, qui avance selon le temps de modèle enregistré. Ici, MCP send initialize commence en même temps que le span de l’outil. Mais dans une autre exécution de l’équipe du cours, il commençait 0,6 seconde avant, dans l’appel de modèle. Dans cette trace, lisez l’arbre, pas les positions exactes.
À vous : quel contexte le résolveur reçoit-il?
Section intitulée « À vous : quel contexte le résolveur reçoit-il? »Le résolveur a pris son parent dans le span courant au moment de l’écriture du message : le span d’exécution du flux de travail. Changez d’abord une chose mentalement : et si handoff_message était appelée dans le span de l’enquêteur?
- Prédisez : quel serait le parent du résolveur, et à quoi ressemblerait le diagramme en cascade?
- Vérifiez votre réponse dans le code. Dans
resolver/agent.py, la lignemessage = handoff_message(report)vient après le blocwith observe.agent_span("investigator", …). Le span de l’enquêteur est donc déjà terminé. - Décidez quel arbre est préférable, et pourquoi.
Discussion
Dans le span de l’enquêteur, le traceparent désignerait l’enquêteur. Le résolveur serait alors son enfant, un niveau plus bas. Le diagramme en cascade montrerait le résolveur dans un span déjà terminé. Les deux arbres sont valides dans OpenTelemetry. Le projet a choisi le flux de travail comme parent, car celui-ci décide de l’ordre des deux processus. Les processus sont au même niveau, et les attributs du passage de relais indiquent qui a transmis à qui. Une équipe doit choisir une règle et la conserver, pour que toutes les traces de toutes les conceptions se lisent de la même façon.
Erreur courante
Les spans MCP sont absents
Symptôme : avec RESOLVER_TOOLS=mcp, l’exécution fonctionne et execute_tool get_order contient larkfield.mcp.server = larkfield-orders. Mais aucun span MCP send … ou tools/call … n’apparaît. Ou ils apparaissent dans leur propre trace.
Cause : le SDK MCP écrit ses spans avec le fournisseur de traceurs global d’OpenTelemetry. Si l’application n’enregistre jamais son fournisseur comme fournisseur global, les spans du SDK vont vers un fournisseur qui ne fait rien. Si le processus serveur n’a pas d’exportateur vers la même destination, sa moitié est perdue.
Diagnostic : python show_spans.py MCP n’affiche rien. Vérifiez que _global_provider() dans resolver/mcp_tools.py s’exécute avant le premier appel. Vérifiez aussi que le serveur reçoit OBS_TELEMETRY dans son environnement (_call() le transmet).
Correction : enregistrez le fournisseur une seule fois avec trace.set_tracer_provider(...) dans chaque processus qui utilise une bibliothèque instrumentée. Donnez aussi les mêmes paramètres d’exportateur à tous les processus. En production, chaque processus exporte vers le Collector, qui ne tient pas compte du processus d’origine d’un span.
Quand propager le contexte, et à quel coût
Section intitulée « Quand propager le contexte, et à quel coût »Propagez le contexte à chaque frontière où la même exécution continue : message entre processus, appel HTTP ou MCP, tâche dans une file d’attente. Le coût est une courte chaîne dans chaque message. Sans elle, chaque partie de l’exécution est correcte séparément, mais personne ne peut voir l’ensemble.
Enregistrez aussi le passage de relais : qui transmet à qui, la quantité transmise et si le contexte est arrivé. Un passage de relais défectueux devient alors quelque chose que vous pouvez compter, avec larkfield.handoff.context = missing, plutôt qu’un mystère.
Ne propagez pas le contexte quand un nouveau travail commence sans faire partie de l’exécution. Un rapport nocturne qui lit plusieurs exécutions en est un exemple. Reliez-le plutôt à ces exécutions, comme pour l’approbation. Et rappelez-vous ce que la trace MCP a montré : les spans créés par d’autres bibliothèques utilisent leurs propres noms et leur propre horloge. Fixez les versions de ces bibliothèques, comme le projet le fait pour le SDK MCP.
Vérification des connaissances
Section intitulée « Vérification des connaissances »Vérifiez votre compréhension
Avec OBS_HANDOFF_CONTEXT=off, obs runs affiche toujours une exécution avec trois appels de modèle. Tomás dit donc : « Rien ne fonctionne mal. » Qu'est-ce qui ne fonctionne pas, et qui le remarquerait en premier?
Afficher la réponse
obs regroupe les spans par identifiant d’exécution. Le span du résolveur enregistre toujours cet identifiant, donc les nombres semblent corrects. Mais la trace est brisée : le span du résolveur n’a aucun parent et commence une deuxième trace. Grafana et tous les systèmes de stockage de traces regroupent les spans par trace. Dans ces systèmes, la trace de l’exécution présente un vide à l’endroit où la décision a été prise. La décision apparaît dans une trace sans lien avec elle. La personne qui ouvre la trace d’une réponse étrange le remarque en premier. L’étape qui a choisi la réponse est absente.
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
Que contient un traceparent comme 00-7dad6f36…-ea73cacf…-01? Pourquoi le deuxième identifiant est-il celui d'un span et non de l'exécution?
Afficher la réponse
Il contient la version (00), l’identifiant de trace, l’identifiant du span parent (ea73cacf…, le span d’exécution du flux de travail) et les indicateurs (01 : échantillonné). Le destinataire a besoin de l’identifiant du span parent pour rattacher son span au bon endroit dans l’arbre. Le placer dans la bonne trace ne suffit pas. L’identifiant d’exécution est notre propre étiquette. Il regroupe les spans d’une exécution, mais n’indique pas où placer un nouveau span dans l’arbre. Un système de stockage de traces ne l’utilise pas pour construire les arbres.
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 pratique : montrez, avec votre télémétrie, que le span du serveur MCP appartient à la trace de l'exécution, dans un autre processus.
Afficher la réponse
Exécutez RESOLVER_TOOLS=mcp python -m resolver run T-80008, puis python show_spans.py tools/call. Le résultat montre deux spans avec le même identifiant de trace que l’exécution. Le premier est MCP send tools/call get_order, le client dans le processus du flux de travail. Son parent est execute_tool get_order. Le deuxième est tools/call get_order, le serveur, avec mcp.method.name = tools/call et larkfield.mcp.server = larkfield-orders. Son parent est le span du client. Le processus serveur a écrit le span du serveur. Il a reçu OBS_TELEMETRY du flux de travail.
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
- Propagation du contexte : l’expéditeur écrit le
traceparent(contexte de trace parent) dans le message. Le destinataire le lit d’abord et en fait le parent de son travail. - Les deux processus transmettent un message contenant le rapport et le contexte. Sans contexte, le résolveur commence une deuxième trace sans parent, alors que
obs runs(liste des exécutions) semble toujours normal. - Le passage de relais est enregistré : l’expéditeur, le destinataire, la taille du rapport et la réception ou non du contexte.
- Le SDK MCP propage lui-même le contexte dans
_meta(métadonnées), avec le fournisseur global de traceurs. Ses spans utilisent l’heure de l’horloge et ses propres noms.
Votre projet contient maintenant les fichiers des trois dernières leçons, plus agent.py, mcp_tools.py, mcp_server.py, requirements-mcp.txt et deux tests. Les 86 tests réussissent (et le test MCP réussit avec son paquet). Chaque partie d’une exécution forme une seule histoire, du billet à la personne, puis à l’écriture. Mais chaque appel de modèle passe aussi par la passerelle de modèles de Larkfield en production. Celle-ci conserve ses propres enregistrements des mêmes appels. Ensuite, vous comparerez ce que voit la passerelle avec ce que voit l’application, puis vous relierez les deux.
Leçon suivante : Ce que voit la passerelle et ce que voit l'application