PydanticAI

1. Vue d'ensemble du concept et problème systémique

La première vague de bibliothèques dédiées aux modèles de langage a été conçue à l'ère du prototypage rapide : elle reposait sur des classes dynamiques imbriquées, des dictionnaires non typés, des prompts invisibles et une héritage complexe. En production backend, cela engendrait des difficultés catastrophiques :

1. Absence d'autocomplétion et de refactoring : L'IDE ne comprend pas quels champs retourne l'agent, et le renommage d'une seule propriété casse le code au runtime sans aucune alerte.
2. Difficultés liées à la testabilité : Il est impossible d'isoler la logique agentique des services externes ou de substituer la base de données par un mock de test en raison de l'absence d'injection de dépendances (DI) conventionnelle.
3. Traitement peu fiable des erreurs de structure : Les modèles omettent souvent des champs obligatoires ou confondent les types (par exemple, une chaîne de caractères au lieu d'un nombre), ce qui entraîne des pannes d'API.

PydanticAI, développé par Samuel Colvin (l'auteur de Pydantic), ramène le développement d'agents dans le giron de l'ingénierie logicielle classique et propre : il s'agit d'un framework type-safe, minimaliste et performant, bâti sur la norme Pydantic v2.

2. Taxonomie architecturale et modèle mental

L'architecture de PydanticAI repose sur quatre piliers conceptuels :

• 1. Agent paramétré (Agent[Deps, ResultType]) : L'agent est explicitement typé par deux paramètres : le type des dépendances contextuelles (Deps) dont il a besoin pour fonctionner, et le type du résultat final (ResultType). Si le résultat est un modèle Pydantic, l'agent garantit le retour d'une instance validée de la classe.
• 2. Contexte d'exécution et DI (RunContext[Deps]) : Le mécanisme d'injection de dépendances. Chaque outil et chaque prompt dynamique accède à ctx.deps, où sont stockées les connexions actives à la base de données, la configuration ou les informations relatives aux droits de l'utilisateur.
• 3. Outils typés (@agent.tool) : Des fonctions Python dont les arguments sont automatiquement traduits en JSON Schema pour le LLM. Les descriptions des arguments sont extraites des Type Hints et des docstrings.
• 4. Prompts système dynamiques (@agent.system_prompt) : Des fonctions asynchrones qui construisent l'instruction système « à la volée » en se basant sur les dépendances transmises (par exemple, en injectant le solde actuel de l'utilisateur ou son fuseau horaire).

3. Pipeline technique et mécanique interne

Le cycle de vie de l'exécution d'une requête dans PydanticAI :

1. Instantiation & Context Binding (Assemblage du contexte) : Lors de l'appel agent.run(prompt, deps=my_deps), le framework initialise le RunContext et résout toutes les fonctions marquées par le décorateur @agent.system_prompt.
2. Schema Generation & Model Inference (Appel du modèle) : Les types des arguments des outils et le ResultType final sont convertis en schémas JSON stricts via le moteur Pydantic Core (écrit en Rust, garantissant une vitesse microseconde).
3. Tool Invocation with Self-Correction (Validation et correction) : Lorsque le modèle renvoie un appel d'outil, les arguments d'entrée passent par le validateur Pydantic. Si la validation échoue (par exemple, si un nombre négatif est fourni là où un PositiveInt est attendu), PydanticAI ne lève pas d'exception, mais renvoie automatiquement un message au modèle : « Erreur de validation du champ X : valeur > 0 attendue. Veuillez réessayer ».
4. Structured Output Serialization & Streaming (Retour du résultat) : La réponse finale est désérialisée vers l'objet Python cible. La méthode run_stream() est prise en charge, permettant de diffuser partiellement les champs de l'objet au client en temps réel.

4. Scénarios d'ingénierie pratiques en production

01. Agents natifs au sein de FastAPI

Partage des modèles : le même schéma InvoiceExtractionResponse sert à la fois de schéma de sortie pour PydanticAI, de response_model pour l'endpoint FastAPI, et permet la génération automatique du type TypeScript client via OpenAPI.

02. Gestion sécurisée des transactions de base de données

Via le RunContext, une session transactionnelle AsyncSession SQLAlchemy est injectée dans les outils. L'agent peut effectuer des vérifications et écrire des données. Si une erreur survient lors de l'étape finale, le gestionnaire de contexte externe effectue un rollback de la transaction, empêchant ainsi la persistance de données corrompues ou incomplètes.

03. Streaming d'interfaces structurées (Generative UI)

L'agent génère un tableau de bord dynamique. Grâce au support de la validation de flux par PydanticAI, le frontend peut rendre les graphiques et les cartes avant même que le modèle n'ait terminé la construction du document JSON complet.

5. Pièges courants, erreurs typiques et sécurité

• Absence de descriptions de champs (Field(description=...)) : Le modèle construit ses appels en se basant exclusivement sur les noms et les descriptions des champs. Si un champ est nommé de manière ambiguë (par exemple, status: int) et qu'il est dépourvu de description, le modèle hallucinera régulièrement avec des valeurs incorrectes.
• Épuisement des tentatives de correction (Max Retries Exceeded) : Si le schéma est trop complexe, le modèle peut épuiser la limite retries=3 en tentant d'adapter sa réponse au validateur, ce qui entraînera l'échec de la requête. Simplifiez les schémas ou décomposez-les en sous-tâches.
• Fuite de cycle de vie des ressources dans Deps : Assurez-vous que les objets transmis dans deps (pools de connexions, clients HTTP) sont correctement fermés après la fin de l'exécution de l'agent (via async with).