Qu'est-ce que PydanticAI ? Guide du framework d'agents Python à typage fort

Si vous avez déjà mis en production une fonctionnalité basée sur un LLM et reçu du JSON invalide, PydanticAI cible exactement ce problème. Ce framework d’agents Python, créé par l’équipe derrière Pydantic, met la validation et les types au centre du développement d’agents. Dans ce guide, vous verrez comment l’utiliser pour obtenir des sorties structurées, valider les appels d’outils et choisir quand l’utiliser plutôt qu’un framework comme LangGraph.

Essayez Apidog dès aujourd’hui

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 l’équipe qui développe Pydantic Validation et Pydantic Logfire, avec un objectif clair : apporter une expérience proche de FastAPI au développement d’agents.

Concrètement, vous définissez :

• ce que l’agent doit faire ;
• les outils qu’il peut appeler ;
• la forme exacte de sa sortie ;
• les dépendances dont il a besoin.

PydanticAI orchestre ensuite les appels au modèle, valide les sorties avec vos modèles Pydantic et relance le modèle si la réponse ne respecte pas le contrat attendu.

Le projet a atteint une version stable v2.0.0 le 23 juin 2026, après plusieurs versions bêta. La version 2 repose sur une conception centrée sur le harnais : outils, hooks, instructions et paramètres de modèle peuvent être composés comme des unités réutilisables.

Installation :

pip install pydantic-ai

ou avec uv :

uv add pydantic-ai

Pourquoi la sûreté des types est importante pour les agents

Les LLM sont non déterministes. Une même invite peut produire deux structures de réponse différentes. Pour une conversation, ce n’est pas forcément bloquant. Pour du code de production, c’est risqué.

Exemples de cas problématiques :

• une écriture en base reçoit un champ manquant ;
• un appel API reçoit une valeur au mauvais format ;
• un calcul de facturation utilise une chaîne au lieu d’un nombre ;
• une réponse censée être du JSON contient de la prose autour.

Sans validation stricte, vous finissez souvent avec :

• du parsing défensif ;
• des expressions régulières pour nettoyer les réponses ;
• des boucles de retry manuelles ;
• des erreurs difficiles à reproduire en production.

PydanticAI déplace ce contrat dans le framework. Vous définissez un modèle Pydantic, vous le passez comme type de sortie, et votre code reçoit un objet validé. Si le modèle renvoie une réponse invalide, PydanticAI transmet l’erreur de validation au LLM et lui demande de corriger sa sortie.

Le même principe s’applique aux outils. Quand le modèle appelle une fonction, PydanticAI valide les arguments avec les annotations de type avant d’exécuter votre logique métier.

Concepts fondamentaux

PydanticAI reste volontairement compact. La plupart des cas d’usage reposent sur cinq concepts : agents, sorties typées, outils, dépendances et fournisseurs.

1. Créer un agent

La classe Agent est le point d’entrée principal. Vous lui fournissez un modèle et, si nécessaire, des instructions système.

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)

La chaîne du modèle permet de changer de fournisseur sans réécrire l’agent. Par exemple, passer de :

'anthropic:claude-sonnet-4-6'

à :

'openai:gpt-4o'

revient généralement à modifier une seule ligne.

2. Valider une sortie structurée

Pour éviter de parser du texte brut, définissez un modèle Pydantic et utilisez-le comme output_type.

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.')

ticket = result.output

print(ticket.category)
print(ticket.priority)
print(ticket.summary)

Ici, result.output n’est pas une chaîne à parser. C’est une instance validée de SupportTicket.

Si le modèle renvoie par exemple :

{
  "category": "billing",
  "priority": "high"
}

la validation échoue, car priority doit être un entier et summary est manquant. PydanticAI peut alors relancer le modèle avec l’erreur de validation.

Résultat : votre code applicatif manipule des objets typés, pas des réponses incertaines.

3. Ajouter des outils

Les outils permettent à l’agent d’interagir avec votre système : base de données, API REST, calcul métier, service interne, etc.

Vous les déclarez avec le décorateur @agent.tool.

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."""
    return await lookup_balance(ctx.deps, account_id)

PydanticAI utilise :

• les annotations de type ;
• la docstring ;
• le type de dépendance ;
• la signature de la fonction.

Ces informations servent à générer le schéma que le modèle peut utiliser pour appeler l’outil.

Avant l’exécution, les arguments sont validés. Si le modèle tente d’appeler l’outil avec un account_id invalide ou un argument manquant, votre fonction n’est pas appelée avec des données incorrectes.

4. Injecter des dépendances

Un agent de production a rarement tout en mémoire. Il a souvent besoin de dépendances :

• client HTTP ;
• connexion base de données ;
• utilisateur courant ;
• configuration ;
• clé API ;
• service métier.

PydanticAI gère cela avec deps_type et RunContext.

Exemple avec un client applicatif :

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class AppDeps:
    api_base_url: str
    auth_token: str

agent = Agent(
    'openai:gpt-4o',
    deps_type=AppDeps,
)

@agent.tool
async def get_order_status(ctx: RunContext[AppDeps], order_id: str) -> str:
    """Retourne le statut d'une commande."""
    return await fetch_order_status(
        base_url=ctx.deps.api_base_url,
        token=ctx.deps.auth_token,
        order_id=order_id,
    )

Exécution :

deps = AppDeps(
    api_base_url='https://api.example.com',
    auth_token='secret-token',
)

result = await agent.run(
    'Quel est le statut de la commande 123 ?',
    deps=deps,
)

print(result.output)

Ce modèle facilite aussi les tests. Vous pouvez injecter de fausses dépendances sans modifier l’agent.

5. Changer de fournisseur et utiliser le streaming

PydanticAI prend en charge plusieurs fournisseurs, notamment OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, Azure AI Foundry, Amazon Bedrock et des modèles auto-hébergés.

Le changement se fait généralement via la chaîne de modèle :

agent = Agent('openai:gpt-4o')

ou :

agent = Agent('anthropic:claude-sonnet-4-6')

Le framework prend aussi en charge le streaming de sorties structurées, avec validation appliquée pendant l’arrivée des données. Cela permet d’afficher des résultats partiels sans abandonner les garanties de type.

Comme l’équipe développe également Pydantic Logfire, l’observabilité est intégrée : traçage, débogage et suivi des coûts pour les exécutions d’agents.

Comparaison avec d’autres frameworks d’agents Python

Il n’existe pas de meilleur framework universel. Le bon choix dépend surtout du niveau de contrôle, de validation et d’orchestration dont vous avez besoin.

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

PydanticAI est particulièrement utile lorsque votre agent produit des données consommées par d’autres systèmes. Sa couche de validation réduit les erreurs d’exécution liées aux champs absents, aux types incorrects ou aux réponses mal structurées.

LangGraph est plus adapté si vous devez modéliser explicitement une machine à états avec des branches, des retours arrière et des workflows longs.

L’OpenAI Agents SDK est pertinent si vous êtes déjà centré sur OpenAI et que vous voulez utiliser des fonctionnalités comme les transferts d’agents ou le support de serveur MCP.

Vous pouvez aussi combiner les approches. Par exemple, utiliser un orchestrateur plus large pour le workflow, puis PydanticAI pour obtenir des sorties strictement typées à certaines étapes.

Quand utiliser PydanticAI

Utilisez PydanticAI lorsque :

• la sortie de l’agent alimente du code, pas seulement une interface de chat ;
• vous devez garantir la forme des données ;
• vous voulez que votre IDE et votre vérificateur de types comprennent votre agent ;
• vous utilisez déjà Pydantic ou FastAPI ;
• vous voulez changer de fournisseur LLM avec un minimum de modifications ;
• vous avez besoin d’observabilité avec Logfire ;
• vous voulez limiter le parsing manuel et les retries faits maison.

Cherchez plutôt un framework orienté graphe lorsque :

• votre workflow contient beaucoup de branches ;
• l’état doit être contrôlé explicitement à chaque étape ;
• plusieurs agents doivent collaborer dans une orchestration complexe ;
• vous avez besoin d’un contrôle fin de type machine à états.

Tester et simuler les API derrière votre agent

Un agent PydanticAI est aussi fiable que les API qu’il appelle. Même si PydanticAI valide les sorties du modèle, il ne peut pas garantir à lui seul que vos API externes renvoient exactement les structures attendues.

Un agent peut dépendre de :

• l’API du fournisseur LLM ;
• vos endpoints REST internes ;
• des outils tiers ;
• une API de paiement ;
• une API de support client ;
• un service d’authentification.

C’est là qu’Apidog intervient. Apidog n’est pas un framework d’agents et ne remplace pas PydanticAI. C’est une plateforme API pour tester, documenter et simuler les endpoints sur lesquels votre agent s’appuie.

Simuler un endpoint d’outil

Pendant le développement, vous pouvez pointer un outil vers une API de simulation au lieu d’appeler le vrai service.

Cela permet de :

• éviter de consommer des tokens à chaque test ;
• contourner les limites de débit pendant l’itération ;
• obtenir des réponses déterministes ;
• tester les erreurs et cas limites sans impacter la production.

Exemple côté agent :

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    tools_api_base_url: str

agent = Agent('openai:gpt-4o', deps_type=Deps)

@agent.tool
async def get_invoice_status(ctx: RunContext[Deps], invoice_id: str) -> str:
    """Retourne le statut d'une facture."""
    url = f'{ctx.deps.tools_api_base_url}/invoices/{invoice_id}'
    return await fetch_status(url)

En local, tools_api_base_url peut pointer vers un mock Apidog. En staging ou production, il peut pointer vers votre vraie API.

Valider la forme des réponses API

Avant de connecter un endpoint REST à une fonction @agent.tool, vérifiez que sa réponse correspond à ce que votre outil attend.

Avec les assertions API, vous pouvez détecter :

• un champ manquant ;
• un mauvais type ;
• une structure JSON inattendue ;
• un code HTTP incorrect ;
• une réponse vide ;
• une rupture de contrat entre environnements.

Cela vous évite de découvrir le problème au milieu d’une exécution d’agent.

Gérer les environnements

Un même agent peut être exécuté en local, en CI, en staging ou en production. Les URLs et clés ne doivent pas être codées en dur.

Vous pouvez gérer séparément :

• les URLs de base ;
• les tokens ;
• les clés fournisseur ;
• les endpoints mockés ;
• les endpoints réels.

L’objectif est simple : changer d’environnement sans modifier le code de l’agent.

Tester directement un endpoint LLM

Si vous appelez un fournisseur LLM via HTTP, vous pouvez tester l’API ChatGPT avec Apidog avant d’y connecter votre agent.

Vérifiez notamment :

• l’authentification ;
• le format de requête ;
• le streaming ;
• les erreurs ;
• les formats d’appel d’outils ;
• les limites de débit.

Si vous voulez l’essayer, téléchargez Apidog et commencez par simuler un endpoint utilisé par l’un de vos outils.

Foire aux questions

PydanticAI est-il gratuit et open source ?

Oui. PydanticAI est open source et s’installe depuis PyPI :

pip install pydantic-ai

ou :

uv add pydantic-ai

Vous devrez toutefois payer le fournisseur LLM utilisé, car PydanticAI appelle ces API en votre nom. Pour réduire les coûts pendant le développement, vous pouvez simuler les réponses de l’API au lieu d’interroger le modèle réel à chaque test.

Avec quels modèles PydanticAI fonctionne-t-il ?

PydanticAI est agnostique vis-à-vis des fournisseurs. La documentation mentionne 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 choisissez un modèle avec une chaîne comme :

Agent('anthropic:claude-sonnet-4-6')

ou :

Agent('openai:gpt-4o')

Dans la plupart des cas, changer de modèle revient à modifier cette chaîne.

En quoi PydanticAI est-il différent de LangChain ou LangGraph ?

PydanticAI se concentre sur la sûreté des types : sorties structurées validées, arguments d’outils validés et intégration native avec les modèles Pydantic.

LangGraph se concentre davantage sur les graphes explicites avec état pour les workflows multi-étapes et ramifiés.

Choisissez PydanticAI si votre priorité est la fiabilité des données produites par l’agent. Choisissez un framework orienté graphe si votre priorité est le contrôle précis d’une orchestration complexe.

Dois-je connaître Pydantic pour utiliser PydanticAI ?

Cela aide, mais les bases sont rapides à apprendre. Vous définissez des structures de données avec des classes qui héritent de BaseModel, puis PydanticAI les utilise pour valider les sorties et les schémas d’outils.

Exemple minimal :

from pydantic import BaseModel

class Answer(BaseModel):
    title: str
    confidence: float

Si vous avez déjà utilisé Python pour les tests d’API ou travaillé avec FastAPI, le modèle mental sera familier.

Conclusion

PydanticAI apporte une garantie pratique au développement d’agents : les sorties du modèle et les appels d’outils doivent respecter les types que vous avez déclarés. Cela réduit une catégorie fréquente de bugs en production et rend le flux de données plus prévisible.

Utilisez-le lorsque vous avez besoin de sorties structurées, de validation stricte et d’un code Python typé. Pour des workflows très ramifiés, un framework orienté graphe peut être plus adapté.

Quel que soit le framework choisi, testez aussi les API sous-jacentes. Simulez vos endpoints LLM et outils, affirmez leurs formes de réponse et gérez les clés par environnement dans Apidog afin que votre agent repose sur une base vérifiée.