Si vous avez déjà déployé une fonctionnalité LLM et l'avez vue renvoyer du JSON malformé en production, PydanticAI est fait pour vous. C'est le framework d'agents Python de l'équipe derrière Pydantic, et il place les sorties validées et de type sûr au cœur du développement d'agents. Ce guide explique ce qu'est PydanticAI, pourquoi la sûreté des types est importante pour les agents, les concepts fondamentaux que vous utiliserez réellement, et comment il se compare à d'autres frameworks Python comme LangGraph.
Qu'est-ce que PydanticAI
PydanticAI est un framework d'agents open-source et agnostique vis-à-vis des fournisseurs pour Python. Il est maintenu par la même équipe qui développe Pydantic Validation et Pydantic Logfire, il hérite donc d'une solide base de validation et d'un objectif de conception clair : apporter « cette sensation FastAPI » au développement d'agents.
En termes simples, vous décrivez ce que votre agent doit faire, les outils qu'il peut appeler et la forme que doit prendre sa sortie. PydanticAI gère les appels de modèle, valide tout par rapport à vos modèles Pydantic et réessaie lorsque le modèle renvoie quelque chose qui ne correspond pas.
Le projet a atteint une version stable v2.0.0 le 23 juin 2026, après une série de versions bêta. La version 2 s'appuie sur une conception axée sur le harnais où les outils, les hooks, les instructions et les paramètres de modèle d'un agent se composent comme des unités réutilisables. Vous pouvez l'installer avec pip install pydantic-ai ou uv add pydantic-ai.
Pourquoi la sûreté des types est importante pour les agents
Les LLM sont non déterministes. Posez la même question deux fois et vous pouvez obtenir deux formes de réponse différentes. C'est bien pour une boîte de discussion, mais cela pose problème dès que vous connectez la sortie du modèle à du vrai code : une écriture de base de données, un appel d'API, un calcul de facturation.
La plupart des bugs d'agents proviennent de cet écart. Le modèle renvoie « principalement » du JSON valide, votre analyseur fonctionne en test, puis une réponse de production omet un champ ou enveloppe la réponse dans de la prose et votre pipeline plante. Vous finissez par écrire manuellement de l'analyse défensive, du nettoyage par expressions régulières et des boucles de réessai.
PydanticAI comble cette lacune en faisant du contrat de sortie une partie intégrante du framework. Vous définissez un modèle Pydantic, le transmettez comme type de sortie, et le framework garantit que la valeur que vous recevez correspond à ce modèle. Si le modèle renvoie quelque chose d'invalide, PydanticAI renvoie l'erreur de validation au LLM et lui demande de réessayer. Votre code en aval reçoit des objets typés, et non des chaînes de caractères incertaines.
Cette même idée s'étend aux arguments des outils. Lorsque le modèle appelle l'un de vos outils, PydanticAI valide les arguments par rapport aux annotations de type de votre fonction avant que la fonction ne s'exécute. Les arguments invalides n'atteignent jamais votre logique métier.
Concepts fondamentaux
PydanticAI garde sa surface d'attaque petite. Cinq idées couvrent la majeure partie de ce que vous allez construire.
Agents
La classe Agent est le point d'entrée principal. Vous en créez une avec un identifiant de modèle et des instructions optionnelles. La classe est générique sur deux paramètres de type : le type des dépendances et le type de sortie, ce qui confère à votre éditeur et à votre vérificateur de type une visibilité réelle sur votre agent.
from pydantic_ai import Agent
agent = Agent(
'anthropic:claude-sonnet-4-6',
instructions='Be concise, reply with one sentence.',
)
result = agent.run_sync('Where does "hello world" come from?')
print(result.output)
Cette chaîne de modèle est la seule chose que vous modifiez pour changer de fournisseur, ce qui rend votre code portable.
Sorties typées
Passez un modèle Pydantic comme output_type et le résultat de l'agent est validé par rapport à celui-ci. Vous obtenez un objet typé en retour, et votre IDE connaît chaque champ. Voici un aperçu de sortie structurée :
from pydantic import BaseModel
from pydantic_ai import Agent
class SupportTicket(BaseModel):
category: str
priority: int
summary: str
agent = Agent('openai:gpt-4o', output_type=SupportTicket)
result = agent.run_sync('My payment failed three times today.')
print(result.output.priority) # un entier, validé, pas une supposition
Si le modèle renvoie une priorité sous forme de texte ou omet le résumé, la validation échoue et le framework relance l'invite. Vous ne parsez jamais vous-même la réponse brute.
Outils
Les outils permettent au modèle de s'étendre : interroger une base de données, appeler une API REST, effectuer un calcul. Vous enregistrez un outil avec le décorateur @agent.tool. PydanticAI lit les annotations de type et la docstring de la fonction pour construire le schéma que le modèle voit, puis valide chaque appel par rapport à celui-ci.
from pydantic_ai import Agent, RunContext
agent = Agent('openai:gpt-4o', deps_type=str)
@agent.tool
async def get_user_balance(ctx: RunContext[str], account_id: str) -> float:
"""Retourne le solde actuel d'un compte."""
# ctx.deps contient votre dépendance injectée
return await lookup_balance(ctx.deps, account_id)
Le modèle décide quand appeler l'outil. Votre fonction ne s'exécute qu'avec des arguments qui ont déjà passé la validation.
Dépendances
Les agents réels ont besoin de contexte : une connexion de base de données, un client HTTP, l'utilisateur actuel, une clé API. PydanticAI gère cela avec l'injection de dépendances. Vous déclarez un deps_type sur l'agent, puis le lisez via RunContext à l'intérieur des outils et des instructions dynamiques. Toute la chaîne reste de type sûr, et les tests deviennent plus faciles car vous pouvez échanger de vraies dépendances contre des fausses.
Fournisseurs agnostiques et streaming
PydanticAI prend en charge une longue liste de fournisseurs : OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, ainsi que des options cloud comme Azure AI Foundry et Amazon Bedrock et des modèles auto-hébergés. Le changement est généralement une modification d'une seule ligne de la chaîne du modèle.
Il diffuse également des sorties structurées avec validation appliquée au fur et à mesure de l'arrivée des données, afin que vous puissiez afficher des résultats partiels sans renoncer aux garanties de type. Et parce que l'équipe développe également Pydantic Logfire, l'observabilité est intégrée : traçage, débogage et suivi des coûts pour chaque exécution.
Comment PydanticAI se compare aux autres frameworks d'agents Python
Il n'existe pas de framework "meilleur" unique. Ils sont optimisés pour des choses différentes. Voici une analyse honnête de la position de PydanticAI.
| Framework | Point fort principal | Idéal lorsque vous voulez |
|---|---|---|
| PydanticAI | Sorties et arguments d'outils validés et de type sûr | Fiabilité en production et flux de données typées propre |
| LangGraph | Graphes explicites avec état et contrôle de flux | Workflows longs, ramifiés et en plusieurs étapes |
| Google ADK | Orchestration multi-agents dans l'écosystème Google | Intégration profonde de Gemini et Vertex AI |
| OpenAI Agents SDK | Intégration étroite d'OpenAI avec transferts | Une pile privilégiant OpenAI et une configuration rapide |
L'avantage de PydanticAI est sa couche de validation. Si votre agent alimente d'autres systèmes avec des données typées, la garantie que la sortie correspond à un modèle Pydantic élimine toute une catégorie d'erreurs d'exécution. LangGraph vous offre un contrôle plus fin sur les machines à états et les flux complexes. L'OpenAI Agents SDK est un choix naturel si vous êtes déjà engagé avec OpenAI et souhaitez des fonctionnalités telles que les transferts d'agents et le support de serveur MCP.
Vous pouvez également les mélanger. PydanticAI fonctionne bien comme couche de sortie typée au sein d'une orchestration plus large.
Quand utiliser PydanticAI
Optez pour PydanticAI lorsque :
- La sortie de votre agent est intégrée à du code, pas seulement à une fenêtre de chat, et la forme doit être correcte.
- Vous voulez que votre vérificateur de type et votre IDE comprennent votre agent de bout en bout.
- Vous utilisez déjà Pydantic dans votre base de code, de sorte que les définitions de modèle semblent natives.
- Vous avez besoin de flexibilité de fournisseur et ne voulez pas réécrire votre agent pour changer de modèle.
- L'observabilité est importante et le traçage intégré de Logfire est attrayant.
Cherchez ailleurs lorsque vous avez besoin d'une orchestration lourde basée sur des graphes avec des ramifications complexes, où un framework de machine à états vous offre un contrôle plus direct.
Tester et simuler les API derrière votre agent
Un agent PydanticAI n'est aussi fiable que les API dont il dépend. Chaque exécution appelle un fournisseur LLM, et la plupart des agents utiles appellent également vos propres points de terminaison REST ou des outils tiers. C'est là que des comportements imprévisibles, des coûts inattendus et des incohérences de forme peuvent survenir. PydanticAI valide la sortie du modèle, mais il ne peut pas valider que l'API de l'outil en amont que vous appelez renvoie ce que vous attendez.
C'est là qu'Apidog intervient, et c'est un rôle différent de celui du framework. Apidog est une plateforme API où vous testez et simulez les API sous-jacentes avec lesquelles votre agent communique.
Quelques utilisations concrètes :
- Simulez le LLM ou un point de terminaison d'outil. Pendant le développement, dirigez un outil vers une API de simulation qui renvoie des réponses déterministes. Vous arrêtez de dépenser des jetons à chaque exécution de test et vous contournez les limites de débit du fournisseur pendant l'itération.
- Affirmez les formes de réponse. Avant de connecter un point de terminaison REST à une fonction
@agent.tool, utilisez les assertions API pour confirmer que la réponse réelle correspond à la structure attendue par votre outil. Détectez un champ manquant au niveau de la couche API, et non profondément à l'intérieur d'une exécution d'agent. - Gérez les clés par environnement. Conservez les clés de fournisseur et les URL de base dans des environnements Apidog distincts afin que les exécutions locales, de staging et de CI atteignent les bonnes cibles sans modification de code.
- Vérifiez directement le point de terminaison LLM. Si vous appelez un fournisseur via HTTP, vous pouvez tester l'API ChatGPT avec Apidog pour confirmer l'authentification, le streaming et les formats d'appel d'outils avant que votre agent n'en dépende.
Apidog ne construit ni n'orchestre les agents, et ce n'est pas une alternative à PydanticAI. C'est le banc de test où vous testez et simulez la surface API sur laquelle votre agent s'exécute. Si vous voulez l'essayer, téléchargez Apidog et simulez d'abord l'un de vos points de terminaison d'outil.
Foire aux questions
PydanticAI est-il gratuit et open source ?
Oui. PydanticAI est open source et vous l'installez depuis PyPI avec pip install pydantic-ai ou uv add pydantic-ai. Vous paierez toujours pour le fournisseur LLM que vous utilisez, car le framework appelle ces API en votre nom. Pour réduire ces coûts de fournisseur pendant que vous développez, vous pouvez simuler les réponses de l'API pendant les tests au lieu d'interroger le modèle en direct à chaque exécution.
Avec quels modèles PydanticAI fonctionne-t-il ?
Il est agnostique vis-à-vis des fournisseurs. La documentation liste OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral et Perplexity, ainsi que des options cloud comme Azure AI Foundry et Amazon Bedrock et des modèles auto-hébergés. Vous sélectionnez un modèle en passant une chaîne comme 'anthropic:claude-sonnet-4-6' ou 'openai:gpt-4o' au constructeur de l'Agent, et le changement est généralement une modification d'une seule ligne.
En quoi PydanticAI est-il différent de LangChain ou LangGraph ?
PydanticAI se concentre sur la sûreté des types : des sorties structurées validées et des arguments d'outils validés, soutenus par des modèles Pydantic. LangGraph se concentre sur des graphes explicites avec état pour des workflows multi-étapes et ramifiés. Si votre priorité est de garantir les formes de sortie et un flux de données typées propre, PydanticAI convient bien. Si vous avez besoin d'un contrôle précis sur une machine à états complexe, un framework de graphes vous offre des leviers plus directs.
Dois-je connaître Pydantic pour l'utiliser ?
Cela aide, mais les bases sont rapides à acquérir. Vous définissez des formes de données comme des classes qui héritent de BaseModel, et PydanticAI les utilise pour les sorties et les schémas d'outils. Si vous avez utilisé Python pour les tests d'API ou travaillé avec FastAPI, le modèle mental vous sera familier.
Conclusion
PydanticAI apporte quelque chose de pratique au développement d'agents : la garantie que les sorties de votre modèle et les appels d'outils correspondent aux types que vous avez déclarés. Cela élimine une source réelle de bugs en production et maintient un flux de données propre. Choisissez-le lorsque la fiabilité et les sorties typées sont plus importantes qu'une orchestration complexe basée sur des graphes.
Quel que soit le framework que vous choisissez, les API sous-jacentes à votre agent doivent toujours être testées. Simulez vos points de terminaison LLM et d'outils, affirmez leurs formes de réponse et gérez les clés par environnement dans Apidog afin que votre agent s'exécute sur une base que vous avez réellement vérifiée.