Pydantic AI: cómo construir agentes type-safe en Python

Si ya perdiste horas depurando un agente que recibía un campo de más o de menos, Pydantic AI ataca ese problema de raíz. Define la estructura esperada de las entradas y salidas del agente y valida automáticamente. Si algo no coincide, el error aparece temprano, no en medio de la ejecución.

El repositorio pydantic/pydantic-ai tiene más de 21 mil estrellas, licencia MIT y recibió actualización el 9 de noviembre de 2026. La comunidad y el ritmo de desarrollo indican madurez para uso en producción.

En este artículo vas a ver:

• Qué hace Pydantic AI y cómo organiza un agente
• Cómo instalar y crear el primer agente con tipado
• Cómo validar herramientas y resultados
• Cuándo usar Pydantic AI y cuándo tiene sentido un framework más pesado
• Límites y buenas prácticas

O que é o Pydantic AI e como funciona a tipagem

Un agente típico llama a un modelo de lenguaje, recibe texto e intenta interpretarlo. Sin tipado, esa interpretación es frágil. Pydantic AI invierte la lógica. Declaras un modelo Pydantic para el resultado esperado y el framework se asegura de que la respuesta del modelo se convierta y valide en ese formato.

Esto aplica también a las herramientas que usa el agente. Cada herramienta tiene parámetros tipados. Si el modelo intenta llamar a una herramienta con un argumento incorrecto, la validación falla de forma clara.

El enfoque recuerda a FastAPI, pero para agentes. Escribes menos código defensivo y más código de negocio. El tipado también mejora el autocompletado del editor y la documentación automática.

Como instalar o Pydantic AI e criar o primeiro agente

La instalación es simple. El paquete principal es pydantic-ai.

$ pip install pydantic-ai

Después, define el resultado esperado con un modelo Pydantic y crea el agente.

from pydantic import BaseModel
from pydantic_ai import Agent

class Resposta(BaseModel):
    resumo: str
    pontos: list[str]

agent = Agent(
    "openai:gpt-4o",
    result_type=Resposta,
)

result = agent.run_sync("Resuma as vantagens do Pydantic AI em 3 pontos.")
print(result.data.resumo)
print(result.data.pontos)

El método run_sync ejecuta de forma síncrona y devuelve un objeto con el campo data ya validado. Si la respuesta del modelo no encaja en el modelo Respuesta, el framework intenta corregirlo o lanza un error claro.

Puedes cambiar el proveedor alterando la cadena del modelo. Pydantic AI soporta OpenAI, Anthropic, Groq, Google y modelos locales vía Ollama. La documentación oficial lista los proveedores y sus configuraciones.

Como validar ferramentas e resultados

Las herramientas son funciones que el agente puede llamar. En Pydantic AI, decoras una función con @agent.tool y declaras los parámetros tipados. El framework genera el esquema para el modelo y valida la llamada.

from pydantic_ai import Agent, RunContext

agent = Agent("openai:gpt-4o")

@agent.tool
def busca_preco(ctx: RunContext, produto: str) -> float:
    # consulta o banco ou a API
    return 42.0

result = agent.run_sync("Qual o preço do produto X?")
print(result.data)

El parámetro ctx da acceso al contexto de ejecución, como dependencias inyectadas. Esto facilita las pruebas, porque puedes inyectar mocks en lugar de llamar a servicios reales.

La validación de resultados también ayuda en flujos multi-etapa. Si un agente necesita pasar datos al siguiente, el tipado garantiza que se respete el contrato. En equipos de agentes, esto reduce errores de integración.

Quando usar Pydantic AI e quando um framework mais pesado faz sentido

Pydantic AI es ligero y enfocado. No intenta ser un orquestrador completo con colas, memoria y dashboards. Si necesitas coordinación compleja de varios agentes, puedes combinar Pydantic AI con un orquestrador o usar un framework más completo.

Usa Pydantic AI cuando el problema principal es la confiabilidad de los datos y la claridad del código. Brilla en agentes que llaman herramientas, extraen información estructurada o clasifican contenido.

Si necesitas memoria persistente, mira también Mem0: cómo dar memoria persistente a agentes de IA. Si la tarea exige control de navegador, mira browser-use: cómo conectar agentes de IA al navegador.

Límites y buenas prácticas

La tipificación fuerte no resuelve todos los problemas. El modelo puede generar una respuesta válida en formato, pero semánticamente incorrecta. La validación garantiza la forma, no la verdad. Para datos críticos, agregue verificaciones de negocio.

Otro punto es la verbosidad. Declarar modelos para cada resultado agrega código. En prototipos rápidos, esto puede parecer excesivo. La ganancia aparece cuando el proyecto crece y necesita pruebas automatizadas.

Buenas prácticas que valen para cualquier framework de agentes:

• Defina modelos de resultado pequeños y enfocados
• Inyecte dependencias vía RunContext en lugar de globales
• Pruebe herramientas de forma aislada, sin llamar al modelo
• Monitoree tokens y latencia en producción

Si coordina varios agentes, cada uno en su papel y en su espacio aislado, la tipificación se vuelve contrato entre ellos. En bridgecode montas este squad y acompañas cada etapa, desde la planificación hasta la entrega.

Preguntas frecuentes sobre Pydantic AI

¿Es gratuito Pydantic AI?

Sí. Es open source con licencia MIT. El costo proviene del proveedor de modelo que elijas.

¿Necesito saber Pydantic para usar Pydantic AI?

Conocimiento básico de Pydantic ayuda, pero no es obligatorio. Los ejemplos de la documentación cubren lo esencial. El framework incentiva el uso de modelos para resultados.

¿Pydantic AI reemplaza a LangChain?

No. Resuelven problemas diferentes. LangChain orquesta cadenas y herramientas. Pydantic AI se enfoca en tipado y validación. Puedes usar ambos juntos.

¿Funciona con modelos locales?

Sí, siempre que el proveedor sea compatible. Ollama y vLLM funcionan. Verifica la versión soportada en la documentación.

¿Cómo probar un agente sin llamar al modelo?

Puedes inyectar dependencias vía RunContext y probar herramientas de forma aislada. La documentación muestra patrones de prueba con mocks.