Installation
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
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
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’appelleagent. Encapsulez l’appel pour lui donner le libellé de votre choix :
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 :instrument("pydantic_ai", session_id=...)- Le contexte
failproofai_sdk.session()englobant - Le
conversation_idde l’exécution, puis sonrun_id - Un
uuid4().hexgénéré automatiquement
Options
Problèmes courants
L'exécution fonctionne mais aucun événement n'apparaît
L'exécution fonctionne mais aucun événement n'apparaît
L’
Agent a été construit avant l’exécution de instrument(). Consultez l’avertissement ci-dessus et vérifiez agent.root_capability.capabilities.Une exception ordinaire dans un outil interrompt l'exécution
Une exception ordinaire dans un outil interrompt l'exécution
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.Un span d'agent imbriqué apparaît sans que je l'aie créé
Un span d'agent imbriqué apparaît sans que je l'aie créé
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é.
Les traces de pile commencent par un marqueur de troncature
Les traces de pile commencent par un marqueur de troncature
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.

