Skip to main content

Installation

Versions supportées : pydantic-ai-slim 2.0 à 3.0. La version 2.0 a supprimé Agent(instrument=...) et introduit le protocole de capacité sur lequel repose cet adaptateur — la version 1.x ne peut donc pas être instrumentée de cette façon.

Instrumentation

instrument() doit être exécuté avant la construction d’un Agent. La capacité est ajoutée au moment de la construction : un agent créé avant ne disposera d’aucune capacité et n’enregistrera rien, sans aucune erreur puisque rien ne s’est mal passé. C’est la cause la plus fréquente d’une trace vide avec cet adaptateur.
Les agents définis au niveau du module sont la source habituelle de ce problème :
Pour vérifier que l’instrumentation a bien fonctionné :
Pydantic AI fusionne la liste passée en une unique root_capability, il n’existe donc pas d’attribut agent.capabilities accessible directement. Les agents construits pendant la période d’instrumentation conservent la capacité : vous pouvez appeler uninstrument() puis ré-instrumenter sans avoir à les reconstruire.

Ce qui est enregistré

Il n’y a ni paire de hooks ni paire humain-dans-la-boucle ici. Pydantic AI ne dispose pas de frontière de nœud ou d’étape à délimiter, ni de pause humaine intégrée — il n’y a donc rien à mapper. Si vous en implémentez, émettez les événements vous-même — voir Agents personnalisés. output_type n’a aucune incidence sur la trace. Une exécution typée et une exécution retournant une chaîne produisent les mêmes événements.

Exemple

Dans la trace, restock_eta apparaît comme un tool_result portant une erreur, suivi d’un nouvel appel au modèle où l’agent trouve une alternative, et l’exécution se termine tout de même en success. Les deux informations sont conservées.

Erreurs, réessais et flux de contrôle

Pydantic AI lève des exceptions pour trois situations distinctes, que l’adaptateur différencie : ModelRetry appartient délibérément au premier groupe. Il indique qu’une tentative a réellement échoué et que le modèle a été invité à réessayer — c’est précisément ce à quoi sert le champ d’erreur d’un span d’outil. Le classifier comme flux de contrôle masquerait de vrais échecs d’outils derrière une exécution affichant un succès.

Nommez vos spans

Le span d’exécution propre à Pydantic AI s’appelle agent. Encapsulez l’appel pour lui donner le libellé de votre choix :
Le span du framework s’imbrique alors sous inventory, et c’est là que se rattachent les événements de modèle et d’outil. Gardez agent_id à faible cardinalité. C’est la facette principale sur toutes les surfaces du tableau de bord — utilisez un nom de rôle, jamais un UUID ou une chaîne générée par exécution.

Contrôler la session

Résolution dans cet ordre, la première correspondance l’emporte :
  1. instrument("pydantic_ai", session_id=...)
  2. Le contexte failproofai_sdk.session() englobant
  3. Le conversation_id de l’exécution, puis son run_id
  4. Un uuid4().hex généré automatiquement

Options

Problèmes courants

L’Agent a été construit avant l’exécution de instrument(). Consultez l’avertissement ci-dessus et vérifiez agent.root_capability.capabilities.
Un raise nu se propage — c’est le comportement voulu par Pydantic AI. Pour permettre au modèle de s’en sortir, levez ModelRetry avec un message sur lequel il peut agir. L’échec est enregistré dans tous les cas.
Cet enfant est le span d’exécution propre à Pydantic AI, et c’est là que se rattachent les événements de modèle et d’outil. Supprimez votre propre contexte si vous souhaitez un span unique, au prix du nom personnalisé.
La pile asynchrone de Pydantic AI dépasse la limite du champ de payload, et la dernière ligne d’une trace de pile est l’exception elle-même. Ce champ est rogné depuis le début plutôt que depuis la fin, de sorte que la ligne dont vous avez besoin est préservée.

Étapes suivantes

Fonctionnement interne

Paires, identifiants, cycle de vie des sessions et livraison.

Lire une trace

Suivre la causalité à travers la session que vous venez de capturer.

Autres frameworks

LangGraph, CrewAI, LlamaIndex et agents personnalisés.