Pydantic AI : des agents Python typés à intégrer en production

Informations vérifiées dans la documentation de l’éditeur et la licence du dépôt le 17 octobre 2026. Les critères de choix présentés ici sont la validation des sorties, l’accès aux services de l’application, la maîtrise du workflow et la reprise après incident, plutôt qu’un classement des performances.

Qu’est-ce que Pydantic AI ?

Pydantic AI est le SDK d’agents Python de l’équipe Pydantic. Il réunit un modèle, des instructions, des fonctions Python appelables et un type de sortie facultatif dans un Agent, l’objet que votre application exécute. Le modèle génère les réponses ; le SDK orchestre les échanges qui l’entourent. La présentation actuelle décrit un SDK plus large, mais ce noyau suffit pour comprendre son rôle dans une fonctionnalité produit.

Imaginez un collaborateur imprévisible auquel vous imposez le contrat d’une fonction. Votre application lui fournit le contexte et les opérations autorisées, puis exige un résultat composé de champs nommés. C’est utile, par exemple, lorsqu’une fonctionnalité de support doit produire une catégorie et une prochaine action qu’un programme Python classique pourra exploiter.

L’agent Pydantic AI : une configuration réutilisable

Un Agent contient la configuration d’une tâche. Une exécution correspond à une tentative précise de l’accomplir, avec un prompt et les dépendances fournies à ce moment-là. Vous pouvez appeler run_sync() depuis un script synchrone ou await agent.run() depuis le code asynchrone d’une application. Une fois l’exécution terminée, la valeur finale est accessible via .output. Ces interfaces sont décrites dans la documentation d’Agent.

Le typage remplit deux fonctions distinctes. Le typage statique aide l’éditeur ou le vérificateur de types à détecter les incohérences dans le code Python. La validation des sorties à l’exécution vérifie que les données renvoyées par le modèle respectent le schéma déclaré. Ni l’un ni l’autre ne lève l’ambiguïté d’une demande de support mal définie.

Les outils Pydantic AI : des fonctions reliées à votre application

Les outils sous forme de fonctions permettent au modèle de demander une opération que votre code sait effectuer, comme consulter un abonnement. Enregistrez une fonction qui utilise le contexte avec @agent.tool, ou employez @agent.tool_plain si elle n’en a pas besoin. Les annotations de type décrivent les arguments, tandis que les docstrings aident à expliquer l’outil au modèle. La documentation des outils détaille leur conversion en schémas d’outils.

L’injection de dépendances consiste à fournir à chaque exécution les services dont elle a besoin. Avec deps_type=CustomerContext, vous déclarez le type Python attendu ; avec deps=customer_context, vous transmettez l’instance à utiliser. L’outil reçoit un RunContext[CustomerContext] et accède aux dépendances via ctx.deps. Ce contexte peut contenir un client authentifié, une connexion à une base de données ou un client d’API. Le guide des dépendances précise que deps_type sert à la vérification des types, et non à la validation de l’objet de dépendances à l’exécution.

Pour un développeur SaaS, le bénéfice est concret : le serveur peut sélectionner le compte du client avant que le modèle ne demande à le consulter. Les contrôles d’autorisation doivent rester dans le code de consultation. Faire passer un client de base de données par un contexte typé ne limite pas les lignes auxquelles ce client peut accéder.

Sorties structurées de Pydantic AI : que vérifie la validation ?

output_type définit le résultat que votre application attend. Fournissez un BaseModel Pydantic, une classe Python dont les champs sont typés : Pydantic AI en déduit un schéma et valide les données générées. La documentation des sorties prévoit aussi d’autres types, dont les dataclasses, les listes et les unions.

Les trois modes de sortie modifient la façon de demander ces données au modèle :

Il s’agit des trois modes de sortie documentés du SDK, pas de trois niveaux de précision. Choisissez un mécanisme pris en charge par votre modèle, puis évaluez le résultat sur votre tâche.

Un échec de validation peut être renvoyé au modèle pour qu’il fasse une nouvelle tentative. Le nombre de tentatives est limité ; une fois les tentatives de sortie épuisées, une exception UnexpectedModelBehavior peut être levée. Votre application doit prévoir une issue à cet échec, par exemple demander les informations manquantes ou transmettre la demande à une personne. Consultez le fonctionnement des nouvelles tentatives.

Tutoriel Pydantic AI : créer un agent IA Python qui qualifie les demandes de support

Commencez par un objet de décision en lecture seule avant d’autoriser l’agent à modifier quoi que ce soit. Cet exemple reprend les usages documentés d’Agent, de RunContext et d’output_type pour une petite tâche de qualification des demandes de support.

Le guide d’installation actuel exige Python 3.11 ou une version ultérieure. Dans un environnement virtuel, installez la bibliothèque :

python -m pip install pydantic-ai

Définissez OPENAI_API_KEY dans votre environnement avec la clé d’un compte ayant accès au modèle. Enregistrez le code suivant dans triage.py, puis lancez python triage.py. L’identifiant du modèle reprend celui de la documentation actuelle d’Agent ; vous pouvez le remplacer par un modèle pris en charge auquel votre compte a accès.

from dataclasses import dataclass
from typing import Literal

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

@dataclass
class Customer:
    plan: str

class Triage(BaseModel):
    category: Literal['billing', 'technical']
    priority: Literal['normal', 'urgent']
    summary: str

agent = Agent(
    'openai:gpt-6.1-sol',
    deps_type=Customer,
    output_type=Triage,
    instructions=(
        'Triage the support message. Use customer_plan for context. '
        'Summarize the issue without inventing account facts.'
    ),
)

@agent.tool
def customer_plan(ctx: RunContext[Customer]) -> str:
    """Return the authenticated customer's plan."""
    return ctx.deps.plan

if __name__ == '__main__':
    result = agent.run_sync(
        'I was charged twice for my subscription.',
        deps=Customer(plan='business'),
    )
    print(result.output.model_dump())

Lorsque l’exécution réussit, result.output est un objet Triage. Sa catégorie et sa priorité doivent correspondre aux choix déclarés, et model_dump() convertit cet objet en dictionnaire. L’outil d’accès au contexte, le résultat typé et le rejet d’une catégorie invalide ont été vérifiés hors ligne avec TestModel. Les formulations générées et la qualité de la qualification doivent encore être évaluées sur vos propres cas.

Le contexte client n’est ici qu’un exemple. Dans un produit, construisez-le à partir de la requête authentifiée et des données de compte dont vous disposez. Définissez aussi ce qui rend un dossier urgent : le schéma énumère les libellés valides, mais ne contient aucune règle d’urgence. Cette règle métier manquante compte davantage que l’ajout d’un agent supplémentaire.

Modèles Pydantic AI : changer de fournisseur sans présumer de l’équivalence

Pydantic AI réduit le code d’intégration propre à chaque fournisseur, mais changer de modèle modifie toujours le comportement. De nombreux modes d’accès utilisent un identifiant <provider>:<model>. Certains nécessitent de fournir explicitement un modèle ou un client, les identifiants d’accès adaptés et des dépendances d’installation supplémentaires. Les fonctionnalités disponibles dépendent du modèle et de l’API choisis, comme le précise le répertoire des fournisseurs.

Ce répertoire comprend OpenAI, Anthropic, Google/Gemini, AWS Bedrock, Groq, Mistral, xAI et Ollama. Les autres modes d’accès documentés couvrent :

• Les services de modèles et d’inférence : Alibaba Cloud/Qwen, Cerebras, Cohere, Crusoe, DeepSeek, Fireworks AI, Heroku AI, Hugging Face, Meta, Moonshot AI/Kimi, Nebius AI Studio, OVHcloud AI Endpoints, SambaNova, Snowflake Cortex, Together AI et Z.AI.
• Les options cloud, passerelles et auto-hébergées : Google Cloud/Vertex AI, Microsoft Azure/Foundry, Pydantic AI Gateway, LiteLLM, OpenRouter, Vercel AI Gateway et vLLM.
• Les autres modes d’accès et les modèles de décision : GitHub Copilot, OpenAI Codex, OpenAI Decisions API, System One API et TypeSafe (Jev).

Ces noms désignent différentes façons d’accéder aux modèles, pas des ensembles de fonctionnalités interchangeables. Un modèle local peut utiliser les outils différemment d’un modèle de pointe hébergé ; une API compatible peut tout de même imposer d’autres restrictions sur les schémas.

Pour un fondateur, la portabilité offre une porte de sortie et la liberté d’expérimenter. Pour le développeur chargé de la mettre en œuvre, le test d’acceptation reste le même : le modèle de remplacement choisit-il les bons outils, respecte-t-il le schéma de sortie et prend-il des décisions acceptables sur les mêmes cas ? Conservez ces résultats avant de changer le modèle utilisé par défaut en production.

MCP et exécution durable : connecter les outils et conserver l’avancement

MCP relie un agent à des serveurs d’outils ; l’exécution durable aide une tâche à survivre à une interruption. Ces mécanismes répondent à des problèmes différents.

Le Model Context Protocol, ou MCP, standardise la manière dont les applications exposent des outils et du contexte aux clients d’IA. La fonctionnalité MCP de Pydantic AI accepte des URL de serveurs ainsi que des clients ou des ensembles d’outils, avec des options MCP natives des fournisseurs lorsqu’elles sont prises en charge. Elle permet de réutiliser un serveur d’outils au lieu de développer une intégration pour chaque agent. Elle ne détermine pas quels clients doivent être autorisés à utiliser les opérations de ce serveur.

L’exécution durable consiste à conserver l’avancement pour que le travail puisse reprendre après une panne, un redémarrage ou une longue attente. La documentation actuelle sur la durabilité cite 9 solutions :

• Maintenues conjointement avec les équipes des éditeurs : Temporal, DBOS, Prefect, Restate et AWS Lambda.
• Intégrations de SDK externes : Kitaru, Apache Airflow, Absurd et pgtask.

Un mécanisme de création de backends existe également pour d’autres moteurs. Choisissez une intégration documentée si un agent doit poursuivre son travail au-delà de la requête ou du processus qui l’a lancé. La présence de ces intégrations ne transforme pas un simple appel à Agent en déploiement durable.

Prenez une tâche de support qui prépare une recommandation de remboursement, attend une approbation, puis l’applique. Une exécution sauvegardée peut conserver le travail en attente, mais l’opération de paiement doit toujours être idempotente : répéter la requête ne doit pas déclencher un autre remboursement. Déterminez comment reconnaître une opération déjà effectuée et comment vérifier le résultat lorsqu’il est incertain. Cette responsabilité revient à l’application, en complément du moteur.

Pydantic AI et les évaluations : vérifier la décision derrière l’objet

Pydantic Evals vérifie que l’agent a accompli sa tâche de façon acceptable, au-delà de la possibilité d’analyser sa sortie. C’est un package d’évaluation distinct, piloté par le code, qui ne nécessite pas Pydantic AI. Vous définissez des cas et des évaluateurs, exécutez la tâche sur ces cas, puis examinez un rapport. La documentation décrit l’évaluation des sorties finales comme des trajectoires d’appels d’outils, c’est-à-dire la séquence des actions effectuées pendant une exécution.

Pour l’exemple de qualification, préparez des cas de double facturation, d’échec de connexion, de contexte de compte manquant et de message demandant à l’assistant d’ignorer ses instructions. Vérifiez la catégorie, la décision de transmettre le dossier et l’exécution effective de la consultation de compte requise. Prévoyez aussi des cas où la bonne réponse consiste à poser une question.

Pour l’équipe d’exploitation, une trace explique une exécution ; une évaluation mesure le comportement sur un ensemble de cas. Pydantic AI utilise OpenTelemetry, un standard de télémétrie applicative, et prend en charge d’autres backends d’observabilité grâce à son instrumentation. Lorsqu’un cas échoue, examinez la requête au modèle et les appels d’outils, puis conservez ce cas dans le jeu d’évaluation.

Le service facultatif Pydantic Logfire fournit des traces des agents, des modèles et des outils. Son offre Personal est gratuite et l’offre Team démarre à 49 USD/mois, les usages et sièges supplémentaires étant facturés séparément, selon sa page de tarifs.

Quel framework d’agent IA choisir, et quand privilégier Pydantic AI ?

Choisissez l’abstraction qui correspond à la difficulté réelle de votre fonctionnalité. Un développeur Python qui dispose déjà de modèles métier et de services a intérêt à retenir Pydantic AI parmi ses options si l’intégration des entrées, outils et sorties typés est le principal problème. Un fondateur technique doit se demander quel choix laisse le système le plus simple à exploiter, à expliquer et à maintenir dans l’entreprise.

Pydantic AI ou LangGraph ?

LangGraph constitue un meilleur point de départ si vous voulez concevoir explicitement le workflow qui entoure l’agent. Sa documentation met l’accent sur les agents avec état qui s’exécutent dans la durée, l’exécution durable et l’intervention humaine. Pensez à une application qui impose des étapes : recueillir les éléments nécessaires, obtenir une approbation, exécuter une action autorisée, puis vérifier et rapprocher le résultat obtenu de l’état attendu.

Pydantic AI est intéressant lorsqu’un agent typé constitue un composant d’un processus déjà contrôlé par votre application. Il peut lui aussi participer à des workflows durables : la persistance ne suffit donc pas à trancher. La question décisive est de savoir si vous voulez modéliser le processus métier autour de l’agent ou surtout configurer le comportement de l’agent lui-même. Avec LangGraph, la difficulté reste de concevoir le workflow et de gérer son état. Avec Pydantic AI, le contrat d’agent facilite le travail, mais ne conçoit pas l’ensemble du processus à votre place.

Pydantic AI ou LangChain ?

LangChain est pertinent si ses intégrations de modèles et d’outils et son architecture d’agents conviennent déjà à votre application. Les agents LangChain reposent sur LangGraph, comme l’indique la présentation de LangChain. Choisir son API d’agents de plus haut niveau conserve donc ce socle d’exécution.

Choisissez Pydantic AI pour un service Python si ses contrats de dépendances et de sortie correspondent à votre manière de coder. Conservez une fonctionnalité LangChain qui fonctionne, sauf si vous pouvez désigner une source précise de complexité que la migration éliminerait. L’abstraction de LangChain reste à comprendre lorsque le comportement traverse les couches agent et workflow ; changer de bibliothèque ne fait que déplacer ce travail. Le lien entre ces outils est détaillé dans LangChain vs LangGraph.

OpenAI Agents SDK ou simples appels d’API ?

OpenAI Agents SDK convient à une boucle d’agent gérée dans votre application, avec des outils, des transferts entre agents et des traces. Le SDK s’exécute dans votre application et prend en charge les sorties structurées. Ses interfaces de fournisseurs permettent aussi d’utiliser des modèles autres que ceux d’OpenAI. Présenter les sorties typées ou le choix du fournisseur comme des exclusivités de Pydantic AI serait donc inexact.

Choisissez ce SDK si son modèle d’agents et de transferts correspond à l’intégration OpenAI que vous comptez maintenir. Préférez Pydantic AI si son modèle de dépendances Python et sa configuration des fournisseurs sont mieux adaptés. Dans les deux cas, le déploiement, l’autorisation des outils et le bon fonctionnement de l’application restent de votre ressort.

Utilisez de simples appels d’API si la tâche se résume à une requête au modèle entourée d’un peu de code déterministe. Les API directes savent déjà renvoyer des sorties contraintes par un schéma. Un extracteur de reçus n’a pas besoin d’un framework d’agents au seul motif que son résultat est un objet Pydantic. La limite apparaît lorsque vous recréez régulièrement, d’une fonctionnalité à l’autre, les boucles d’appels d’outils, les nouvelles tentatives de validation et l’instrumentation.

Pour élargir la comparaison, consultez le guide des frameworks d’agents IA. Si vous hésitez encore entre un contrôle explicite du workflow et une répartition des rôles entre agents spécialisés, poursuivez avec LangGraph vs CrewAI.

Ce que les promesses autour des agents typés exagèrent

L’exagération consiste à présenter un agent typé comme un système de production automatiquement correct. La bibliothèque ne peut pas faire disparaître certaines limites :

• La sûreté du typage ne garantit pas l’exactitude des faits. Une réponse bien formée peut mal interpréter la demande de l’utilisateur. Déterminez ce qui doit être vérifié dans les données faisant autorité.
• La portabilité des modèles ne garantit pas une qualité équivalente. Une nouvelle configuration de fournisseur exige les mêmes évaluations sur la tâche qu’un nouveau prompt.
• La durabilité ne fournit pas un déploiement automatique. Choisissez et exploitez le moteur, le stockage et le mécanisme de reprise dont votre fonctionnalité a besoin.
• Une nouvelle tentative représente du travail supplémentaire. Chaque requête additionnelle au modèle augmente la latence et la consommation. Prévoyez explicitement ce que fait l’application lorsque les tentatives sont épuisées.

Passez à l’action si votre prochaine fonctionnalité Python a déjà besoin d’outils et de décisions structurées. Reportez une migration de framework si le système existant fonctionne et que le seul bénéfice annoncé est un code de démonstration plus élégant. Vous êtes peu concerné si la fonctionnalité se limite à un appel d’extraction simple, avec une validation et une gestion des erreurs adaptées.

Questions fréquentes sur Pydantic AI

Que mettre en production la semaine prochaine ?

Fixez des critères d’acceptation clairs à une petite fonctionnalité en lecture seule avant d’élargir son autonomie. Pour un produit de support, commencez par l’objet de qualification de l’exemple et gardez l’action finale sur le compte dans le code classique de l’application.

Pour des conseils pratiques sur la création de fonctionnalités IA, abonnez-vous à la newsletter.