Cómo construir agentes IA con PydanticAI: del prototipo a producción en Python

PydanticAI está disponible en PyPI como el paquete pydantic-ai y se instala con un solo comando. El paquete base incluye soporte nativo para Anthropic, OpenAI y Google Gemini sin dependencias adicionales.

pip install 'pydantic-ai>=2.2.0'

El concepto central de PydanticAI es el parámetro output_type del Agent. En vez de que el LLM retorne texto libre que debes parsear manualmente, defines un modelo Pydantic con los campos que necesitas. El framework construye el JSON Schema correspondiente, lo envía al LLM como restricción, valida la respuesta recibida y —si hay errores— reintenta antes de propagar el error. El resultado llega como instancia Python tipada, lista para usar directamente en tu lógica de negocio sin ninguna conversión adicional. Esta característica elimina una clase entera de errores de integración que ocurren cuando el LLM no respeta el formato esperado.

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class SolicitudSoporte(BaseModel):
    empresa: str = Field(description='Nombre de la empresa remitente')
    urgencia: str = Field(description='Nivel de urgencia: baja, media o alta')
    categoria: str = Field(description='Categoria del problema tecnico')
    resumen: str = Field(description='Resumen del problema en una oracion')
    requiere_escalamiento: bool

agente = Agent(
    'anthropic:claude-sonnet-4-6',
    output_type=SolicitudSoporte,
    instructions=(
        'Eres un agente de soporte B2B. '
        'Extrae los datos estructurados del correo recibido. '
        'El campo urgencia debe ser exactamente baja, media o alta.'
    )
)

Para ejecutar el agente usa run_sync() en código sincrónico o await agent.run() en código asíncrono. El atributo .output del resultado contiene el objeto Pydantic validado, listo para insertar en una base de datos o pasarlo a otro proceso de tu flujo.

correo = (
    'Hola, llevamos 3 horas sin acceso al sistema de facturacion. '
    'Esto nos impide emitir boletas. Necesitamos solucion urgente.'
)

resultado = agente.run_sync(correo)
solicitud = resultado.output

print(solicitud.urgencia)               # 'alta'
print(solicitud.requiere_escalamiento)  # True
print(solicitud.categoria)              # 'acceso al sistema'

El siguiente agente integra un modelo de salida Pydantic, dependencias tipadas y una herramienta de enriquecimiento en menos de 70 líneas. Procesa correos de soporte B2B, extrae datos estructurados y verifica automáticamente si el cliente tiene contrato vigente antes de registrar el ticket. Es el patrón que Cognitiva aplica en integraciones con sistemas de CRM y soporte de empresas chilenas que manejan volúmenes medios de solicitudes entrantes.

import os
from dataclasses import dataclass
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext, ModelRetry

# Modelo de salida tipado
class TicketSoporte(BaseModel):
    empresa: str = Field(description='Nombre de la empresa')
    rut: str = Field(default='', description='RUT de la empresa si se menciona')
    urgencia: str = Field(description='baja, media o alta')
    categoria: str = Field(description='Categoria principal del problema')
    resumen: str = Field(description='Descripcion del problema en una oracion')
    requiere_escalamiento: bool

# Dependencias tipadas
@dataclass
class DepsSoporte:
    base_clientes: dict
    umbral_escalamiento: int = 2

# Agente con output_type y deps_type
agente_soporte = Agent(
    'anthropic:claude-sonnet-4-6',
    output_type=TicketSoporte,
    deps_type=DepsSoporte,
    retries=2,
    instructions=(
        'Eres un agente de soporte B2B de primer nivel. '
        'Extrae datos estructurados del correo. '
        'Verifica siempre el contrato del cliente si mencionan su RUT.'
    )
)

@agente_soporte.tool
async def verificar_cliente(
    ctx: RunContext[DepsSoporte],
    rut: str
) -> dict:
    'Verifica el contrato vigente del cliente por RUT (formato XX.XXX.XXX-X).'
    cliente = ctx.deps.base_clientes.get(rut)
    if not cliente:
        raise ModelRetry('RUT no encontrado. Solicita confirmacion del RUT al remitente.')
    tickets = cliente.get('tickets_abiertos', 0)
    return {
        'nombre': cliente['nombre'],
        'plan': cliente['plan'],
        'escalar': tickets >= ctx.deps.umbral_escalamiento
    }

Para ejecutar el agente, instancia las dependencias con los datos del entorno y llama a run() con el texto del correo. El objeto de salida estará validado por Pydantic antes de que lo recibas:

import asyncio

clientes = {
    '76.123.456-7': {
        'nombre': 'Acme SpA',
        'plan': 'empresarial',
        'tickets_abiertos': 3
    }
}

deps = DepsSoporte(base_clientes=clientes, umbral_escalamiento=2)

correo = (
    'Hola, soy de Acme SpA, RUT 76.123.456-7. '
    'Llevamos 3 horas sin acceso al sistema de facturacion. '
    'Necesitamos solucion urgente.'
)

async def main():
    resultado = await agente_soporte.run(correo, deps=deps)
    ticket = resultado.output
    print(ticket.empresa)                # 'Acme SpA'
    print(ticket.urgencia)               # 'alta'
    print(ticket.requiere_escalamiento)  # True

asyncio.run(main())

La pregunta más frecuente al evaluar PydanticAI es cuándo usarlo en vez de LangChain. Son herramientas con fortalezas distintas, no rivales directos. La elección depende del tipo de flujo y del perfil del equipo que lo mantiene.

PydanticAI es la elección natural cuando el agente debe retornar datos estructurados —formularios, tickets, extracciones, clasificaciones—, cuando el equipo ya trabaja con Pydantic en FastAPI, o cuando la validación de schema en producción es un requisito no negociable. LangChain tiene mayor ecosistema de integraciones listas para usar y es más maduro para flujos conversacionales con memoria de largo plazo o cadenas de múltiples modelos en secuencia.

La buena noticia es que ambos frameworks pueden coexistir sin conflictos en el mismo proyecto. PydanticAI maneja la capa de extracción y validación estructurada; LangChain puede ocuparse de los flujos conversacionales o las memorias vectoriales donde tiene más recorrido. No es una decisión excluyente.