Aller au contenu
English

Trouver des défaillances dans des exécutions d'agents publiques

  • Étude de cas 1
  • 150 min
  • Facultative · 1 étude de cas requise pour le certificat

Où nous en sommes

Dans ce cours, nous avons trouvé des modèles de défaillance dans les traces du flux de travail de Larkfield. Nous avons utilisé nos propres règles et requêtes. Mais nous les avions écrites pour des exécutions que nous avions construites, et nous connaissions chaque réponse. Dans cette étude de cas, nous essayons la même méthode sur 456 exécutions d'un agent d'une autre équipe. Quelqu'un d'autre les a enregistrées et notées. Nous les convertissons en OpenTelemetry, les lisons avec obs et comptons les défaillances que les traces peuvent détecter.

Étude de cas 1 sur 3 · Observabilité des agents d'IA : traces, coûts et pistes d'auditTrouver des défaillances dans des exécutions d'agents publiques
Aperçu du cours

Ce que vous saurez faire

Découvrez quelles défaillances d’un agent d’IA ses traces peuvent montrer. Vous convertissez en OpenTelemetry 456 exécutions réelles enregistrées d’un agent ouvert de service à la clientèle, avec les noms du cours. Vous les lisez avec obs, appliquez les règles de défaillance du cours et adaptez ces règles à cet agent. Vous vérifiez chaque signalement à l’aide de la note du banc d’essai. Ensuite, vous mesurez combien d’exécutions échouées un réviseur trouve avec chaque méthode. Vous testez la méthode sur les exécutions d’un autre modèle et rédigez une recommandation.

Étude de casPièce de portfolio

Licence
MIT
Durée
Environ 2,5 heures
S’exécute dans
VS Code, Python 3.12+
Compétences utilisées
  • Convertir des exécutions enregistrées en OpenTelemetry
  • Conventions GenAI
  • Lire des exécutions avec obs
  • Règles de défaillance
  • Adapter les règles à un autre agent
  • Taux de réussite des signalements et taux de base
  • Un budget de révision comme mesure
  • Nouvelles données d'entrée
  • Recommandation

Décompressez le projet de départ, ouvrez le dossier dans VS Code et suivez les étapes ci-dessous. Elles commencent par un nouvel environnement virtuel.

Cette étude de cas est un dossier de projet, pas un carnet (notebook) Jupyter. Elle lit les exécutions avec l’outil obs du cours, depuis votre projet de cours. Elle écrit des spans (segments de trace) avec les paquets OpenTelemetry déjà présents dans le projet. Un carnet dans Colab n’aurait ni l’un ni les autres. Le dossier est petit (environ 1,4 Mo) et n’ajoute aucun paquet.

Avant de commencerCe qu’il faut savoir et avoir sous la mainEnviron 150 minutes

Ce que vous devez savoir

Cette étude de cas utilise l’ensemble du cours. Ces leçons sont les plus importantes :

Cette page enseigne deux nouvelles idées. Vous convertissez des exécutions enregistrées par un autre système. Vous comparez aussi des façons de choisir les exécutions qu’une personne révise.

Ce qu’il vous faut sur votre ordinateur

  • Le projet de cours à la fin du cours, dans ~/projects/observable-workflow, avec son environnement virtuel. Si le vôtre ne fonctionne plus, téléchargez l’instantané end-of-m08 du cours et suivez son README.
  • Grafana est facultatif. Chaque étape fonctionne avec obs et les commandes de l’étude de cas.

Testé sur macOS (Apple silicon) avec Python 3.12.13 et les paquets du projet de cours. Les commandes Windows (PowerShell) et Linux sont écrites, mais n’ont pas été exécutées.

Larkfield veut un agent pour sa boutique en ligne. Il annulera et modifiera des commandes, et traitera les retours et les échanges. Amira (elle) le construira. Priya (elle) est responsable de la qualité et pose d’abord la question : « Quand cet agent échouera, nos traces le montreront-elles? »

Tomás (il) pense que la réponse est simple : « Nous avons cinq règles de défaillance. Elles trouveront aussi ses défaillances. » Priya n’en est pas certaine. Les règles ont été écrites pour le flux de travail de soutien. Elles ont été vérifiées sur une semaine construite pour le cours, avec un fichier de réponses. Un nouvel agent échoue à sa façon.

Priya propose donc une répétition sur des exécutions publiques d’un agent semblable, que quelqu’un d’autre a enregistrées et notées. Il faut les convertir en traces du cours, appliquer les règles et compter leurs résultats en les comparant aux notes. Avant le lancement, l’équipe devra enregistrer autrement tout ce que les règles ne détectent pas.

Vous construirez un rapport de défaillance avec des preuves pour 456 exécutions d’un agent ouvert. Il contient des traces converties, une référence de base, des règles adaptées et une mesure équitable. Il précise aussi ce que les traces ne peuvent pas voir. Il se termine par un test sur de nouvelles données d’entrée et une recommandation.

Un flux de haut en bas. L'échantillon fixe, 456 exécutions avec vérifications SHA-256, passe à la conversion avec le SDK OpenTelemetry. La conversion écrit deux éléments : telemetry/design/traces.jsonl.gz et truth.json, qui contient la note, gardée à part. Les traces passent à obs runs, trace et find, l'outil du cours inchangé, et, facultativement, à Grafana avec TraceQL. Viennent ensuite les règles : celles du cours, puis celles de la boutique. Chaque signalement est vérifié à l'aide de la note dans truth.json. Puis une mesure : les exécutions échouées trouvées en 92 révisions. Enfin, la recommandation et les nouvelles données d'entrée : les exécutions d'un autre modèle, qui reviennent à la conversion.
La méthode de cette étude de cas. La note reste dans son propre fichier, pour qu'aucune règle ne puisse la lire.
Description textuelle du diagramme

Les exécutions sont converties en traces, lues avec obs et signalées par des règles. La note reste à part, dans truth.json, et permet de vérifier chaque signalement. Une mesure compare les méthodes, et de nouvelles données d’entrée testent la recommandation.

  1. Téléchargez le projet de départ depuis l’encadré en haut de cette page. Décompressez-le dans ~/projects, pour placer le dossier public-agent-runs à côté de observable-workflow.

  2. Dans VS Code, choisissez File > Open Folder (fichier, ouvrir un dossier) et ouvrez public-agent-runs. Ouvrez ensuite un terminal : Terminal > New Terminal (terminal, nouveau terminal).

  3. Activez l’environnement virtuel du projet de cours :

    Fenêtre de terminal
    source ../observable-workflow/.venv/bin/activate

    Si votre projet de cours est ailleurs, définissez OBS_PROJECT avec ce dossier (PowerShell : $env:OBS_PROJECT = "C:\path\to\observable-workflow").

  4. Exécutez les tests : python -m pytest -q. Le projet de départ contient trois parties à compléter, donc six tests échouent :

    FAILED tests/test_convert.py::test_tool_kinds_statuses_and_the_order_id - Ass...
    FAILED tests/test_rules.py::test_three_different_orders_are_not_a_loop - Asse...
    FAILED tests/test_rules.py::test_two_different_writes_are_not_a_duplicate - A...
    FAILED tests/test_rules.py::test_the_same_write_twice_is_a_duplicate - KeyErr...
    FAILED tests/test_rules.py::test_the_policys_second_lookup_is_not_a_hidden_error
    FAILED tests/test_rules.py::test_a_refused_change_that_was_never_repaired - K...
    6 failed, 13 passed in 0.28s
  5. Ouvrez un deuxième terminal dans le projet de cours : cd ~/projects/observable-workflow, puis activez le même environnement. Vous y exécutez obs, sans le modifier.

Le projet terminé se trouve dans le même encadré, pour le comparer à votre travail. Toutes les sorties de cette page proviennent de ce projet.

Les données sont les résultats publiés de τ²-bench, un banc d’essai ouvert d’agents d’IA qui discutent avec des clients et utilisent des outils. Son domaine de vente au détail représente le service de soutien d’une boutique en ligne. Un client veut annuler ou modifier une commande, retourner ou échanger des articles, ou changer une adresse. L’agent dispose de 16 outils et d’une politique écrite. Un deuxième modèle joue le client et termine la conversation lorsqu’il est satisfait.

Priya avait besoin de quatre éléments : l’heure de chaque étape, les jetons de chaque appel de modèle, les appels d’outils avec leurs erreurs, et une note. Les exécutions du premier τ-bench n’ont ni heures ni nombres de jetons. D’autres ensembles ouverts contiennent des décisions isolées ou interdisent l’utilisation commerciale. τ²-bench possède les quatre éléments. Ses exécutions de télécommunications servent de données à Contenir un agent emballé, dans le cours Gouverner les agents d’IA : passerelles, registres et contrôles; ses exécutions de vente au détail sont plus proches de Larkfield.

Les exécutions de conception sont 456 exécutions de gpt-4.1 : 114 tâches, chacune exécutée 4 fois. Nous les étudions et adaptons les règles à partir d’elles. Les exécutions de Claude 3.7 Sonnet, o4-mini et gpt-4.1-mini sur les mêmes tâches seront les nouvelles données d’entrée à la fin. Une exécution contient ces champs :

Champ Ce qu’il contient
id, task_id, trial l’exécution; une des 114 tâches; chaque tâche a été exécutée 4 fois
messages[] chaque message : son expéditeur (assistant, user, tool, soit assistant, utilisateur, outil) et son heure
in, out, cost, finish un appel de modèle de l’agent : nombres de jetons enregistrés, coût enregistré par le banc d’essai, raison de fin
calls[] les outils demandés par le modèle : name et args
error, error_text un outil a répondu avec une erreur et son court texte, comme Error: User not found (erreur : utilisateur introuvable)
end comment le client a terminé la conversation : stop, transfer ou out_of_scope (arrêt, transfert ou hors portée)
grade la récompense du banc d’essai (1 ou 0) et ses vérifications : gardées à part, jamais dans un span

Le banc d’essai donne une récompense de 1 lorsque deux conditions sont remplies. La base de données de la boutique finit exactement dans l’état attendu par la tâche. L’agent a aussi communiqué au client ce que la tâche exige.

L’unité est une exécution : une conversation, du message d’accueil de l’agent au dernier message du client. Elle devient une trace.

La vérité est la note du banc d’essai. Elle joue le rôle du fichier truth.json de la semaine du cours. Un système en production n’a pas de note, donc aucune règle ne peut la lire. Le convertisseur l’écrit dans son propre fichier, et seule la vérification la lit.

La mesure. L’équipe de Priya révise une exécution sur cinq, comme dans La qualité à partir des exécutions en production. Ici, cela représente 92 exécutions sur 456. Une méthode est meilleure lorsque davantage des 92 exécutions révisées ont réellement échoué. Les signalements d’une règle indiquent au réviseur quelles exécutions lire en premier.

Une nouvelle idée : taux de réussite des signalements et taux de base

Section intitulée « Une nouvelle idée : taux de réussite des signalements et taux de base »

Imaginez un avertisseur de fumée qui sonne chaque fois que quelqu’un fait griller du pain. Bientôt, personne ne l’écoute. La question utile est : quand il sonne, à quelle fréquence y a-t-il un feu?

Un signalement fonctionne de la même façon. Son taux de réussite est la proportion des exécutions signalées qui ont réellement échoué. Comparez-le au taux de base : la proportion de toutes les exécutions qui ont échoué. Un signalement est utile seulement si son taux de réussite dépasse nettement le taux de base. Sinon, un réviseur obtient d’aussi bons résultats en choisissant des exécutions au hasard.

Dix exécutions, dont trois échouées : un taux de base de 30 %. Deux révisions au hasard trouvent 2 fois 3 sur 10, soit 0,6 exécution échouée en moyenne. Une règle signale 4 exécutions, dont 2 échouées : un taux de réussite des signalements de 50 %. Deux révisions d'exécutions signalées trouvent 2 fois 2 sur 4, soit 1,0 exécution échouée en moyenne.
Le petit exemple de tests/test_compare.py. Avec les mêmes deux révisions, les exécutions signalées révèlent plus de défaillances, car le taux de réussite dépasse le taux de base.
Description textuelle du diagramme

Dix exécutions, dont trois échouées : le taux de base est de 30 %. Deux révisions au hasard trouvent 0,6 exécution échouée en moyenne. Une règle signale quatre exécutions, dont deux échouées : un taux de réussite des signalements de 50 %. Deux révisions d’exécutions signalées trouvent 1,0 exécution échouée en moyenne.

agentruns/compare.py utilise ce calcul. Le réviseur lit d’abord les exécutions signalées, puis en choisit d’autres au hasard. Si le nombre de signalements dépasse le budget, le réviseur choisit au hasard parmi les exécutions signalées. Les résultats sont des moyennes et ne dépendent donc pas d’une graine aléatoire.

Partie 1 : convertir les exécutions en OpenTelemetry

Section intitulée « Partie 1 : convertir les exécutions en OpenTelemetry »

Imaginez que vous copiez un ancien registre papier dans le tableur de votre équipe. Vous placez chaque fait dans la colonne déjà utilisée par tous et omettez ce qui ne doit pas y figurer.

Un convertisseur fait la même chose avec des exécutions enregistrées. Le banc d’essai a écrit chaque exécution comme une liste de messages, et nos outils lisent des traces. Ainsi, agentruns/convert.py crée une trace par exécution avec le SDK OpenTelemetry. Il l’écrit au format OTLP JSON, que obs et le Collector lisent.

Deux colonnes reliées ligne par ligne par des flèches. À gauche, une exécution enregistrée du fichier du banc d'essai : début à 15 h 00 min 00 s avec le message d'accueil fixe de l'agent, sans appel de modèle; message du client à 15 h 00 min 04 s; appel de modèle de l'agent à 15 h 00 min 05 s, 1 000 jetons d'entrée et 20 de sortie, qui demande get_order_details; réponse de l'outil à 15 h 00 min 05,01 s, sans erreur; appel de modèle à 15 h 00 min 07 s, 1 500 jetons d'entrée et 40 de sortie, avec du texte pour le client; STOP du client à 15 h 00 min 08 s. À droite, la trace : span racine invoke_agent retail-agent de 0 à 8,0 s, avec larkfield.run.id R-007-0 et le résultat resolved; en dessous, customer_turn de 0 à 4,0 s; chat gpt-4.1 de 4,0 à 5,0 s, 1000 jetons d'entrée, fin tool_calls; execute_tool get_order_details de 5,0 à 5,01 s, type read, statut ok, commande W1 et empreinte; chat gpt-4.1 de 5,01 à 7,0 s, fin stop; customer_turn de 7,0 à 8,0 s, tau2.customer.end stop. En bas, la note, récompense de 1 ou 0, va dans truth.json, jamais dans un span.
La petite exécution de tests/helpers.py, avec un appel d'outil : une exécution enregistrée devient une trace, un span par message, en ordre chronologique. Chaque span dure aussi longtemps que l'étape enregistrée. La note va dans son propre fichier.
Description textuelle du diagramme

L’exécution devient le span racine, de son début à son dernier message. Chaque message du client devient un span customer_turn avec le temps pris par le client. Chaque appel de modèle devient un span chat avec ses jetons et sa raison de fin, du message précédent à sa réponse. Chaque appel d’outil devient un span execute_tool avec son type, son statut, l’identifiant de commande et une empreinte de ses arguments. La note va dans truth.json.

Les règles de conversion sont celles du cours :

  • Les noms GenAI fixés par le projet de cours : invoke_agent, chat {model}, execute_tool {tool}, gen_ai.usage.input_tokens et les autres.
  • Les noms propres au cours lorsqu’ils ont le même sens, comme larkfield.run.id, larkfield.outcome et larkfield.tool.kind. obs a été construit pour Larkfield et lit ces noms. Il lit donc les exécutions de la boutique sans modification. Les faits propres au banc d’essai reçoivent le préfixe tau2..
  • Aucune valeur qui identifie une personne. Les clients sont fictifs, mais cette habitude compte. Un span conserve les noms des arguments (email, courriel) et une empreinte des valeurs. Il ne conserve jamais de nom, d’adresse courriel ou de code postal. Deux appels identiques ont la même empreinte.
  • Les heures enregistrées. Un span chat commence au message précédent et se termine à la réponse du modèle. Un span customer_turn représente le temps pris par le client pour répondre. C’est notre propre nom de span, pas une opération GenAI.
  1. Ouvrez agentruns/convert.py et trouvez le premier TODO (Part 1) (à faire, partie 1). Une écriture a besoin de son résultat, comme dans les spans d’écriture du cours :

    if k == WRITE:
    attrs[n.WRITE_OUTCOME] = "refused" if res.get("error") else "done"
  2. Trouvez le deuxième TODO (Part 1). Un appel échoué a besoin d’un statut d’erreur, avec le court message de l’outil :

    if res.get("error"):
    span.set_attribute(n.ERROR_TYPE, "tool_error")
    span.set_status(Status(StatusCode.ERROR, res.get("error_text", "")))
  3. Exécutez les tests : python -m pytest -q. Deux tests échouent encore : les règles des parties 2 et 3.

  4. Convertissez les exécutions de conception :

    Fenêtre de terminal
    python -m agentruns.convert design
    design (gpt-4.1-2025-04-14): 456 runs -> 12,142 spans in telemetry/design/traces.jsonl.gz
    the benchmark's grade -> telemetry/design/truth.json (118 of 456 runs failed; obs never reads it)

agentruns/data.py vérifie le SHA-256 de chaque fichier avant de le lire. La conversion produit le même fichier chaque fois : les identifiants de spans proviennent d’une graine.

Dans votre deuxième terminal, dans observable-workflow, listez les dernières exécutions :

Fenêtre de terminal
python -m obs runs --data ../public-agent-runs/telemetry/design --limit 5
run ticket started outcome model tools appr cost US$ secs model flags
R-109-3 task-109 Thu 11:38 resolved 12 6 0 0.06657 59.3 gpt-4.1-2025-04-14 duplicate_write
R-110-3 task-110 Thu 11:38 resolved 12 5 0 0.06665 64.1 gpt-4.1-2025-04-14 duplicate_write
R-111-3 task-111 Thu 11:38 handed_to_person 14 8 0 0.08078 66.0 gpt-4.1-2025-04-14 loop
R-112-3 task-112 Thu 11:38 resolved 16 4 0 0.07336 72.6 gpt-4.1-2025-04-14 -
R-113-3 task-113 Thu 11:38 resolved 8 6 0 0.03033 41.5 gpt-4.1-2025-04-14 duplicate_write,loop
456 run(s), 324 flagged (last 5 shown)

Ce que cela nous apprend. L’outil du cours lit l’agent d’une autre équipe sans modification : exécutions, résultats, appels de modèle, outils, coûts et temps. Les coûts sont ceux enregistrés par le banc d’essai, pas ceux de la table de prix du cours. Les heures de début viennent du banc d’essai, sont lues comme UTC et affichées dans le fuseau horaire de Larkfield. Et la dernière colonne est un avertissement : 324 exécutions sur 456 sont signalées.

Les 456 exécutions se sont terminées normalement : le client simulé a arrêté la conversation. 428 se sont terminées avec resolved (résolu) et 28 avec handed_to_person (transféré à une personne). Aucune exécution n’a tourné en boucle jusqu’à ce que le banc d’essai l’arrête. Les défaillances évidentes de la semaine du cours ne sont donc pas présentes ici. Si cet agent échoue, il échoue calmement.

Fenêtre de terminal
python -m obs trace R-002-0 --data ../public-agent-runs/telemetry/design
Trace 1 9cc6b0ee25dca4b7c7d22fc4a3cb15d5 Thu 05 Jun 11:33:58 36.2 s
0.0 s |========================| 36.20 s invoke_agent retail-agent finished
0.1 s |===== | 7.72 s customer_turn
7.8 s | == | 2.14 s chat gpt-4.1-2025-04-14 3531 in / 62 out US$0.00276 stop
…
13.2 s | === | 2.94 s chat gpt-4.1-2025-04-14 3895 in / 129 out US$0.00364 tool_calls
16.1 s | = | 0.00 s execute_tool list_all_product_types ok
16.1 s | = | 0.00 s execute_tool get_order_details ok #W6247578
16.1 s | = | 0.00 s execute_tool get_order_details ok #W9711842
16.1 s | = | 0.00 s execute_tool get_order_details ok #W4776164
16.1 s | = | 0.00 s execute_tool get_order_details ok #W6679257
16.1 s | = | 0.00 s execute_tool get_order_details ok #W2378156
…
27.9 s | == | 1.79 s chat gpt-4.1-2025-04-14 7225 in / 52 out US$0.00968 tool_calls
29.7 s | = | 0.00 s execute_tool return_delivered_order_items done #W2378156
29.7 s | === | 3.67 s chat gpt-4.1-2025-04-14 7820 in / 84 out US$0.01113 stop
33.4 s | ==| 2.82 s customer_turn
Outcome: resolved
Flag loop: the model asked for get_order_details(order_id) 5 times in one run

Ce que cela nous apprend. Vous la lisez comme dans Lire une exécution. Le client a pris 7,7 secondes pour écrire son premier message. Un appel de modèle a demandé six outils à la fois, dont cinq commandes du client. Ensuite, un retour a été accepté. Le banc d’essai a jugé cette exécution réussie. Mais la règle de boucle du cours la signale : cinq appels de get_order_details avec l’argument order_id.

La recherche du cours pour une lecture échouée dans une exécution résolue trouve 46 exécutions :

Fenêtre de terminal
python -m obs find --error-then-resolved --data ../public-agent-runs/telemetry/design
R-036-0 task-36 Thu 11:34 gpt-4.1-2025-04-14 a tool error, then resolved
R-035-0 task-35 Thu 11:34 gpt-4.1-2025-04-14 a tool error, then resolved
…
46 match(es) in 456 run(s)

Les appels échoués sont fréquents. Lesquels comptent?

Une référence de base : les cinq règles du cours, sans changement

Section intitulée « Une référence de base : les cinq règles du cours, sans changement »

Exécutez-les toutes, puis comparez leurs signalements à la note :

Fenêtre de terminal
python -m obs find all --data ../public-agent-runs/telemetry/design
R-002-0 task-2 Thu 11:33 gpt-4.1-2025-04-14 loop: the model asked for get_order_details(order_id) 5 times in one run
…
R-004-0 task-4 Thu 11:33 gpt-4.1-2025-04-14 duplicate_write: two writes with the same idempotency key None
…
477 match(es) in 456 run(s)

Dans public-agent-runs :

Fenêtre de terminal
python -m agentruns.check --data design --rules course
456 runs, 118 failed by the benchmark's grade: base rate 26%. The course's rules:
rule flagged failed hit rate
loop 268 74 28%
duplicate_write 163 45 28%
no_action 31 6 19%
hidden_tool_error 15 7 47%
any rule 324 88 27%
Failed runs that a rule flagged: 88 of 118. Why they failed (truth.json):
…

Ce que cela nous apprend. Les règles signalent 324 exécutions. Leur taux de réussite, 27 %, correspond au taux de base, 26 %. Signaler 71 % des exécutions ne nous apprend rien. Chaque règle repose sur une hypothèse concernant le flux de travail de Larkfield. Cet agent ne la respecte pas :

Règle Hypothèse de Larkfield Ce que fait cet agent
loop une commande par billet : le même outil avec les mêmes noms d’arguments trois fois constitue une boucle un client a plusieurs commandes, donc cinq appels à get_order_details(order_id) sont normaux
duplicate_write chaque écriture a une clé d’idempotence aucune écriture n’a de clé, donc « la même clé » signifie « aucune clé » pour chaque paire d’écritures
no_action une réponse est un appel à l’outil send_reply la réponse est le texte produit par le modèle
hidden_tool_error sans appel ultérieur au même outil, il manque des faits la vérification d’identité prévue par la politique : un courriel échoue, puis un nom et un code postal fonctionnent
followed_injection les données d’exercice marquent les textes injectés aucun texte n’a de marqueur

Les règles ne sont pas fausses. Ce sont celles de Larkfield. De même, Contenir un agent emballé montrait que les limites d’un agent ne conviennent pas à un autre.

agentruns/rules.py contient les règles du magasin. Chacune lit les mêmes objets Run que obs. Elle renvoie une phrase avec les noms des spans et les heures, comme dans Les modèles de défaillance des agents :

  • loop compte les appels au même outil avec les mêmes arguments : l’empreinte, pas les noms.
  • duplicate_write compare l’outil et l’empreinte, car il n’y a pas de clé.
  • hidden_tool_error traite les deux recherches d’identité comme un seul objectif.
  • no_action et followed_injection sont retirées. Ici, une exécution sans changement est souvent correcte, car le client a seulement posé une question. Et aucun texte n’a de marqueur.
  1. Ouvrez agentruns/rules.py et trouvez TODO (Part 2) (à faire, partie 2). Le code de départ compte un outil avec ses noms d’arguments, comme la règle du cours. Comptez plutôt l’empreinte des valeurs :

    return s.tool, s.get(n.ARGS_DIGEST)
  2. Exécutez les tests : un échoue encore, celui de la règle de la partie 3.

Partie 3 : une règle tirée de la politique du magasin

Section intitulée « Partie 3 : une règle tirée de la politique du magasin »

La politique du magasin contient des règles qu’une trace peut vérifier sans lire le texte. Par exemple : « Les outils d’échange ou de modification de commande ne peuvent être appelés qu’une fois par commande. » Nous en avons essayé plusieurs sur les exécutions de conception. La plupart ne signalaient aucune exécution, ou signalaient des exécutions dont le taux d’échec ne dépassait pas le taux de base. Un signal se démarquait : la base de données du magasin refusait un changement, par exemple « Une commande non livrée ne peut pas être échangée. » L’exécution continuait, et aucun changement ultérieur du même type sur cette commande n’était accepté.

  1. Trouvez TODO (Part 3) (à faire, partie 3), dans refused_change. Pour chaque écriture refusée, cherchez une écriture ultérieure acceptée du même outil sur la même commande :

    writes = _writes(run)
    for i, s in enumerate(writes):
    if s.get(n.WRITE_OUTCOME) != "refused":
    continue
    later = [x for x in writes[i + 1:] if x.tool == s.tool and x.get(n.ORDER_ID) == s.get(n.ORDER_ID)
    and x.get(n.WRITE_OUTCOME) == "done"]
    if not later:
    return (f"the store refused {s.tool} {s.get(n.ORDER_ID, '')} at {at(run, s)} "
    f"({s.status_message[:90]}), and no later {s.tool} on it was accepted").replace(" ", " ")
    return None
  2. Exécutez les tests : la dernière ligne indique 19 passed (19 tests réussis).

  3. Trouvez les exécutions :

    Fenêtre de terminal
    python -m agentruns.find refused_change --data design
    R-027-0 task-27 Thu 11:34 refused_change: the store refused exchange_delivered_order_items #W7181492 at +39.1 s (Error: Non-delivered order cannot be exchanged), and no later exchange_delivered_order_items on it was accepted
    R-030-0 task-30 Thu 11:34 refused_change: the store refused exchange_delivered_order_items #W2692684 at +22.7 s (Error: New item 3788616824 not found or available), and no later exchange_delivered_order_items on it was accepted
    …
    39 match(es) in 456 run(s), 39 run(s) flagged

Vérifiez un signalement à partir des preuves. Dans observable-workflow, ouvrez la première exécution :

Fenêtre de terminal
python -m obs trace R-027-0 --data ../public-agent-runs/telemetry/design
…
35.3 s | === | 3.85 s chat gpt-4.1-2025-04-14 6230 in / 113 out US$0.00818 tool_calls
39.1 s | = | 0.00 s execute_tool return_delivered_order_items done #W7181492
39.1 s | = | 0.00 s execute_tool exchange_delivered_order_items ERROR refused #W7181492
39.1 s | === | 5.07 s chat gpt-4.1-2025-04-14 6903 in / 138 out US$0.00973 stop
…
Outcome: handed_to_person

Un appel de modèle demandait deux changements simultanés sur une commande. Le magasin a accepté le retour et refusé l’échange. Le retour a changé l’état de la commande, rendant l’échange impossible. Maintenant seulement, regardez la note dans public-agent-runs :

Fenêtre de terminal
python -m agentruns.check --data design --run R-027-0
R-027-0 (task 27, trial 0): the benchmark's grade 0, failed: different_changes
changes made 1, expected 1; database as expected: no; customer told what they had to hear: yes
the course's rules: no flag
the store's rules: refused_change: the store refused exchange_delivered_order_items #W7181492 at +39.1 s (Error: Non-delivered order cannot be exchanged), and no later exchange_delivered_order_items on it was accepted

Un signalement justifié. Ils ne le sont pas tous. R-095-3 avait le même refus et a réussi : l’agent avait déjà échangé cette commande une fois. Sa deuxième tentative n’a rien changé. Un signalement invite à examiner, pas à rendre un verdict.

Partie 4 : une comparaison équitable avec une seule mesure

Section intitulée « Partie 4 : une comparaison équitable avec une seule mesure »

D’abord, comparez les règles du magasin à la note :

Fenêtre de terminal
python -m agentruns.check --data design --rules store
456 runs, 118 failed by the benchmark's grade: base rate 26%. The store's rules:
rule flagged failed hit rate
refused_change 39 18 46%
hidden_tool_error 35 15 43%
duplicate_write 3 1 33%
loop 2 1 50%
any rule 45 21 47%
Failed runs that a rule flagged: 21 of 118. Why they failed (truth.json):
why failed flagged
wrong_arguments 50 9
different_changes 18 9
unasked_change 11 0
missing_change 13 1
no_change 13 2
right_changes_not_told 13 0

Puis la mesure, avec les mêmes 92 révisions pour chaque méthode :

Fenêtre de terminal
python -m agentruns.compare --data design
design: review 92 of 456 runs (one in five); 118 failed by the grade. Failed runs found, on average:
how the reviewer chooses found hit rate
at random 23.8 26%
the course's rules first 25.0 27% (324 flagged: 92 of them at random)
the store's rules first 32.1 35% (45 flagged, then 47 at random)
456 exécutions enregistrées de gpt-4.1 dans le domaine du commerce de détail de τ²-bench; 118 ont échoué selon la note du banc d'essai. Valeurs attendues : la moyenne de tous les choix aléatoires possibles.
Description textuelle du graphique

Trois barres. Au hasard : 23.8 exécutions en échec trouvées dans 92 révisions. Les règles du cours en premier : 25.0. Les règles du magasin en premier : 32.1, avec 45 exécutions signalées, dont 21 en échec.

Ce que cela nous apprend.

  • Les règles du cours ne font pas mieux qu’un échantillon aléatoire : 25,0 contre 23,8. Elles signalent trop d’exécutions.
  • Les règles du magasin signalent 45 exécutions, dont 21 ont échoué. Leur taux de réussite est de 47 %, presque le double du taux de base. En les examinant d’abord, les mêmes 92 révisions trouvent 32,1 exécutions en échec plutôt que 23,8, environ un tiers de plus.
  • Mais elles signalent seulement 21 des 118 exécutions en échec. Quatre exécutions en échec sur cinq ne laissent aucune marque visible par une règle sur la trace.

Lisez maintenant truth.json pour les 97 exécutions en échec qu’aucune règle n’a signalées :

Les exécutions de conception (gpt-4.1), les règles du magasin. args : le bon outil avec d'autres arguments; other : un autre changement; unasked : un changement non demandé par la tâche; missing : un changement attendu manque; none : aucun changement; untold : le client n'a pas reçu l'information nécessaire (agentruns/truth.py).
Description textuelle du graphique

Six barres d’exécutions en échec qu’aucune règle n’a signalées. Mauvais arguments : 41. Autre changement : 9. Changement non demandé : 11. Changement manquant : 12. Aucun changement : 11. Information non transmise : 13.

Le plus grand groupe est le bon outil avec les mauvais arguments : 50 exécutions en échec, dont 41 non signalées. Dans 19 de ces 50 exécutions, seul le nouvel article diffère. L’agent a choisi une autre variante du bon produit, comme une autre couleur ou taille. Il avait recherché le produit, et l’article choisi existait vraiment. Seuls les mots du client indiquent lequel il voulait.

Voici un échec qui semble parfait dans la trace :

Fenêtre de terminal
python -m obs trace R-051-0 --data ../public-agent-runs/telemetry/design
…
9.3 s | = | 0.75 s chat gpt-4.1-2025-04-14 3932 in / 20 out US$0.00265 tool_calls
10.0 s | = | 0.00 s execute_tool get_order_details ok #W8855135
…
16.7 s | = | 0.83 s chat gpt-4.1-2025-04-14 4659 in / 26 out US$0.00377 tool_calls
17.5 s | = | 0.00 s execute_tool cancel_pending_order done #W8855135
17.5 s | === | 2.45 s chat gpt-4.1-2025-04-14 5135 in / 82 out US$0.00401 stop
20.0 s | ===| 1.88 s customer_turn
Outcome: resolved

La vérification d’identité, une recherche, une annulation, un client satisfait. La note indique un échec : different_changes (changements différents). Le changement attendu par la tâche est un retour sur une autre commande, #W4689314, qui avait été livrée (data/runs/retail-tasks.jsonl.gz). Dans la conversation originale, le client demandait de retourner un appareil photo. L’agent a plutôt trouvé une commande en attente, et le client a accepté de l’annuler. La trace enregistre correctement chaque étape. Elle ne peut pas savoir que l’étape était la mauvaise.

Priya l’écrit pour Amira, avant la création de l’agent du magasin :

Quatre lignes : un type d'échec, puis l'enregistrement qui le détecte. Un appel en échec, un changement refusé par le magasin, une boucle : 21 des 118 exécutions en échec; les règles du magasin sur les traces : révisez ces exécutions d'abord. Un changement différent de la demande du client, de mauvais arguments, un autre changement ou un changement non demandé : 79 sur 118; enregistrez ce que le client a confirmé sous forme d'identifiants dans un événement de proposition, puis comparez chaque écriture à cet événement. Le client n'a pas reçu l'information nécessaire : 13; une personne lit le texte lors de révisions échantillonnées, avec du contenu capturé seulement pour celles-ci. Combien d'exécutions échouent? Gardez une part aléatoire des révisions, car réviser d'abord les exécutions signalées surestime les échecs.
Chaque type d'échec nécessite son propre enregistrement. La structure de la trace détecte seulement le premier type.
Description textuelle du diagramme

Appels en échec, changements refusés et boucles : les règles du magasin, et révisez ces exécutions d’abord. Un changement différent de la demande : enregistrez la demande confirmée sous forme d’identifiants et comparez chaque écriture à celle-ci. Un client non informé : une personne lit le texte. Le taux d’échec : une part aléatoire des révisions.

  1. Écrivez les règles propres à l’agent avant le lancement, et mesurez leur taux de réussite. Copiez la méthode, pas les règles. Sans changement, les règles du cours restaient au taux de base; adaptées, elles atteignaient 47 %.
  2. Révisez d’abord les exécutions signalées. Avec les mêmes 92 révisions, l’équipe trouve environ un tiers de plus d’échecs.
  3. Gardez une part aléatoire des révisions. Réviser d’abord les exécutions signalées trouve plus d’échecs et surestime donc le taux d’échec. Un échantillon aléatoire l’estime sans biais.
  4. Enregistrez ce que le client a confirmé, sous forme d’identifiants. Dans 79 des 118 échecs, un changement diffère de la demande de la tâche. Une règle peut le voir seulement si l’exécution enregistre la demande suivie : la commande, les articles et le mode de paiement. Le flux de soutien de Larkfield enregistre sa proposition et l’approbation d’une personne. Consultez Approbations, personnes et temps d’attente et Enregistrer les décisions, les approbations et les changements.
  5. Laissez des personnes lire le texte de quelques exécutions. Le texte permet de savoir si le client a reçu la bonne information. Capturez le contenu seulement pour les révisions échantillonnées, comme dans Ce qu’il faut enregistrer, et ce qu’il ne faut pas.

Partie 5 : de nouvelles données d’entrée, de bout en bout

Section intitulée « Partie 5 : de nouvelles données d’entrée, de bout en bout »

Des règles adaptées aux exécutions d’un modèle peuvent convenir seulement à ce modèle. Appliquez toute la méthode aux 456 exécutions de Claude 3.7 Sonnet sur les mêmes tâches.

  1. Convertissez-les :

    Fenêtre de terminal
    python -m agentruns.convert claude-3.7-sonnet
    claude-3.7-sonnet (claude-3-7-sonnet-20250219): 456 runs -> 13,486 spans in telemetry/claude-3.7-sonnet/traces.jsonl.gz
    the benchmark's grade -> telemetry/claude-3.7-sonnet/truth.json (97 of 456 runs failed; obs never reads it)
  2. Lisez-les avec obs, dans observable-workflow :

    Fenêtre de terminal
    python -m obs runs --data ../public-agent-runs/telemetry/claude-3.7-sonnet --limit 3
    run ticket started outcome model tools appr cost US$ secs model flags
    R-111-3 task-111 Thu 12:00 resolved 18 9 0 0.52124 80.4 claude-3-7-sonnet-20250219 duplicate_write,loop
    R-112-3 task-112 Thu 12:00 resolved 23 10 0 0.67582 102.9 claude-3-7-sonnet-20250219 duplicate_write,loop
    R-113-3 task-113 Thu 12:00 resolved 14 6 0 0.30788 48.5 claude-3-7-sonnet-20250219 duplicate_write,loop
    456 run(s), 315 flagged (last 3 shown)
  3. Vérifiez les règles du magasin, sans changement :

    Fenêtre de terminal
    python -m agentruns.check --data claude-3.7-sonnet --rules store
    456 runs, 97 failed by the benchmark's grade: base rate 21%. The store's rules:
    rule flagged failed hit rate
    refused_change 32 20 62%
    hidden_tool_error 21 13 62%
    loop 5 5 100%
    any rule 34 22 65%
    Failed runs that a rule flagged: 22 of 97. Why they failed (truth.json):
    …
  4. Comparez les méthodes sur les quatre modèles :

    Fenêtre de terminal
    python -m agentruns.convert o4-mini
    python -m agentruns.convert gpt-4.1-mini
    python -m agentruns.compare --data design claude-3.7-sonnet o4-mini gpt-4.1-mini --json results/compare.json
    …
    claude-3.7-sonnet: review 92 of 456 runs (one in five); 97 failed by the grade. Failed runs found, on average:
    how the reviewer chooses found hit rate
    at random 19.6 21%
    the course's rules first 21.0 23% (315 flagged: 92 of them at random)
    the store's rules first 32.3 35% (34 flagged, then 58 at random)
    o4-mini: review 92 of 456 runs (one in five); 130 failed by the grade. Failed runs found, on average:
    how the reviewer chooses found hit rate
    at random 26.2 29%
    the course's rules first 24.8 27% (274 flagged: 92 of them at random)
    the store's rules first 27.5 30% (19 flagged, then 73 at random)
    gpt-4.1-mini: review 92 of 456 runs (one in five); 155 failed by the grade. Failed runs found, on average:
    how the reviewer chooses found hit rate
    at random 31.3 34%
    the course's rules first 34.1 37% (356 flagged: 92 of them at random)
    the store's rules first 41.0 45% (101 flagged: 92 of them at random)

Ce que cela nous apprend.

  • Sur Claude 3.7 Sonnet, les règles du magasin sont restées efficaces. Leur taux de réussite était de 65 %, contre un taux de base de 21 %. Les mêmes révisions ont trouvé 32,3 exécutions en échec plutôt que 19,6. Ses cinq boucles étaient toutes de véritables échecs.
  • Sur gpt-4.1-mini, elles sont aussi restées efficaces : 41,0 plutôt que 31,3.
  • Sur o4-mini, elles ont presque cessé de fonctionner : 27,5 plutôt que 26,2. La plupart de ses échecs étaient de mauvais arguments (73 sur 130). Le magasin a refusé des changements dans seulement 15 de ses exécutions. Une règle détecte seulement les échecs qui laissent sa signature.
  • Sur chaque modèle, les règles du cours, sans changement, sont restées au taux de base.

La recommandation tient donc toujours, avec un ajout : mesurez à nouveau le taux de réussite pour chaque nouveau modèle avant sa mise en production.

Si vous avez Docker et 20 Go d’espace disque libre, cherchez les exécutions avec TraceQL, comme dans Chercher des exécutions avec TraceQL. Le fichier grafana.md du projet contient les étapes et cinq requêtes. Démarrez Grafana dans observable-workflow (docker compose -f grafana/compose.yaml up -d), puis envoyez les exécutions avec python -m agentruns.convert design --otlp. Le convertisseur décale les heures pour que la dernière exécution se termine maintenant. Arrêtez Grafana avec docker compose -f grafana/compose.yaml down -v. L’équipe du cours a exécuté ces étapes une fois. Grafana était prêt après 14 secondes, et --otlp a envoyé les 12 142 spans en environ une seconde. Tempo conservait ensuite 362 des 456 exécutions. L’échantillonnage en fin de trace du Collector garde les traces avec une écriture, une erreur ou une durée supérieure à 30 secondes. Il élimine les autres. Les cinq requêtes de grafana.md ont renvoyé 362 exécutions, 44 avec un changement refusé, 68 avec un appel en échec ensuite résolu, 11 confiées à une personne et 345 avec un appel de modèle dépassant 5 secondes. Ce sont des candidates, pas des échecs. Les règles dans agentruns/rules.py en gardent moins, car elles vérifient aussi la suite de l’exécution.

TraceQL trouve les candidates, par exemple chaque changement refusé : { resource.service.name = "tau2-retail-agent" && span.larkfield.write.outcome = "refused" }. Il ne peut pas demander « un changement ultérieur du même type a-t-il été accepté? ». Les règles dans agentruns/rules.py le font.

Erreur courante

Le projet du cours est introuvable

Symptôme :

The course project is not in /Users/you/projects/observable-workflow. Put this folder next to observable-workflow, or set OBS_PROJECT to the course project's folder.

Cause : public-agent-runs n’est pas à côté de observable-workflow, donc l’étude de cas ne peut pas importer obs.

Solution : déplacez le dossier, ou définissez OBS_PROJECT sur le dossier de votre projet du cours et relancez la commande.

  • Une règle porte les hypothèses de son flux de travail. Sur un autre agent, les règles du cours ont signalé 71 % des exécutions. Listez l’hypothèse de chaque règle avant de vous fier à son compte.
  • Le taux de réussite détermine l’utilité d’un signalement. Comparez-le chaque fois au taux de base. Signaler 88 échecs sur 118 semble bon, jusqu’à voir que 324 exécutions ont été signalées.
  • La structure détecte seulement les échecs qui laissent une structure. Les changements refusés, les appels en échec et les boucles sont visibles. Un mauvais choix parmi des options valides ne l’est pas, et représente la plupart des échecs de cet agent.
  • Un banc d’essai, pas un service de soutien. Un modèle joue les clients, et les tâches constituent des données de test, chacune exécutée 4 fois. Une tâche peut échouer de la même façon aux quatre essais. Les comptes ne représentent donc pas 456 cas indépendants.
  • La note correspond à une réponse par tâche. Quelques tâches peuvent accepter plusieurs bons résultats, mais le banc d’essai n’en compte qu’un.
  • Décrivez les données honnêtement. Ce sont les exécutions du banc d’essai d’une autre équipe. Présentez les taux de réussite comme un exercice de la méthode, pas comme une mesure de l’agent de Larkfield.
  • Gardez les valeurs personnelles hors des spans, même si elles sont inventées. Le convertisseur conserve les noms d’arguments et les empreintes. N’ajoutez pas les valeurs pour faciliter la recherche.
  • Un signalement n’est pas un jugement sur une personne ou un modèle. Il choisit les exécutions qu’une personne lit d’abord. La personne décide.
  • Mentionnez la source. Les données sont sous licence MIT. Gardez le texte de la licence et l’attribution dans votre copie, comme dans la fiche du jeu de données.

Ce projet montre ce que recherchent les équipes d’exploitation. Il comprend un convertisseur vers une norme, une référence de base, des règles vérifiées contre une note, une mesure équitable et un test sur de nouvelles données d’entrée.

Quoi mettre dans le dépôt :

public-agent-runs/
README.md the question, how to run it, the results table and the recommendation
data/dataset.md the source, the licence, the checksums, the changes, the limits
data/runs/ the fixed sample and the τ²-bench licence text
LICENSE MIT, for your code
agentruns/ names, store, convert, truth, rules, find, check, compare
tests/ 19 tests
results/ your compare.json
  1. Créez un dépôt Git à partir du dossier de votre projet, puis poussez-le vers GitHub. .gitignore exclut telemetry/ et results/ : ajoutez results/compare.json avec git add -f.
  2. Rédigez le tableau des résultats du README à partir de votre sortie de python -m agentruns.compare, avec la référence de base et les nouvelles données d’entrée.
  3. Indiquez dans le README que le projet nécessite le projet du cours (OBS_PROJECT). Précisez que python -m pytest réussit lorsque celui-ci est présent.

En deux phrases, pour une entrevue :

« J’ai converti 456 exécutions ouvertes et notées d’un agent d’IA de service à la clientèle en traces OpenTelemetry. J’ai vérifié des règles de défaillance contre la note. Les règles adaptées à l’agent ont presque doublé le taux de réussite et trouvé un tiers de plus d’échecs par révision. La note a montré quels échecs nécessitent plutôt un enregistrement de la demande du client. »

Aller plus loin : convertissez les exécutions du domaine aérien du même banc d’essai avec python -I tools/make_sample.py, dans un nouveau dossier vide, et adaptez la table des outils du magasin. Ou écrivez une règle pour « modifier ou échanger deux fois sur une commande », puis mesurez son taux de réussite. Ou attribuez un coût à une révision et à un échec manqué, puis choisissez le budget qui minimise le coût total.

Vérifiez votre compréhension

Les cinq règles du cours ont signalé 88 des 118 exécutions en échec. Pourquoi Priya dit-elle qu'elles n'ont rien trouvé d'utile?

Afficher la réponse

Parce qu’elles ont signalé 324 des 456 exécutions, dont seulement 27 % étaient en échec. Le taux de base est de 26 %. Un réviseur qui commence par les exécutions signalées trouve 25,0 échecs en 92 révisions, presque autant qu’au hasard (23,8). Les règles reposent sur les hypothèses de Larkfield : une commande par billet, une clé d’idempotence pour chaque écriture, un outil send_reply. Cet agent ne respecte aucune des trois.

Vérifiez votre compréhension

R-051-0 a annulé une commande en attente, le client a accepté et l'exécution s'est terminée avec le problème résolu. L'évaluation indique un échec. Pourquoi aucune règle appliquée à sa trace ne peut-elle le détecter? Quel enregistrement permettrait à une règle de le détecter?

Afficher la réponse

Chaque étape de la trace est correcte : la vérification d’identité, la recherche, une annulation acceptée, un client satisfait. L’échec vient du choix : le client voulait retourner un appareil photo d’une autre commande, déjà livrée. Cela se trouve dans les mots, pas dans la structure. Une demande enregistrée sous forme d’identifiants (commande, articles, changement) permettrait à une règle de comparer chaque écriture à cette demande. Les événements de proposition et d’approbation de Larkfield constituent un tel enregistrement.

Vérifiez votre compréhension

Les règles du magasin ont augmenté le nombre d'échecs trouvés en 92 révisions : de 23,8 à 32,1 pour gpt-4.1. Pour Claude 3.7 Sonnet, ce nombre est passé de 19,6 à 32,3. Pour o4-mini, elles en ont trouvé 27,5 plutôt que 26,2. Que devrait faire Larkfield de ce résultat?

Afficher la réponse

Mesurer de nouveau le taux de détection de ses règles à chaque changement de modèle, comme vérification avant la mise en production. Une règle trouve seulement les échecs qui laissent la signature qu’elle cherche. Les échecs d’o4-mini venaient surtout d’arguments incorrects, et le magasin refusait peu de ses changements. Les règles avaient donc peu à détecter. Garder une part aléatoire des révisions pour obtenir un taux d’échec fidèle à la réalité. Enregistrer aussi la demande confirmée pour rendre les arguments incorrects visibles.

Récapitulatif

  • Un convertisseur transforme les exécutions enregistrées par un autre système en traces. Chaque exécution devient une trace, avec les noms du cours et les heures enregistrées. Aucune valeur personnelle ne figure dans un span (une unité de travail d’une trace). L’évaluation a son propre fichier.
  • Sans modification, les règles du cours ont signalé 71 % des exécutions d’un autre agent, avec le taux d’échec de base. Une fois adaptées, elles ont atteint un taux de détection de 47 %. Elles ont trouvé environ un tiers plus d’échecs dans les mêmes 92 révisions.
  • Quatre exécutions en échec sur cinq n’ont laissé aucune marque structurelle : surtout le bon outil avec les mauvais arguments. Un enregistrement de la demande confirmée, sous forme d’identifiants, et quelques révisions humaines permettent de les trouver.
  • Les règles adaptées ont gardé leur efficacité sur deux des trois autres modèles. Mesurez de nouveau le taux de détection à chaque changement de modèle.

Vous pouvez maintenant lire, avec vos propres outils, les exécutions enregistrées par un autre système. Vous pouvez aussi préciser, preuves à l’appui, quels échecs leurs traces permettent de voir. Ensuite, vous mesurez le coût d’un agent de programmation. Il comporte beaucoup plus d’étapes, et son coût dépend du chemin que l’agent prend.

Leçon suivante : Le coût d'un agent de programmation