PydanticAI est né de l'équipe derrière la bibliothèque de validation sur laquelle repose l'essentiel du Python moderne, et cela se voit dans chaque partie. Une réponse du modèle revient sous forme d'objet conforme à un schéma, les dépendances sont injectées comme dans un vrai framework web, et les tests n'ont pas besoin d'appeler un modèle.
Ce qui distingue cette approche
La plupart des bibliothèques d'agents traitent la réponse d'un modèle comme du texte que l'on analyse ensuite. Ici, le point de départ est un type, et la bibliothèque se charge de faire tenir le résultat dedans.
pip install pydantic-aifrom pydantic import BaseModel
from pydantic_ai import Agent
class Ticket(BaseModel):
category: str
priority: int
needs_human: bool
agent = Agent(
"openai:gpt-5-mini",
output_type=Ticket,
system_prompt="You classify customer tickets. Priority from 1 to 5.",
)
result = agent.run_sync("I cannot log in since yesterday, urgent")
print(result.output.priority)L'objet renvoyé est déjà validé, donc lire un champ n'exige aucune vérification de son existence. Si le modèle répond hors schéma, la bibliothèque lui demande de se corriger en lui transmettant le message de validation, et vous ne voyez qu'un résultat valide ou une exception.
Cela règle le problème d'intégration le plus courant : gérer une réponse qui a l'air correcte et refuse de s'analyser. Le code qui s'occupait d'expressions régulières et de cas limites disparaît.
Des dépendances plutôt que des globales
Le deuxième élément distinctif est la façon dont le contexte parvient aux outils. Au lieu de chercher des globales ou des closures, vous déclarez un type de dépendance et la bibliothèque le fournit à chaque appel.
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
@dataclass
class Deps:
db: DatabaseConnection
customer_id: str
agent = Agent("openai:gpt-5", deps_type=Deps)
@agent.tool
async def order_history(ctx: RunContext[Deps], limit: int = 5) -> list[dict]:
"""Returns recent orders for the current customer.
Call this when the question concerns earlier purchases.
"""
return await ctx.deps.db.orders(ctx.deps.customer_id, limit)
result = await agent.run("What did I buy recently?", deps=Deps(db=db, customer_id="42"))Cet agencement a trois conséquences. L'outil ne sait pas d'où vient sa connexion à la base, donc un test la remplace par un stub. L'identifiant du client vient du contexte de l'appel plutôt que d'un argument que le modèle pourrait manipuler. Le code de l'outil reste propre, puisque toute la configuration se trouve au même endroit.
Le dernier point compte plus qu'il n'y paraît. Un agent qui sert de nombreux utilisateurs ne doit jamais laisser le modèle décider de quelles données récupérer. Passer l'identifiant par les dépendances plutôt que par le schéma de l'outil ferme cette voie au niveau de l'architecture.
Tester sans appeler de modèle
C'est là que la bibliothèque apporte le plus et, en même temps, là où les gens en profitent le moins. Les tests d'agents n'existent généralement pas, ou coûtent des tokens à chaque exécution.
from pydantic_ai.models.test import TestModel
def test_classification_returns_priority():
with agent.override(model=TestModel()):
result = agent.run_sync("Payment is not working")
assert 1 <= result.output.priority <= 5Le modèle de test génère des réponses conformes au schéma déclaré, donc vous vérifiez le flux, la gestion des dépendances et la validation sans réseau et sans coût. Pour exercer un chemin précis, vous pouvez aussi substituer un modèle qui renvoie une réponse fixe.
Testez séparément les outils comme de simples fonctions. Comme les dépendances sont injectées, appeler un outil dans un test n'exige ni agent ni modèle, seulement un objet de dépendances contenant des stubs.
La troisième couche est l'évaluation de la qualité sur un ensemble de cas, assurée par un paquet séparé de la même famille. C'est de la mesure plutôt qu'un test unitaire, donc lancez-la délibérément, car elle consomme des tokens.
Observabilité et exécution durable
La bibliothèque se branche sur le protocole de télémétrie standard, donc les traces d'appels arrivent dans l'outil d'observabilité propre au fournisseur ou dans n'importe quel système conforme. Vous voyez alors au même endroit les appels d'outils, les nouvelles tentatives après une validation échouée et la consommation de tokens.
Ce dernier chiffre est souvent le plus instructif. Un agent qui corrige deux fois une réponse hors schéma consomme trois fois les tokens qu'un seul appel laisse penser, et sans traces cette différence reste invisible.
L'exécution durable est un sujet à part, c'est-à-dire la résilience aux pannes pendant une longue tâche. La bibliothèque s'intègre avec des moteurs de workflows, donc un processus interrompu par une erreur réseau ou un redémarrage reprend là où il s'était arrêté au lieu de repartir de zéro.
Cela compte pour les tâches en plusieurs étapes où chaque étape coûte. Reprendre un processus qui a déjà fait sept appels sur dix économise du temps et l'argent dépensé en tokens.
Outils, MCP et toolsets
Vous définissez un outil avec un décorateur, et le schéma des arguments vient des annotations de types et de la docstring. C'est le même mécanisme que celui des frameworks web de cette équipe, donc il n'y a pas de format séparé à apprendre.
Les toolsets permettent de regrouper des fonctions et de les attacher d'un bloc à un agent, ce qui met de l'ordre dans le code dès qu'il y a dix outils. La bibliothèque permet aussi de connecter des serveurs du protocole MCP, donc des intégrations prêtes à l'emploi se branchent sans écrire vos propres enveloppes.
Les outils différés forment une catégorie à part, ce sont ceux dont l'exécution exige une décision humaine ou un processus plus long en dehors de l'agent. L'agent signale alors le besoin d'un appel, vous l'exécutez à votre rythme et vous revenez avec un résultat. Ce mécanisme est nécessaire partout où une action touche à l'argent ou à la communication avec les clients.
Streaming et réponses partielles
Une application avec une interface utilisateur doit montrer quelque chose avant huit secondes. La bibliothèque prend en charge le streaming même quand la sortie est typée, ce qui paraît contradictoire et fonctionne grâce à la validation partielle.
async with agent.run_stream("Describe outages from the last day") as stream:
async for chunk in stream.stream_output(debounce_by=0.1):
update_view(chunk)Les versions successives de l'objet arrivent à mesure que le modèle remplit les champs, et la bibliothèque valide ce qui est arrivé jusque-là. La vue reçoit d'abord la catégorie, puis la description, plutôt qu'un écran vide jusqu'à la fin de la génération.
Le paramètre de debounce compte en pratique. Sans lui, vous obtenez une mise à jour par token, ce qui, en pilotant une interface, peut charger le navigateur plus lourdement que l'appel au modèle lui-même. Un dixième de seconde suffit généralement.
Rappelez-vous séparément que le streaming ne réduit pas le coût. Vous payez les mêmes tokens et ne gagnez que la réactivité perçue, mais sur des réponses plus longues, c'est la différence entre une application que les gens utilisent et une qu'ils ferment.
Flux en plusieurs étapes et graphes
Un seul agent suffit pour les tâches décrites par un seul jeu d'outils. Dès qu'un processus a des étapes distinctes avec des branches, la bibliothèque propose un paquet séparé pour construire des graphes, où chaque nœud est une étape et où les transitions se déclarent par les types de retour.
Cette approche diffère du modèle populaire d'état partagé. Au lieu d'un dictionnaire dans lequel chaque nœud écrit des champs, vous passez des objets de classes concrètes, et le type de retour d'un nœud indique où le processus peut aller ensuite. Une mauvaise connexion apparaît pendant la vérification de types plutôt qu'à la troisième exécution.
En pratique, commencez par un agent et quelques outils, et ne passez à un graphe que quand vous devez mettre le processus en pause pour une décision humaine ou le reprendre après une interruption. Introduire un graphe plus tôt ajoute du code sans ajouter de contrôle.
Un bon signal qu'un graphe s'impose est le moment où votre prompt système commence à décrire l'ordre des étapes. Puisque l'ordre est connu, l'exprimer dans le code vaut mieux que d'espérer que le modèle le reconstitue à chaque fois.
L'évaluation plutôt que les impressions
Un changement de prompt qui améliore subjectivement les réponses en casse souvent un autre cas. La bibliothèque d'évaluation de la même famille permet de définir un ensemble de cas et de mesurer le score après chaque modification.
from pydantic_evals import Case, Dataset
dataset = Dataset(cases=[
Case(name="login", inputs="I cannot log in", expected_output={"priority": 4}),
Case(name="invoice", inputs="Please resend my invoice", expected_output={"priority": 2}),
])
report = dataset.evaluate_sync(task)Trente cas suffisent pour voir si un changement aide. Collectez-les à partir du trafic réel, surtout des situations où l'agent a échoué, car ce sont celles qui reviennent.
Séparez deux sortes de vérification. L'évaluation déterministe, qui compare un champ à une valeur attendue, est peu coûteuse et rapide. L'évaluation qui utilise un modèle comme juge coûte des tokens et introduit son propre bruit, donc réservez-la à ce qu'aucune vérification plus simple ne peut couvrir.
PydanticAI face aux alternatives
| Outil | Point fort | Point faible | À choisir quand |
|---|---|---|---|
| PydanticAI | Sorties et dépendances typées, tests sans modèle, cohérence de l'écosystème | Catalogue d'intégrations prêtes plus petit | Application Python en production qui exige de la prévisibilité |
| LangChain | Le plus grand ensemble d'intégrations, agent en une fonction | Plus d'abstraction à apprendre | Projet qui combine de nombreux modèles, outils et sources |
| CrewAI | Modèle de rôles lisible, démarrage rapide | Moins de contrôle sur la forme de la sortie | Équipe d'agents avec des tâches réparties |
| LangGraph | Contrôle total du flux, état durable | Plus de travail sur les cas simples | Processus avec branchements et pauses |
Le choix dépend de ce qu'il faut garantir. Si le plus important est que le résultat puisse passer sans risque dans le code suivant, le typage l'emporte. Si le plus important est le nombre d'intégrations prêtes, c'est le plus grand écosystème qui gagne.
Si tout ce dont vous avez besoin dans cette liste est que le modèle renvoie un objet conforme à un schéma, il existe une sortie plus légère. Instructor ne construit ni agent ni flux ; il enveloppe le client du fournisseur et ajoute un paramètre response_model avec une nouvelle tentative automatique quand la validation échoue. Deux réserves l'accompagnent : le paquet de base tire le client OpenAI même si vous utilisez un autre fournisseur, et le portage TypeScript s'est arrêté à une version de janvier 2025, donc en dehors de Python il est difficile à recommander.
Ces bibliothèques ne s'excluent pas mutuellement. Un agent construit ici peut utiliser des serveurs MCP exposés par d'autres outils et transmettre son résultat à un flux construit ailleurs.
Réglages du modèle, limites et modèle de repli
Un agent de production finira par rencontrer la surcharge d'un fournisseur ou une limite de débit. La bibliothèque permet de déclarer un modèle de repli qui prend le relais de l'appel quand le principal échoue, sans toucher au reste du code.
Le même mécanisme sert parfois d'économie. Un modèle moins cher traite le cas simple, et le modèle coûteux n'intervient que quand le moins cher ne peut pas satisfaire le schéma. Mesurez toutefois si cet agencement économise vraiment, car deux appels au lieu d'un peuvent coûter plus cher que de prendre directement le modèle le plus puissant.
Les réglages du modèle, dont le plafond de tokens de réponse et le délai d'expiration, se déclarent une fois sur l'agent ou se redéfinissent à chaque exécution. Le délai d'expiration est celui qu'on oublie le plus souvent, et il décide si un appel bloqué paralyse le processus pendant un quart d'heure.
Fixez séparément des limites au niveau de l'exécution : un nombre maximal d'appels au modèle et un nombre maximal d'appels d'outils. Un agent qui boucle et appelle le même outil quarante fois n'est pas une situation théorique, et sans plafond vous la rencontrerez sur la facture.
Quand ne pas s'en servir
Pour un seul appel au modèle où vous ne voulez que du texte, cette bibliothèque est superflue. Le client du fournisseur suffit et ajoute moins de dépendances.
Il en va de même pour un prototype dont le but est de vérifier si le modèle peut seulement traiter la tâche. Le typage aide quand le résultat alimente du code, pas quand vous le lisez vous-même.
Le troisième cas est une équipe qui travaille surtout en TypeScript. La bibliothèque n'existe qu'en Python, donc intégrer via un service séparé ajoute une couche qu'il vaut mieux éviter quand le reste du système vit dans un autre langage.
La frontière est assez lisible. Si la réponse d'un modèle va dans une fonction qui en fera quelque chose, le typage est rentable dès le premier jour. Si une personne lit la réponse, le gain est faible.
Erreurs courantes
La première est un schéma de sortie trop élaboré. Un modèle qui remplit une structure de quinze champs avec des listes imbriquées se heurte plus souvent à la validation, et chaque correction coûte. Commencez avec trois champs et élargissez.
La deuxième est de passer l'identifiant de l'utilisateur dans le schéma de l'outil plutôt que dans les dépendances. Le modèle peut alors fournir l'identifiant de quelqu'un d'autre, et vous n'avez d'autre garde-fou que la surveillance du prompt.
La troisième est l'absence de limite de nouvelles tentatives sur la validation. Un modèle qui renvoie obstinément un résultat hors schéma réessaiera autant de fois que vous l'autorisez, donc fixez un plafond et traitez son atteinte comme un signal pour corriger le schéma.
La quatrième, ce sont les docstrings écrites pour un développeur. Le modèle lit le même texte, donc une phrase qui dit quand appeler l'outil compte plus qu'une description de l'implémentation.
La cinquième est de sauter les tests parce qu'un agent est de toute façon non déterministe. Le modèle de test permet de tout vérifier sauf le texte de la réponse lui-même, et c'est là que se cachent la plupart des bugs.
FAQ
PydanticAI est-il gratuit ?
Oui, la bibliothèque est open source sous licence MIT et gratuite en usage commercial. Vous ne payez que les appels au modèle chez le fournisseur de votre choix. Les mainteneurs exploitent un outil d'observabilité séparé avec un plan gratuit qui couvre dix millions d'enregistrements par mois, plafonné une fois cette limite atteinte, et des plans payants à partir de 49 dollars par mois. La bibliothèque fonctionne sans lui et émet de la télémétrie vers n'importe quel système conforme.
PydanticAI ou LangChain ?
Choisissez PydanticAI quand vous voulez une forme de sortie prévisible, de la testabilité et de la cohérence avec le reste de votre code Python. LangChain apporte bien plus d'intégrations prêtes et convient mieux quand il faut connecter de nombreuses sources de données sans écrire d'adaptateurs.
Fonctionne-t-il avec d'autres modèles qu'OpenAI ?
Oui, la couche des modèles est neutre vis-à-vis des fournisseurs et prend en charge Claude, Gemini et les modèles locaux servis par Ollama, entre autres. Changer revient à modifier l'identifiant du modèle, même si le prompt demande généralement d'être réajusté.
Qu'apporte concrètement la sortie typée ?
La couche de code qui gérait l'analyse et les réponses non conformes disparaît. Un résultat revient comme un objet conforme au schéma ou ne revient pas du tout, donc les étapes suivantes peuvent s'y fier sans vérifier. Pour la classification et l'extraction de données, c'est la plus grosse économie.
Est-il prêt pour la production ?
Oui, à deux conditions. Fixez des limites de nouvelles tentatives et une gestion d'erreurs, car sans elles une validation échouée se transforme en boucle qui brûle des tokens. Branchez aussi la télémétrie, car sans traces d'appels, diagnostiquer le comportement d'un agent revient à deviner.
La documentation se trouve sur le site du projet, et le code source dans le dépôt GitHub.