Aller au contenu
English

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.

Lue depuis YouTube. Rien ne se charge depuis YouTube avant que vous appuyiez sur lecture. Confidentialité
Leçon 10 sur 28 · Observabilité des agents d'IA : traces, coûts et pistes d'auditPlusieurs agents et passages de relais
Aperçu du cours

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

Ce que vous devez savoir

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

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

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 :

Fenêtre de terminal
python -m resolver run T-90103 --variant workers
OBS_HANDOFF_CONTEXT=off python -m resolver run T-90103 --variant workers
python -m obs runs

Dans 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 flags
T-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 flagged

Les 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 missing

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

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…-01

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

L'enquêteur, invoke_agent investigator, effectue deux appels de modèle et un get_order, puis rédige un rapport de 17 éléments. Une flèche, « le flux de travail écrit le rapport et le contexte courant », mène au message de passage de relais : de investigator à resolver, le rapport de 17 éléments et traceparent 00-7dad6f36…-ea73cacf…-01. Une flèche, « le résolveur lit d'abord le contexte, puis démarre son span », mène à invoke_agent resolver : son parent est le span ea73cacf…, le span d'exécution du flux de travail. Une flèche en pointillé, OBS_HANDOFF_CONTEXT=off, mène à : sans traceparent, le résolveur démarre une nouvelle trace sans parent.
Le message de passage de relais contient le rapport et le contexte de trace. Le span du résolveur prend son parent dans le message. Identifiants tirés de l'exécution de l'équipe du cours.
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é.

  1. 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-m03
    cp $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/
  2. Ouvrez resolver/agent.py et trouvez handoff_message. Cette fonction construit le message avec le rapport et, quand OBS_HANDOFF_CONTEXT vaut on (activé), avec traceparent. Trouvez ensuite observe.agent_span("resolver", model, parent_message=message). Dans resolver/observe.py, agent_span lit le traceparent dans le message et en fait le contexte parent.

  3. Exécutez les tests : python -m pytest -q. Sans le paquet MCP, la dernière ligne indique 86 passed, 1 skipped, 1 deselected (86 réussis, 1 ignoré, 1 exclu). Le test ignoré est celui de MCP. tests/test_handoff.py vérifie les deux cas : une trace avec le contexte, deux traces sans lui.

  4. 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 s
    0.0 s |========================| 4.96 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
    3.5 s | ========| 1.49 s chat chat-small 2143 in / 92 out - stop
    3.5 s | ========| 1.49 s invoke_agent resolver handoff context propagated
    4.9 s | =| 0.01 s execute_tool send_reply sent

    Une 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 trace affiche l’appel de modèle du résolveur juste au-dessus de son span, car les deux commencent au même moment.

  5. Affichez les spans des deux processus : python show_spans.py invoke_agent. Le résolveur de la première exécution indique parent ea73cacf (parent ea73cacf; votre identifiant sera différent). C’est l’identifiant du span invoke_workflow, le span courant au moment de l’écriture du message. Le résolveur de la deuxième exécution indique parent none (aucun parent) et larkfield.handoff.context = missing.

Les deux exécutions du même billet, côte à côte :

Trois diagrammes en cascade sur une échelle de 0 à 5 secondes. Avec le contexte dans le message, une trace : invoke_workflow support-resolution pendant 4,9 s; en dessous, invoke_agent investigator pendant 3,5 s avec chat chat-small (694 en entrée, 21 en sortie, tool_calls), execute_tool get_order (ok) et chat chat-small (942 en entrée, 259 en sortie, tool_calls); puis invoke_agent resolver (contexte du passage de relais propagé) de 3,5 à 4,9 s avec chat chat-small (2143 en entrée, 92 en sortie, stop); puis execute_tool send_reply (sent). Sans le contexte, trace 1 : la même chose, mais sans le résolveur : un trou de 3,5 à 4,9 secondes. Sans le contexte, trace 2 : invoke_agent resolver (contexte du passage de relais manquant) avec son chat chat-small, seul, commençant à 0.
T-90103 avec la conception à deux processus, avec et sans le contexte de trace dans le message de passage de relais. Appels de chat-small rejoués.
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().

Une séquence avec trois participants : le processus du flux de travail, dans le span execute_tool get_order; le client MCP, le SDK MCP; et le processus serveur MCP, larkfield-orders. Le flux de travail appelle get_order(order_id). Le client crée le span « MCP send tools/call get_order », de type CLIENT, enfant de execute_tool. Il envoie tools/call get_order avec params._meta.traceparent = 00-…-01. Le serveur crée le span « tools/call get_order », de type SERVER, dans la même trace, avec le span client comme parent. Le serveur renvoie la commande, et le client renvoie ok, LK-581106. Les deux processus écrivent dans le même dossier de télémétrie : une seule trace.
Le SDK MCP transmet le contexte de trace dans le champ _meta de la requête. Le span du serveur rejoint ainsi la trace du flux de travail dans un autre processus.
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.

  1. Installez le paquet MCP : python -m pip install -r requirements-mcp.txt. Exécutez ensuite les tests à nouveau : la dernière ligne indique 87 passed, 1 deselected (87 réussis, 1 exclu).

  2. 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-80008
    python -m obs trace T-80008
    Trace 1 0b3cc8d8dfb66eda60e19ca6dae8bcfe … 4.5 s
    0.0 s |========================| 4.48 s invoke_agent support-resolver reply_only rule W1
    0.0 s |===== | 0.96 s chat chat-small 2169 in / 21 out - tool_calls
    1.0 s | ============= | 2.33 s execute_tool get_order ok LK-581106
    1.0 s | ===== | 1.00 s MCP send initialize
    1.9 s | = | 0.00 s initialize
    2.0 s | = | 0.01 s MCP send tools/call get_order
    2.0 s | = | 0.01 s tools/call get_order ok
    2.0 s | = | 0.00 s MCP send tools/list
    2.0 s | = | 0.00 s tools/list
    3.3 s | =======| 1.18 s chat chat-small 2411 in / 96 out - tool_calls
    4.5 s | =| 0.01 s execute_tool send_reply sent
  3. Trouvez le span du serveur avec python show_spans.py tools/call. Pour tools/call get_order, parent (parent) correspond à l’identifiant du span MCP send tools/call get_order, dans la même trace. Il contient aussi mcp.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.

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?

  1. Prédisez : quel serait le parent du résolveur, et à quoi ressemblerait le diagramme en cascade?
  2. Vérifiez votre réponse dans le code. Dans resolver/agent.py, la ligne message = handoff_message(report) vient après le bloc with observe.agent_span("investigator", …). Le span de l’enquêteur est donc déjà terminé.
  3. 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.

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

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.

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.

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