Pydantic AI

En bref

Pydantic AI est un framework Python consacré aux applications qui font travailler un modèle de langage avec des instructions, des outils et des données applicatives. Il reprend les principes qui ont fait le succès de Pydantic et FastAPI : annotations de types, validation explicite et objets faciles à tester.

Il convient particulièrement aux équipes Python qui veulent construire un agent sans adopter immédiatement une plateforme d’orchestration très large. Le framework prend en charge la boucle d’agent, les appels d’outils, les sorties structurées, l’injection de dépendances, les nouvelles tentatives et l’instrumentation.

Quel problème résout-il ?

Un appel isolé à un modèle renvoie du texte. Une application métier doit souvent aller plus loin : interroger une base, appeler une API, produire un objet conforme à un schéma, demander une confirmation avant une action sensible et conserver assez de traces pour comprendre un échec.

Pydantic AI rassemble ces besoins autour de la classe Agent. Le modèle choisit éventuellement un outil, reçoit son résultat, puis poursuit jusqu’à produire la sortie attendue ou atteindre une limite. Les arguments d’outils et la réponse finale peuvent être validés par Pydantic.

from pydantic import BaseModel, Field
from pydantic_ai import Agent


class Diagnostic(BaseModel):
    resume: str
    priorite: int = Field(ge=1, le=3)


agent = Agent(
    "openai:gpt-5",
    output_type=Diagnostic,
    instructions="Analyse le signalement sans inventer d’information.",
)

resultat = agent.run_sync("La page de paiement renvoie une erreur 502.")
print(resultat.output.priorite)

Le schéma améliore l’intégration avec le reste du programme, mais il ne garantit pas que le contenu est vrai. La validation contrôle la forme et les règles codées ; l’exactitude métier doit encore être testée.

Outils et dépendances

Une fonction Python peut devenir un outil. Sa signature sert à construire le schéma transmis au modèle et sa documentation l’aide à décider quand l’appeler. L’injection de dépendances permet de fournir au code une connexion, un client HTTP ou l’identité courante sans exposer cet objet au modèle.

Cette séparation est importante : le modèle propose un appel avec des arguments limités ; l’application conserve la responsabilité des secrets, des autorisations et de l’exécution réelle.

Modèles et fournisseurs

Pydantic AI propose une interface commune pour plusieurs fournisseurs et modèles locaux. Cette abstraction facilite les essais et certains remplacements, mais elle ne rend pas les modèles interchangeables. Le format des outils, les sorties structurées, le raisonnement, les limites de contexte, le prix et la latence restent propres à chaque fournisseur.

Un changement de modèle doit donc repasser par les évaluations. Il faut aussi conserver les paramètres et versions utilisés pour pouvoir reproduire un comportement.

Tests et observabilité

Le framework fournit des modèles de test qui évitent d’appeler un service externe dans les tests unitaires. Pour les tests de comportement, utilisez un petit jeu de cas représentatifs et mesurez au minimum : réussite de la tâche, validité de la sortie, nombre d’outils appelés, coût, latence et erreurs dangereuses.

L’instrumentation s’intègre notamment à Pydantic Logfire et à l’écosystème OpenTelemetry. Elle permet de suivre les étapes d’une exécution, mais les prompts et résultats peuvent contenir des données sensibles : filtrez ou masquez les champs avant export.

Quand choisir Pydantic AI ?

Choisissez-le si :

• votre application est principalement écrite en Python ;
• les sorties typées et la validation sont centrales ;
• vous voulez injecter proprement des dépendances dans les outils ;
• vous préférez composer un agent dans du code plutôt que configurer une plateforme ;
• vous voulez tester la logique sans appeler systématiquement un modèle réel.

Évaluez une autre approche si vous cherchez avant tout un éditeur visuel, un catalogue complet de connecteurs prêts à l’emploi ou une orchestration distribuée multi-agents déjà structurée.

Points de vigilance

• Une sortie conforme au schéma peut rester factuellement fausse.
• Un outil doit vérifier les autorisations côté serveur, même si les instructions interdisent certains usages.
• Les nouvelles tentatives augmentent le coût et peuvent répéter une action si celle-ci n’est pas idempotente.
• Les agents longs ont besoin de limites explicites : tours, temps, budget et volume de sortie.
• L’abstraction fournisseur ne dispense pas de tests par modèle.

À retenir

Pydantic AI apporte une couche agentique cohérente aux projets Python déjà familiers de Pydantic. Sa valeur principale n’est pas de rendre un modèle autonome, mais de rendre ses interactions avec l’application plus typées, vérifiables et observables.