Si alguna vez desplegaste una función con LLM y terminó devolviendo JSON malformado en producción, PydanticAI resuelve justo ese problema: convertir respuestas probabilísticas en objetos validados y seguros en cuanto a tipos. Es el framework de agentes de Python del equipo detrás de Pydantic y está pensado para construir agentes cuyas salidas, herramientas y dependencias puedan verificarse antes de llegar a tu lógica de negocio.
Qué es PydanticAI
PydanticAI es un framework de agentes de código abierto, agnóstico al proveedor, para Python. Lo mantiene el mismo equipo que desarrolla Pydantic Validation y Pydantic Logfire, así que su enfoque principal es claro: llevar la experiencia de tipos y validación de Pydantic al desarrollo de agentes.
En la práctica, defines:
- qué debe hacer el agente;
- qué modelo LLM debe usar;
- qué herramientas puede llamar;
- qué forma exacta debe tener la salida.
PydanticAI ejecuta el modelo, valida las respuestas contra tus modelos Pydantic y reintenta cuando el LLM devuelve algo que no encaja.
El proyecto alcanzó una versión estable v2.0.0 el 23 de junio de 2026, después de varias versiones beta. La V2 favorece un diseño harness-first, donde herramientas, hooks, instrucciones y configuración del modelo se componen como unidades reutilizables.
Instalación:
pip install pydantic-ai
O con uv:
uv add pydantic-ai
Por qué la seguridad de tipos importa en agentes LLM
Los LLM no son deterministas. Una misma instrucción puede devolver respuestas con estructuras distintas. Eso puede ser aceptable en un chat, pero se vuelve frágil cuando conectas la salida del modelo a código real:
- escrituras en base de datos;
- llamadas a APIs;
- cálculos de facturación;
- clasificación de tickets;
- flujos de aprobación;
- herramientas internas.
El fallo típico se ve así:
- El modelo “normalmente” devuelve JSON válido.
- Tu parser funciona en pruebas.
- En producción, el modelo omite un campo o envuelve el JSON en texto.
- Tu pipeline falla o procesa datos incompletos.
PydanticAI evita que tengas que escribir validaciones manuales, regex defensivas y bucles de reintento. Defines un modelo Pydantic como contrato de salida y el framework garantiza que el resultado final cumpla ese contrato.
Si el modelo devuelve algo inválido, PydanticAI devuelve el error de validación al LLM y le pide corregir la respuesta. Tu código recibe objetos tipados, no strings que “probablemente” contienen JSON.
La misma idea aplica a las herramientas. Cuando el modelo intenta llamar una función, PydanticAI valida sus argumentos contra las anotaciones de tipo antes de ejecutar tu lógica.
Conceptos fundamentales
PydanticAI tiene una superficie pequeña. Estos son los conceptos que más usarás.
1. Agentes
La clase Agent es el punto de entrada principal. Creas un agente con un identificador de modelo e instrucciones opcionales.
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 cadena del modelo define el proveedor y el modelo. Para cambiar de proveedor, normalmente cambias esa cadena:
agent = Agent('openai:gpt-4o')
Esto mantiene el código portable entre proveedores compatibles.
2. Salidas tipadas
El caso de uso más importante de PydanticAI es recibir una salida estructurada y validada.
Define primero el contrato de salida:
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.category)
print(result.output.priority)
print(result.output.summary)
result.output no es un string: es una instancia validada de SupportTicket.
Eso significa que puedes usarla directamente:
ticket = result.output
if ticket.priority >= 8:
escalate_ticket(ticket)
else:
create_standard_ticket(ticket)
Si el modelo devuelve priority como texto, omite summary o genera una estructura inválida, PydanticAI fuerza una corrección en lugar de dejar que el error llegue a tu aplicación.
3. Herramientas
Las herramientas permiten que el agente interactúe con sistemas externos:
- consultar una base de datos;
- llamar a una API REST;
- ejecutar un cálculo;
- buscar información interna;
- leer estado de usuario.
Registras herramientas con @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:
"""Return the current balance for an account."""
return await lookup_balance(ctx.deps, account_id)
PydanticAI usa:
- las anotaciones de tipo;
- la docstring;
- el contexto de ejecución;
para construir el esquema que el modelo puede invocar.
El modelo decide cuándo llamar la herramienta, pero tu función solo se ejecuta si los argumentos pasan validación.
4. Dependencias
Los agentes reales necesitan contexto externo:
- clientes HTTP;
- conexiones a base de datos;
- usuario actual;
- claves de API;
- configuración de entorno;
- repositorios internos.
PydanticAI maneja esto con inyección de dependencias mediante deps_type y RunContext.
Ejemplo con un cliente de API:
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
@dataclass
class AppDeps:
api_base_url: str
api_key: str
agent = Agent(
'openai:gpt-4o',
deps_type=AppDeps,
)
@agent.tool
async def get_order_status(ctx: RunContext[AppDeps], order_id: str) -> str:
"""Return the status of an order."""
return await fetch_order_status(
base_url=ctx.deps.api_base_url,
api_key=ctx.deps.api_key,
order_id=order_id,
)
deps = AppDeps(
api_base_url='https://api.example.com',
api_key='secret',
)
result = agent.run_sync(
'Check order ORD-123',
deps=deps,
)
Esto facilita pruebas porque puedes cambiar dependencias reales por mocks o servicios simulados.
5. Proveedores, streaming y observabilidad
PydanticAI soporta múltiples proveedores, incluidos OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, además de opciones como Azure AI Foundry, Amazon Bedrock y modelos autoalojados.
Cambiar de proveedor suele ser un cambio de una línea:
agent = Agent('anthropic:claude-sonnet-4-6')
agent = Agent('openai:gpt-4o')
También soporta streaming de salida estructurada con validación progresiva, lo que permite mostrar resultados parciales sin abandonar las garantías de tipo.
Como el equipo también construye Pydantic Logfire, la observabilidad está integrada para seguimiento, depuración y control de costos por ejecución.
Cómo se compara PydanticAI con otros frameworks de agentes de Python
No hay un único framework “mejor”. Cada uno optimiza para un problema distinto.
| 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 |
| 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 multiagente 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 centrado en OpenAI y configuración rápida |
La ventaja de PydanticAI es la validación. Si tu agente alimenta datos a otros sistemas, la garantía de que la salida coincide con un modelo Pydantic elimina una clase completa de errores en tiempo de ejecución.
LangGraph ofrece más control sobre flujos complejos, máquinas de estado y ramificaciones. El SDK de Agentes de OpenAI encaja mejor si tu stack ya está centrado en OpenAI y quieres características como traspasos de agentes y soporte de servidor MCP.
También puedes combinarlos. PydanticAI puede funcionar como capa de salida tipada dentro de una orquestación más grande.
Cuándo usar PydanticAI
Usa PydanticAI cuando:
- la salida del agente se envía a código, no solo a una ventana de chat;
- necesitas que la forma de la respuesta sea correcta;
- quieres que tu IDE y verificador de tipos entiendan el flujo completo;
- ya usas Pydantic o FastAPI;
- necesitas cambiar de proveedor sin reescribir el agente;
- quieres validación automática de argumentos de herramientas;
- la observabilidad con Logfire es relevante para tu equipo.
Considera otro enfoque si tu principal problema es modelar un workflow complejo con muchos estados, ramificaciones y transiciones explícitas. En ese caso, un framework basado en grafos puede darte más control 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 puede llamar a:
- un proveedor LLM;
- tus endpoints REST;
- herramientas internas;
- servicios de terceros;
- bases de datos;
- endpoints de autenticación.
PydanticAI valida la salida del modelo, pero no valida automáticamente que una API externa devuelva exactamente lo que tu herramienta espera.
Aquí es donde encaja Apidog. No reemplaza a PydanticAI ni orquesta agentes. Su función es ayudarte a probar, simular y verificar las APIs con las que tu agente se comunica.
Simula un endpoint de herramienta
Durante el desarrollo, puedes apuntar una herramienta a una API simulada que devuelva respuestas deterministas.
Esto ayuda a:
- evitar gastar tokens en cada prueba;
- reducir dependencia de servicios externos;
- probar errores de forma controlada;
- validar el comportamiento del agente en CI.
Verifica formas de respuesta
Antes de conectar un endpoint REST a una función @agent.tool, usa aserciones de API para confirmar que la respuesta real coincide con lo que espera tu herramienta.
Por ejemplo, si tu herramienta espera:
class OrderStatus(BaseModel):
order_id: str
status: str
estimated_delivery: str | None
deberías verificar que el endpoint devuelve esos campos antes de integrarlo con el agente.
Gestiona claves por entorno
Mantén URLs base y claves separadas para:
- local;
- staging;
- CI;
- producción.
Así puedes cambiar el destino de tus pruebas sin modificar el código del agente.
Prueba directamente endpoints LLM
Si llamas a un proveedor mediante HTTP, puedes probar la API de ChatGPT con Apidog para verificar:
- autenticación;
- formato del payload;
- streaming;
- errores;
- llamadas a herramientas.
Si quieres probarlo, descarga Apidog y empieza simulando uno de los endpoints que tu agente llama como herramienta.
Preguntas frecuentes
¿PydanticAI es gratuito y de código abierto?
Sí. PydanticAI es de código abierto y se instala desde PyPI:
pip install pydantic-ai
O con uv:
uv add pydantic-ai
Seguirás pagando por el proveedor LLM que utilices, porque el framework llama a esas APIs en tu nombre. Para reducir costos durante el desarrollo, puedes simular respuestas de API en lugar de consultar el modelo real 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 Azure AI Foundry, Amazon Bedrock y modelos autoalojados.
Seleccionas el modelo pasando una cadena al constructor de Agent:
agent = Agent('anthropic:claude-sonnet-4-6')
O:
agent = Agent('openai:gpt-4o')
¿En qué se diferencia PydanticAI de LangChain o LangGraph?
PydanticAI se centra en seguridad de tipos: salidas estructuradas validadas y argumentos de herramientas validados con modelos Pydantic.
LangGraph se centra en grafos explícitos con estado para workflows de varios pasos y ramificaciones.
Si tu prioridad es garantizar formas de salida y mantener un flujo de datos tipado, PydanticAI encaja bien. Si necesitas controlar una máquina de estados compleja, un framework de grafos puede darte más herramientas.
¿Necesito conocer Pydantic para usarlo?
Ayuda, pero no es obligatorio. El concepto principal es simple: defines estructuras de datos como clases que heredan de BaseModel.
from pydantic import BaseModel
class Product(BaseModel):
name: str
price: float
in_stock: bool
PydanticAI usa esas clases para validar salidas y esquemas de herramientas. Si has usado Python para pruebas de API o FastAPI, el modelo mental te resultará familiar.
Conclusión
PydanticAI aporta una mejora práctica al desarrollo de agentes: garantiza que la salida del modelo y las llamadas a herramientas coincidan con los tipos que declaraste.
Úsalo cuando necesites:
- salidas estructuradas;
- validación automática;
- menos parsing manual;
- herramientas tipadas;
- flexibilidad de proveedor;
- código más seguro para producción.
Elijas el framework que elijas, las APIs detrás de tu agente también deben probarse. Simula endpoints de LLM y herramientas, verifica formas de respuesta y gestiona claves por entorno en Apidog para ejecutar tus agentes sobre una base que ya hayas validado.
Top comments (0)