Pydantic AI es el framework de agentes creado por el equipo de Pydantic, la misma biblioteca de validación que usan por dentro el SDK de OpenAI, el de Anthropic y LangChain. Su idea es sencilla y potente: construyes agentes en Python donde cada salida del modelo se valida contra un tipo que tú declaras, de modo que el error deja de aparecer en producción y salta mientras escribes el código. En esta guía verás qué es Pydantic AI, cómo funcionan sus salidas estructuradas, cómo darle herramientas y dependencias, un agente de ejemplo completo y en qué se diferencia de LangChain. La misma explicación está disponible en inglés.

Puntos clave

  • Pydantic AI es un framework de agentes de código abierto (licencia MIT) construido sobre el sistema de tipos de Pydantic; supera las 18 600 estrellas en GitHub y va por la versión v2.11.0, publicada en julio de 2026.
  • Lo mantiene el equipo de Pydantic, la biblioteca de validación que ya usan por dentro el SDK de OpenAI, el de Anthropic, Google ADK y LangChain, así que hereda un motor de validación muy probado.
  • Su rasgo distintivo son las salidas estructuradas tipadas: defines la respuesta como un modelo Pydantic (output_type) y el agente garantiza esa estructura, reintentando si el modelo se sale del formato.
  • Es agnóstico del proveedor: funciona con más de veinte proveedores de modelos (OpenAI, Anthropic, Gemini, DeepSeek, Mistral, Groq, Bedrock, Ollama y otros) con la misma API.
  • Requiere Python 3.10 o superior, se instala con pip y se integra con Pydantic Logfire para observabilidad basada en OpenTelemetry.

¿Qué es Pydantic AI?

Pydantic AI es, en palabras de su propia documentación, el «framework de agentes de IA generativa, a la manera de Pydantic». Nació de un equipo con mucha credibilidad: los mismos que crearon Pydantic[1], la biblioteca de validación de datos más usada del ecosistema Python, presente por dentro del SDK de OpenAI, el de Anthropic, Google ADK y LangChain. Con Pydantic AI llevan esa fiabilidad al mundo de los agentes de IA.

El proyecto es software libre bajo licencia MIT y ha tenido una acogida notable: reúne más de 18 600 estrellas en GitHub y va por la versión v2.11.0, publicada en julio de 2026. Necesita Python 3.10 o superior y se instala con una sola orden:

pip install pydantic-ai

# Instalación mínima: solo con el proveedor que vayas a usar
pip install "pydantic-ai-slim[openai]"

La promesa central es la seguridad de tipos. La documentación oficial lo resume así: «traslada clases enteras de errores del tiempo de ejecución al momento de escribir el código, para acercarse a esa sensación de Rust de "si compila, funciona"». En la práctica eso significa que tu editor y el verificador de tipos entienden qué devuelve cada agente, y que un fallo de formato aparece antes de desplegar, no cuando ya está en manos de tus usuarios.

Salidas estructuradas y validación con tipos

Aquí está el corazón de Pydantic AI. En lugar de recibir texto suelto del modelo y parsearlo a mano, declaras la respuesta que esperas como un modelo Pydantic y se lo pasas al agente en el parámetro output_type. El agente instruye al modelo para que produzca esa forma, valida la respuesta contra el esquema y, si algo no encaja, reintenta automáticamente hasta obtener un objeto válido.

from pydantic import BaseModel
from pydantic_ai import Agent

class Factura(BaseModel):
    numero: str
    total: float
    moneda: str

agente = Agent('anthropic:claude-sonnet-4-5', output_type=Factura)
resultado = agente.run_sync('Extrae los datos de: factura F-2026-014 por 149,90 EUR')

print(resultado.output.total)   # 149.9, ya validado como float
print(resultado.output.moneda)  # EUR

El objeto resultado.output no es una cadena de texto que haya que interpretar: es una instancia de Factura con sus campos ya validados y con el tipo correcto. Tu IDE autocompleta resultado.output.total y sabe que es un float. Si el modelo devolviera «ciento cuarenta y nueve con noventa» en vez de un número, la validación fallaría y Pydantic AI pediría al modelo que corrija, en lugar de propagar un dato roto por tu aplicación.

Herramientas y dependencias

Un agente útil necesita actuar sobre el mundo: consultar una base de datos, llamar a una API o leer un archivo. En Pydantic AI eso se hace con herramientas, funciones de Python que decoras con @agente.tool y que el modelo puede invocar cuando las necesita. Y para pasarles recursos externos (una conexión a base de datos, el identificador del usuario, una clave) se usa la inyección de dependencias con deps_type y el objeto RunContext.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Contexto:
    cliente_id: int

agente = Agent('openai:gpt-4o', deps_type=Contexto)

@agente.tool
async def saldo_pendiente(ctx: RunContext[Contexto]) -> float:
    """Devuelve el saldo pendiente del cliente actual."""
    return consultar_saldo(ctx.deps.cliente_id)

El modelo decide cuándo llamar a saldo_pendiente, pero los datos sensibles (aquí cliente_id) los inyectas tú desde fuera y viajan por ctx.deps, no por el texto del prompt. Este patrón mantiene el código desacoplado y fácil de probar: en las pruebas puedes inyectar un contexto falso y comprobar el agente sin tocar la base de datos real. Es el mismo enfoque de inyección de dependencias que verías en un framework web maduro, aplicado a los agentes.

Un agente de ejemplo

Con las tres piezas juntas (modelo, salida tipada e instrucciones) un agente completo cabe en unas pocas líneas. El siguiente ejemplo pide un parte meteorológico y obtiene un objeto validado, no un texto libre:

from pydantic import BaseModel
from pydantic_ai import Agent

class Parte(BaseModel):
    ciudad: str
    temperatura_c: float
    resumen: str

agente = Agent(
    'openai:gpt-4o',
    output_type=Parte,
    instructions='Responde en español y con datos concretos.',
)

resultado = agente.run_sync('Dame el parte de hoy en Sevilla')
print(resultado.output.ciudad)         # Sevilla
print(resultado.output.temperatura_c)  # p. ej. 34.0

Fíjate en el detalle: cambiar de proveedor es tan sencillo como sustituir la cadena 'openai:gpt-4o' por 'anthropic:claude-sonnet-4-5' o 'google:gemini-2.5-pro'. El resto del código no se toca, porque Pydantic AI abstrae la diferencia entre los más de veinte proveedores que soporta. Si quieres construir agentes más complejos con estado y ramas, la propia biblioteca incluye un sistema de grafos, un terreno parecido al que cubre LangGraph.

Pydantic AI frente a LangChain

La comparación es casi obligada porque Pydantic ya vive dentro de LangChain. La diferencia de filosofía es clara. LangChain es un ecosistema enorme y veterano, con integraciones para casi todo y un grafo de estados (LangGraph) muy capaz; a cambio, arrastra muchas capas de abstracción y una curva de aprendizaje empinada. Pydantic AI apuesta por lo contrario: una superficie pequeña, muy pythónica, donde los tipos son de primer nivel y el código se lee casi como Python normal.

Si tu prioridad es la fiabilidad de las salidas, el tipado estricto y un código limpio y fácil de probar, Pydantic AI encaja de maravilla. Si necesitas un catálogo inmenso de integraciones listas para usar o ya tienes una inversión grande en LangChain, ese ecosistema sigue siendo una opción sólida. No son excluyentes: puedes usar Pydantic AI para la parte del agente y apoyarte en otras bibliotecas para la orquestación, igual que combinarías el SDK de Anthropic con tus propias herramientas. La elección depende de si valoras más el alcance o la disciplina de tipos.

Preguntas frecuentes

¿Necesito saber Pydantic para usar Pydantic AI?

Ayuda mucho, pero no hace falta ser experto. Si sabes definir una clase que hereda de BaseModel con unos cuantos campos tipados, ya tienes lo esencial para declarar salidas estructuradas. El resto de conceptos (herramientas, dependencias, instrucciones) se aprenden sobre la marcha con los ejemplos de la documentación. Como Pydantic es la biblioteca de validación más extendida de Python, es muy probable que ya la hayas usado sin darte cuenta.

¿Con qué modelos funciona Pydantic AI?

Con más de veinte proveedores mediante la misma API: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Mistral, Cohere, Groq, Amazon Bedrock, OpenRouter y otros, además de modelos que ejecutes en tu propia máquina con Ollama. Cambiar de uno a otro es cuestión de editar la cadena de identificación del modelo, sin reescribir la lógica del agente.

¿Es Pydantic AI adecuado para producción?

Sí, es su objetivo declarado. Aporta validación estricta de entradas y salidas, ejecución duradera para sobrevivir a fallos en flujos largos, aprobación humana de herramientas sensibles e integración con Pydantic Logfire para observabilidad con OpenTelemetry. Al ir por la versión v2.11.0 y estar respaldado por el equipo de Pydantic, ofrece una base madura, aunque conviene fijar la versión exacta que uses porque el proyecto avanza deprisa.

Conclusión

Pydantic AI lleva la disciplina de tipos de Python al desarrollo de agentes: defines la salida que esperas como un modelo, el agente la valida por ti y los errores de formato saltan mientras escribes, no en producción. Con una API pequeña y pythónica, soporte para más de veinte proveedores e integración con Logfire, es una opción excelente cuando la fiabilidad importa más que el tamaño del ecosistema. El siguiente paso es instalarlo con pip install pydantic-ai, escribir tu primer agente con output_type y compararlo con LangGraph para decidir cuál encaja mejor en tu proyecto.

Fuentes: [1] Documentación oficial de Pydantic AI[2], [2] Pydantic AI en GitHub[3], [3] Paquete pydantic-ai en PyPI[4], [4] Qué es Pydantic AI en 2026, análisis de Future AGI[5].

Visitas: 0

Fuentes

  1. Pydantic
  2. Documentación oficial de Pydantic AI
  3. Pydantic AI en GitHub
  4. Paquete pydantic-ai en PyPI
  5. Qué es Pydantic AI en 2026, análisis de Future AGI

Ruta: Frameworks para construir agentes de IA