Si alguna vez has implementado una función LLM y la has visto devolver JSON malformado en producción, PydanticAI está diseñado para ti. Es el framework de agentes de Python del equipo detrás de Pydantic, y sitúa las salidas validadas y seguras en cuanto a tipos en el centro del desarrollo de agentes. Esta guía explica qué es PydanticAI, por qué la seguridad de tipos es importante para los agentes, los conceptos fundamentales que realmente utilizarás y cómo se compara con otros frameworks de Python como LangGraph.
Qué es PydanticAI
PydanticAI es un framework de agentes de código abierto, agnóstico al proveedor, para Python. Es mantenido por el mismo equipo que desarrolla Pydantic Validation y Pydantic Logfire, por lo que hereda una sólida base de validación y un objetivo de diseño claro: aportar "esa sensación de FastAPI" a la construcción de agentes.
En términos sencillos, describes lo que tu agente debe hacer, qué herramientas puede llamar y qué forma debe tener su salida. PydanticAI gestiona las llamadas al modelo, valida todo contra tus modelos Pydantic y reintenta cuando el modelo devuelve algo que no encaja.
El proyecto alcanzó una versión estable v2.0.0 el 23 de junio de 2026, después de una serie de versiones beta. La V2 se inclina por un diseño "harness-first" donde las herramientas, los ganchos (hooks), las instrucciones y la configuración del modelo de un agente se componen como unidades reutilizables. Puedes instalarlo con pip install pydantic-ai o uv add pydantic-ai.
Por qué la seguridad de tipos es importante para los agentes
Los LLM no son deterministas. Haz la misma pregunta dos veces y puedes obtener dos formas de respuesta diferentes. Eso está bien para un cuadro de chat, pero se rompe en el momento en que conectas la salida del modelo a código real: una escritura en la base de datos, una llamada a la API, un cálculo de facturación.
La mayoría de los errores de los agentes provienen de esta brecha. El modelo "mayormente" devuelve JSON válido, tu analizador funciona en las pruebas, luego una respuesta de producción elimina un campo o envuelve la respuesta en prosa y tu pipeline falla. Terminas escribiendo análisis defensivos, limpieza con expresiones regulares y bucles de reintento a mano.
PydanticAI cierra la brecha al hacer que el contrato de salida forme parte del framework. Defines un modelo Pydantic, lo pasas como tipo de salida, y el framework garantiza que el valor que recibes coincide con ese modelo. Si el modelo devuelve algo inválido, PydanticAI envía el error de validación de vuelta al LLM y le pide que lo intente de nuevo. Tu código posterior recibe objetos tipados, no cadenas "con esperanza".
Esa misma idea se extiende a los argumentos de las herramientas. Cuando el modelo llama a una de tus herramientas, PydanticAI valida los argumentos contra las sugerencias de tipo de tu función antes de que la función se ejecute. Los argumentos incorrectos nunca llegan a tu lógica de negocio.
Conceptos fundamentales
PydanticAI mantiene su superficie pequeña. Cinco ideas cubren la mayor parte de lo que construirás.
Agentes
La clase Agent es el punto de entrada principal. Creas uno con un identificador de modelo e instrucciones opcionales. La clase es genérica sobre dos parámetros de tipo: el tipo de dependencias y el tipo de salida, que es lo que le da a tu editor y verificador de tipos una visibilidad real de tu agente.
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)
Esa cadena de modelo es todo lo que cambias para cambiar de proveedor, lo que mantiene tu código portable.
Salidas tipadas
Pasa un modelo Pydantic como output_type y el resultado del agente se valida contra él. Obtienes un objeto tipado de vuelta, y tu IDE conoce cada campo. Aquí tienes un esquema de salida estructurada:
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) # an int, validated, not a guess
Si el modelo devuelve una prioridad como texto o omite el resumen, la validación falla y el framework vuelve a solicitar. Nunca analizas la respuesta cruda por ti mismo.
Herramientas
Las herramientas permiten que el modelo interactúe con el exterior: consultar una base de datos, llamar a una API REST, ejecutar un cálculo. Registras una herramienta con el decorador @agent.tool. PydanticAI lee las sugerencias de tipo y la docstring de la función para construir el esquema que el modelo ve, luego valida cada llamada contra él.
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:
"""Return the current balance for an account."""
# ctx.deps holds your injected dependency
return await lookup_balance(ctx.deps, account_id)
El modelo decide cuándo llamar a la herramienta. Tu función solo se ejecuta con argumentos que ya pasaron la validación.
Dependencias
Los agentes reales necesitan contexto: una conexión a la base de datos, un cliente HTTP, el usuario actual, una clave API. PydanticAI maneja esto con inyección de dependencias. Declaras un deps_type en el agente, luego lo lees a través de RunContext dentro de las herramientas e instrucciones dinámicas. Toda la cadena se mantiene segura en cuanto a tipos, y las pruebas son más fáciles porque puedes intercambiar dependencias reales por simulacros.
Proveedores agnósticos al modelo y streaming
PydanticAI soporta una larga lista de proveedores: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, además de opciones en la nube como Azure AI Foundry y Amazon Bedrock y modelos autoalojados. Cambiar suele ser un cambio de una sola línea en la cadena del modelo.
También transmite la salida estructurada con validación aplicada a medida que llegan los datos, por lo que puedes renderizar resultados parciales sin renunciar a las garantías de tipo. Y como el equipo también construye Pydantic Logfire, la observabilidad está incorporada: seguimiento, depuración y control de costos para cada ejecución.
Cómo se compara PydanticAI con otros frameworks de agentes de Python
No existe un único framework "mejor". Optimizan para cosas diferentes. Aquí tienes una lectura honesta sobre dónde encaja PydanticAI.
| Framework | Punto fuerte principal | Mejor cuando necesitas |
|---|---|---|
| PydanticAI | Salidas y argumentos de herramientas validados y seguros en cuanto a tipos | Fiabilidad en producción y flujo de datos tipados limpio |
| LangGraph | Grafos explícitos con estado y control de flujo | Workflows de larga duración, con ramificaciones y múltiples pasos |
| Google ADK | Orquestación multi-agente en el ecosistema de Google | Integración profunda con Gemini y Vertex AI |
| OpenAI Agents SDK | Integración estrecha con OpenAI y traspasos | Un stack "OpenAI-first" y configuración rápida |
La ventaja de PydanticAI es la capa de validación. Si tu agente alimenta datos tipados a otros sistemas, la garantía de que la salida coincide con un modelo Pydantic elimina toda una clase de errores en tiempo de ejecución. LangGraph te ofrece un control más preciso sobre máquinas de estado y flujos complejos. El SDK de Agentes de OpenAI es una opción natural si ya estás comprometido con OpenAI y deseas características como traspasos de agentes y soporte de servidor MCP.
También puedes combinarlos. PydanticAI funciona bien como la capa de salida tipada dentro de una orquestación más grande.
Cuándo usar PydanticAI
Considera PydanticAI cuando:
- La salida de tu agente se envía a código, no solo a una ventana de chat, y la forma debe ser correcta.
- Quieres que tu verificador de tipos e IDE entiendan tu agente de principio a fin.
- Ya usas Pydantic en tu código base, por lo que las definiciones de modelos se sentirán nativas.
- Necesitas flexibilidad de proveedor y no quieres reescribir tu agente para cambiar de modelo.
- La observabilidad importa y el rastreo incorporado de Logfire es atractivo.
Busca otras opciones cuando necesites una orquestación pesada basada en grafos con ramificaciones complejas, donde un framework de máquina de estados te da un control más directo.
Pruebas y simulación de las APIs detrás de tu agente
Un agente de PydanticAI es tan fiable como las APIs de las que depende. Cada ejecución llama a un proveedor LLM, y la mayoría de los agentes útiles también llaman a tus propios endpoints REST o herramientas de terceros. Esas llamadas son donde se cuelan comportamientos inestables, costos sorpresa y desajustes de forma. PydanticAI valida la salida del modelo, pero no puede validar que la API de la herramienta aguas arriba a la que llamas devuelva lo que esperas.
Aquí es donde encaja Apidog, y es un trabajo diferente al del framework. Apidog es una plataforma de API donde pruebas y simulas las APIs subyacentes con las que se comunica tu agente.
Algunos usos concretos:
- Simula el LLM o un endpoint de herramienta. Durante el desarrollo, apunta una herramienta a una API simulada que devuelve respuestas deterministas. Dejas de gastar tokens en cada ejecución de prueba y evitas los límites de tasa del proveedor mientras iteras.
- Verifica las formas de las respuestas. Antes de conectar un endpoint REST a una función
@agent.tool, usa aserciones de API para confirmar que la respuesta real coincide con la estructura que espera tu herramienta. Detecta un campo faltante en la capa de la API, no en lo profundo de la ejecución de un agente. - Gestiona claves por entorno. Mantén las claves de proveedor y las URL base en entornos Apidog separados para que las ejecuciones locales, de staging y de CI apunten a los objetivos correctos sin cambios en el código.
- Verifica directamente el endpoint del LLM. Si llamas a un proveedor a través de HTTP, puedes probar la API de ChatGPT con Apidog para confirmar la autenticación, el streaming y los formatos de llamada a herramientas antes de que tu agente dependa de ellos.
Apidog no construye ni orquesta agentes, y no es una alternativa a PydanticAI. Es el banco de pruebas donde pruebas y simulas la superficie de la API en la que se ejecuta tu agente. Si quieres probarlo, descarga Apidog y simula primero uno de los endpoints de tu herramienta.
Preguntas frecuentes
¿Es PydanticAI gratuito y de código abierto?
Sí. PydanticAI es de código abierto y lo instalas desde PyPI con pip install pydantic-ai o uv add pydantic-ai. Seguirás pagando por el proveedor de LLM que utilices, ya que el framework llama a esas APIs en tu nombre. Para mantener bajos esos costos de proveedor mientras construyes, puedes simular las respuestas de la API durante las pruebas en lugar de consultar el modelo en vivo en cada ejecución.
¿Con qué modelos funciona PydanticAI?
Es agnóstico al proveedor. La documentación enumera OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral y Perplexity, además de opciones en la nube como Azure AI Foundry y Amazon Bedrock y modelos autoalojados. Seleccionas un modelo pasando una cadena como 'anthropic:claude-sonnet-4-6' o 'openai:gpt-4o' al constructor de Agent, y el cambio suele ser una modificación de una sola línea.
¿En qué se diferencia PydanticAI de LangChain o LangGraph?
PydanticAI se centra en la seguridad de tipos: salidas estructuradas validadas y argumentos de herramientas validados respaldados por modelos Pydantic. LangGraph se centra en grafos explícitos con estado para workflows de múltiples pasos y ramificaciones. Si tu prioridad son las formas de salida garantizadas y un flujo de datos tipado limpio, PydanticAI encaja bien. Si necesitas un control detallado sobre una máquina de estados compleja, un framework de grafos te ofrece más palancas directas.
¿Necesito conocer Pydantic para usarlo?
Ayuda, pero los conceptos básicos se aprenden rápidamente. Defines las formas de los datos como clases que heredan de BaseModel, y PydanticAI las utiliza para las salidas y los esquemas de herramientas. Si has utilizado Python para pruebas de API o has trabajado con FastAPI, el modelo mental te resultará familiar.
Conclusión
PydanticAI aporta algo práctico al desarrollo de agentes: la garantía de que la salida de tu modelo y las llamadas a herramientas coinciden con los tipos que declaraste. Esto elimina una fuente real de errores en producción y mantiene tu flujo de datos limpio. Elígelo cuando la fiabilidad y las salidas tipadas importen más que una orquestación de grafos pesada.
Elijas el framework que elijas, las APIs subyacentes a tu agente aún necesitan ser probadas. Simula tus endpoints de LLM y herramientas, verifica las formas de sus respuestas y gestiona las claves por entorno en Apidog para que tu agente se ejecute sobre una base que realmente hayas verificado.