PydanticAI

PydanticAI es un framework de agentes en Python creado por el equipo detrás de Pydantic, liderado por Samuel Colvin, el ingeniero que creó la biblioteca de validación Pydantic utilizada en todo el ecosistema de Python. Lanzado el 2 de diciembre de 2024, durante la semana de AWS re:Invent, alcanzó su versión estable 1.0 el 4 de septiembre de 2025, tras 15 millones de descargas. El framework cuenta con licencia MIT y es de uso gratuito. Su promesa principal: llevar la misma experiencia de desarrollo que convirtió a FastAPI en el framework web predeterminado de Python a la creación de agentes de IA, reemplazando el análisis JSON ad-hoc y la frágil ingeniería de prompts por contratos de tipos adecuados y salidas validadas.

PydanticAI es compatible de forma nativa con OpenAI, Anthropic, Google, xAI, Amazon Bedrock, Groq, Mistral, Ollama, Cohere, OpenRouter, Hugging Face y Cerebras. Sus características clave incluyen la validación de salidas estructuradas mediante modelos de Pydantic, un sistema de inyección de dependencias que utiliza RunContext para pasar conexiones de bases de datos y clientes de API de forma limpia a las herramientas, streaming con validación en tiempo real, compatibilidad con el Model Context Protocol (MCP), aprobación de herramientas con intervención humana (human-in-the-loop), arquitecturas multiagente y ejecución duradera con integración de Temporal. Su estrecha integración con Pydantic Logfire proporciona observabilidad basada en OpenTelemetry para rastrear las ejecuciones de los agentes, supervisar los costos de los tokens y depurar las llamadas a herramientas en producción. Para mayo de 2026, el repositorio cuenta con más de 16.800 estrellas en GitHub, más de 241 versiones y es utilizado en producción por equipos que desarrollan sobre Amazon Bedrock AgentCore.

Lo que PydanticAI hace realmente en mayo de 2026

PydanticAI se centra en una única clase Agent que envuelve un LLM, un conjunto de herramientas, un prompt del sistema y un esquema de salida estructurado. Cuando el agente se ejecuta, valida la salida del modelo contra un modelo de Pydantic en cada llamada, reintentando automáticamente con retroalimentación correctiva si la validación falla. Esto elimina la mayor categoría de fallos de producción en los sistemas de agentes: el LLM devolviendo datos malformados, faltantes o con tipos incorrectos que bloquean el código posterior.

El sistema de inyección de dependencias es el segundo gran diferenciador. En lugar de pasar la configuración a través del estado global o variables de entorno, las herramientas reciben un objeto tipado RunContext[Dependencies] en tiempo de ejecución. En la práctica, esto significa que una conexión a la base de datos, un cliente de API externo o el contexto del usuario se pueden inyectar limpiamente en el momento de la invocación del agente, lo que permite realizar pruebas unitarias de las herramientas sin llamadas en vivo al LLM. Este es un patrón de diseño tomado del sistema de dependencias de FastAPI y resuelve un verdadero problema al que se enfrentan los equipos cuando escalan bases de código de agentes más allá de un solo archivo. Escribir una prueba para una herramienta de agente ya no requiere una llamada en vivo al LLM o una base de datos real: se pasa un objeto de dependencia simulado (mock) a RunContext y se verifica el resultado.

El soporte de streaming incluye la validación en tiempo real de salidas parciales estructuradas, no solo el streaming de tokens. Esto es importante para los paneles de control y las interfaces de usuario en vivo que renderizan datos estructurados incrementales en lugar de texto sin formato: el framework valida cada fragmento de salida parcial a medida que llega, por lo que la aplicación nunca tiene que manejar un error de validación después de que se completa el flujo. Los flujos de trabajo basados en grafos, añadidos a través de la Graph API de PydanticAI, permiten modelar flujos agénticos complejos como máquinas de estado tipadas con transiciones entre estados verificadas por el IDE. La comunicación multiagente (transferencias de agente a agente), el soporte de servidor/cliente MCP y la ejecución duradera (agentes que pueden pausar, persistir el estado y reanudar tras una interrupción a través de Temporal) completan el conjunto de características. La hoja de ruta a principios de 2026 incluye el almacenamiento en caché de prompts, soporte para embeddings, salidas de gramática libre de contexto y un soporte ampliado para recursos MCP.

Un ejemplo concreto de cómo se desarrolla esto en la práctica: un sistema de clasificación de documentos legales construido sobre PydanticAI reportó un 94% de precisión en comparación con el 67% de la coincidencia de palabras clave. Un agente de atención al cliente de comercio electrónico resolvió automáticamente el 38% de los tickets entrantes con puntuaciones de satisfacción del 96%. Una integración de CRM inmobiliario procesó entre 40 y 60 notificaciones simultáneas en menos de 8 segundos. Estas no son afirmaciones de marketing de PydanticAI; son cifras publicadas por desarrolladores individuales que cambiaron al framework específicamente para escapar de los fallos de validación en herramientas anteriores.

"La cuarta vez que tuve que depurar un agente de LangChain que devolvía silenciosamente un JSON malformado y bloqueaba el pipeline de procesamiento de pedidos de un cliente, decidí que había terminado de parchear errores de tipo a medianoche." - jahanzaibai, DEV Community, 2025

Dónde se sitúa PydanticAI frente a LangChain y smolagents

PydanticAI vs. LangChain: LangChain tiene más de 96 mil estrellas en GitHub, una biblioteca de integraciones madura y años de implementaciones en producción a sus espaldas. No va a desaparecer. Pero el framework conlleva una importante complejidad acumulada: un tamaño de ~300 MB, múltiples patrones obsoletos (el antiguo AgentExecutor frente al más reciente LangGraph) y una arquitectura que separa ChatModel, plantillas de prompts, AgentExecutor y RunnableWithMessageHistory en capas distintas que deben conectarse entre sí. Para salidas estructuradas, LangChain no puede combinar with_structured_output() y herramientas adicionales en el mismo agente sin una solución alternativa personalizada como StructuredResponseTool. PydanticAI maneja esto de forma nativa. Para la inyección de dependencias, LangChain requiere crear subclases de BaseTool con una herramienta basada en clases; PydanticAI utiliza funciones simples con RunContext. La contrapartida es la amplitud del ecosistema: LangChain tiene conectores que PydanticAI simplemente aún no tiene.

PydanticAI vs. smolagents: smolagents de Hugging Face hace la apuesta arquitectónica opuesta. Todo su núcleo tiene aproximadamente 1.000 líneas de Python. Los agentes escriben y ejecutan código Python directamente (agentes de código) en lugar de llamar a herramientas predefinidas a través de esquemas JSON. Esto produce ganancias de eficiencia: smolagents afirma tener aproximadamente un 30% menos de llamadas al LLM en benchmarks complejos en comparación con el uso de herramientas de estilo JSON. El costo es que smolagents no tiene validación de salida estructurada incorporada, no tiene soporte asíncrono nativo y tiene un manejo de memoria limitado. PydanticAI impone la consistencia de los datos en cada límite; smolagents se optimiza para la velocidad de experimentación y un tamaño mínimo. Si estás creando prototipos en modelos alojados en Hugging Face y quieres algo funcionando en una hora, smolagents gana. Si estás construyendo un sistema de producción sensible al cumplimiento normativo donde cada salida debe validarse contra un esquema, PydanticAI gana.

Vale la pena señalar: DSPy ocupa un espacio adyacente diferente, optimizando programas de prompts algorítmicamente en lugar de proporcionar una capa de ejecución en tiempo de ejecución. LangGraph (parte del ecosistema LangChain) es el competidor más directo para la orquestación multiagente con estado. LiteLLM es complementario: una capa de enrutamiento independiente del proveedor sobre la que PydanticAI puede asentarse. CrewAI se dirige a sistemas multiagente basados en roles con una abstracción de nivel superior que intercambia control por simplicidad.

Cómo es la realidad del bucle del agente

Un flujo de trabajo típico de PydanticAI comienza definiendo un modelo de Pydantic para la salida esperada, creando un Agent con un prompt del sistema y un backend de modelo, y luego decorando funciones de Python como herramientas. La ejecución del agente devuelve un objeto de resultado tipado, no una cadena de texto. El IDE conoce la forma de cada argumento de herramienta y cada campo de salida antes de que se ejecute el código.

Para la observabilidad, llamar a logfire.configure() y logfire.instrument_pydantic_ai() activa el rastreo automático de cada llamada al LLM, cada invocación de herramienta y cada intento de validación. La base de OpenTelemetry significa que las trazas se pueden exportar a cualquier backend compatible, no solo a la plataforma comercial de Logfire. Esta es una distinción significativa: algunos equipos ya usan Datadog o Grafana y no quieren un segundo proveedor de observabilidad.

Los equipos de producción reportan resultados sólidos. Un desarrollador documentó un 94% de precisión en la clasificación de documentos legales (frente al 67% con coincidencia de palabras clave), un 38% de resolución automática de tickets de soporte de comercio electrónico con puntuaciones de satisfacción del 96%, y el procesamiento de 40 a 60 notificaciones simultáneas de CRM inmobiliario en menos de 8 segundos. Estos números provienen de equipos que cambiaron específicamente a PydanticAI para dejar de perseguir fallos de análisis JSON a las 2 de la madrugada.

"Después de pasar demasiado tiempo buscando errores de acceso a atributos en cadenas de agentes de tipado dinámico, esto importa más que cualquier número de benchmark." - jahanzaibai, DEV Community, 2025

Para quién está diseñado PydanticAI

La señal más clara: si has utilizado FastAPI y consideras el sistema de tipos de Python como infraestructura en lugar de documentación, PydanticAI te resultará inmediatamente familiar. El framework está dirigido a ingenieros que desean tratar el desarrollo de agentes como ingeniería de software normal, con pruebas unitarias, contratos tipados y soporte de IDE, en lugar de como la creación de prompts combinada con esperanza.

Encaja bien en equipos que ya utilizan Pydantic (que a estas alturas es la mayoría de los equipos de Python que trabajan con LLMs, dado que el SDK de OpenAI, el ADK de Google y el propio LangChain dependen de Pydantic para la validación). Adoptar PydanticAI es aditivo en lugar de una reescritura completa. También se adapta a dominios sensibles al cumplimiento normativo: finanzas, atención médica, legal, donde cada salida de IA debe ser auditable y estructurada. Thoughtworks lo movió a "Trial" (Prueba) en noviembre de 2025, su señal de que las empresas deberían usarlo en un proyecto real para desarrollar la comprensión de la categoría.

Es una opción razonable para los equipos que utilizan Amazon Bedrock AgentCore, donde PydanticAI es un framework compatible de primera parte. Se integra de forma natural junto a LiteLLM para los equipos que enrutan a través de múltiples proveedores.

Lo que PydanticAI no es

PydanticAI no es una navaja suiza agéntica de propósito general para cualquier stack. Algunos límites honestos:

Es solo para Python. No hay SDK para JavaScript, TypeScript u otros lenguajes. Si tu backend es Go, Java o Node.js, estás buscando un framework diferente.

Las entradas multimodales (imagen, audio, video) no son compatibles en el núcleo del agente a mediados de 2026. El framework procesa texto y datos estructurados; pasar una imagen a una herramienta requiere un manejo manual fuera de la capa de validación del framework.

Para la orquestación multiagente a gran escala con grafos de estado complejos, LangGraph tiene herramientas más maduras. La Graph API de PydanticAI es funcional pero más reciente, y los desarrolladores informan que la ergonomía para sistemas multiagente en expansión sigue siendo un trabajo en progreso.

Vale la pena señalar la preocupación por la dependencia de Logfire. La integración de observabilidad es excelente y genuinamente útil, pero el equipo de Pydantic tiene incentivos comerciales para dirigir a los usuarios hacia los niveles de pago de Logfire. El framework emite datos de OpenTelemetry, por lo que no estás estrictamente bloqueado, pero los equipos que ya tienen un stack de observabilidad (Datadog, Honeycomb, Grafana) deben validar la ruta de exportación antes de comprometerse.

También hay problemas conocidos que vale la pena tener en cuenta: una versión v1.30.0 introdujo accidentalmente una dependencia estricta de openai v2.8.0 que rompió proyectos existentes (problema de GitHub #3707), la lógica de reintento no siempre resuelve los fallos de validación como se espera (problema #739), y el soporte del modelo DeepSeek ha tenido errores de mapeo. Un equipo de desarrollo activo con 364 problemas abiertos significa que el framework es receptivo pero aún tiene asperezas.

Omite PydanticAI si: quieres algo funcionando en una tarde sin conocimientos de Pydantic, tu stack no es Python, necesitas herramientas maduras de agentes multimodales o necesitas la amplitud de las más de 300 integraciones de LangChain.