Observer un run d'agent, sans tableau maison

Observer un agent, sur les pages lues le 2026-10-18, c’est d’abord un enregistrement du run : quels appels de modèle, quels outils, quels handoffs. Ce n’est pas un tableau branché ici. Aucun run n’a été lancé, aucune trace n’a été ouverte dans un dashboard.

La facture est un autre relevé. Un guide d’un lot ultérieur tiendra les postes de coût, sans montant. La carte des guides est sur Agents IA : où lire.

Architecture observée

Le runner crée des traces et des spans. Un processeur les met en tampon, puis un exporteur les envoie au backend configuré. Le dashboard lit cet export ; il n’exécute pas l’agent et ne garantit pas qu’une réponse est correcte. Les évaluations, les métriques métier et les journaux applicatifs restent des couches séparées.

Cette architecture a une conséquence simple : une trace peut copier les prompts, les sorties du modèle et les arguments d’outils. L’observabilité n’est pas une zone neutre. Il faut choisir les champs avant le premier run, limiter les accès au backend et fixer une durée de conservation adaptée. Ce brouillon n’a vérifié aucun de ces réglages sur un compte réel.

Ce que l’Agents SDK enregistre

La page Tracing de l’Agents SDK Python dit que le tracing est inclus, et actif par défaut. Il collecte les générations du modèle, les appels d’outils, les handoffs, les garde-fous, et des événements que vous ajoutez. Le dashboard cité est Traces. Je ne l’ai pas ouvert.

Une trace est une opération de bout en bout, un workflow. Elle a un nom, un identifiant, un group_id optionnel pour relier plusieurs traces d’une même conversation, et des métadonnées. Un span a un début et une fin, un parent éventuel, et un span_data selon l’opération : agent, génération, outil, garde-fou, handoff. Le temps d’une étape se lit sur started_at et ended_at. Ce n’est pas une latence que j’ai mesurée.

Par défaut, le SDK enveloppe le run, chaque invocation, chaque tour de modèle, chaque passage d’agent, chaque génération, chaque outil de fonction, chaque garde-fou, chaque handoff, et les entrées ou sorties audio. Le nom de trace par défaut est la chaîne Agent workflow. On peut le changer avec trace() ou RunConfig. On peut retirer les spans automatiques de tâche et de tour. Les spans d’agent, de génération, d’outil, de garde-fou et de handoff restent.

Trois façons de couper le tracing sont écrites : la variable OPENAI_AGENTS_DISABLE_TRACING=1, set_tracing_disabled(True), ou tracing_disabled sur un seul run. Couper le tracing n’efface pas ce que les processeurs ont déjà en mémoire. flush_traces() vide encore ce tampon.

Le tracing n’est pas disponible pour une organisation en Zero Data Retention sur les API OpenAI. La page le marque à part. Je n’ai pas ouvert de compte soumis à cette politique.

Ce que la trace contient, et ce qu’elle envoie

generation_span() garde les entrées et sorties du modèle. function_span() garde celles de l’outil. La page dit que cela peut être sensible. RunConfig.trace_include_sensitive_data coupe cette capture. Le défaut écrit est True. On peut poser le défaut avec OPENAI_AGENTS_TRACE_INCLUDE_SENSITIVE_DATA avant de lancer l’application. Quand la capture est coupée, les spans du modèle Responses omettent l’entrée et la sortie. Sur un endpoint OpenAI officiel, le span garde encore response_id. Sur un endpoint maison, cet identifiant est omis.

L’export par défaut passe par un BatchTraceProcessor, vers le backend OpenAI, par lots. Dans un worker long, Celery, RQ, Dramatiq ou une tâche de fond FastAPI, la page dit que l’export part souvent seul, mais pas forcément dès la fin du job. flush_traces() bloque jusqu’à l’envoi du tampon. On l’appelle après la fermeture du trace(), sinon on vide une trace encore ouverte. Je n’ai pas branché de worker.

Pour mettre plusieurs Runner.run dans une seule trace, la page montre un with trace("Joke workflow"). L’exemple n’a pas été exécuté. Integrations and observability dit la même chose côté guide : le tracing sert à comprendre un run, puis, plus tard, à nourrir une évaluation. L’évaluation n’est pas faite ici.

Un processeur ajouté avec add_trace_processor() ne retire pas l’export OpenAI. set_trace_processors() le remplace. La page prévient qu’un processeur de rédaction qui échoue n’empêche pas les autres de recevoir les données. Si la confidentialité dépend de cette rédaction, OpenAI recommande de réunir rédaction et envoi dans un exporteur contrôlé par l’application, puis de remplacer les processeurs par défaut avant de créer la première trace. Un échec doit abandonner le lot, sans journaliser la charge utile. Je n’ai enregistré aucun processeur.

La même page liste des intégrations tierces, dont LangSmith, et dit que leur présence n’est pas une certification. Je n’en ai installé aucune.

LangGraph et Claude Code ne tracent pas le même objet

LangGraph renvoie vers LangSmith pour tracer les requêtes, déboguer, et évaluer. La page dit de poser LANGSMITH_TRACING=true et une clé, puis de suivre le quickstart de tracing. Je n’ai pas posé la variable, et je n’ai pas ouvert ce quickstart. La promesse de visibilité, sur la page d’overview, n’est pas un relevé.

Claude Code, sur How Claude Code works, écrit autre chose. Chaque message, appel d’outil et résultat va dans un JSONL sous ~/.claude/projects/. Ce journal sert à reprendre, forker, revenir en arrière. Ce n’est pas l’arbre de spans de l’Agents SDK. /context montre ce qui occupe la fenêtre. Ce n’est ni une facture, ni une latence d’outil. Je n’ai pas ouvert ce dossier.

Les logs d’une application, requêtes HTTP, erreurs et files sont encore un troisième objet. Un guide d’un lot ultérieur les traitera. Une trace d’agent ne les remplace pas, et l’inverse est vrai.

Ce qu’une trace ne prouve pas

Une trace montre le chemin d’un run : modèle, outil, handoff, garde-fou. Elle ne dit pas que la réponse était juste. La page OpenAI le dit en renvoyant l’évaluation à plus tard, une fois le comportement stable. Elle ne dit pas non plus combien le run a coûté. Les jetons peuvent apparaître dans un span de génération. Le montant, s’il existe, se lit ailleurs. Cette page n’inscrit pas de chiffre de coût.

Une trace absente ne prouve pas qu’aucune action n’a eu lieu : le tracing peut être coupé, l’export peut rester en tampon ou échouer, et un autre composant peut agir hors du SDK. À l’inverse, une trace complète ne prouve ni l’exactitude, ni l’autorisation, ni l’absence de fuite. Pour une action sensible, rapprochez la trace d’un journal applicatif, de l’état du système cible et d’une évaluation du résultat.

L’historique de conversation n’est pas une trace. Mémoire d'agent garde des items pour le tour suivant. Une trace décrit ce qui s’est passé. Les deux peuvent porter le même texte d’outil. Ce n’est pas le même fichier.

Relevé nommé	Où la doc le place	Ce que je n’ai pas ouvert
Traces et spans	Agents SDK, dashboard Traces	Le dashboard
Variable LangSmith	Overview LangGraph, quickstart à part	La variable et le quickstart
JSONL de session	`~/.claude/projects/`	Le dossier
Logs d’application	Guide prévu dans un lot ultérieur	Un déploiement

Ce qui n’a pas tourné

Aucun Runner.run, aucun export, aucun dashboard. Les noms de spans, le défaut actif, et l’exception Zero Data Retention viennent de la page Tracing ouverte le 2026-10-18. Les prix ne sont pas sur cette page, ou n’ont pas été recopiés.

Sources

Ces pages officielles ont été relues le 2026-10-19. Aucune intégration, variable, clé, trace ou interface externe n’a été ouverte. Les détails décrivent la documentation, pas une installation vérifiée.