Pydantic AI: cómo crear agentes Python tipados sin perder control en producción

Pydantic AI no es otro wrapper bonito para prompts. Su valor está en obligarte a tratar un agente como software: contratos de salida, dependencias explícitas, herramientas validadas, límites de uso, trazas y evals.

Pydantic AI es un framework Python para construir aplicaciones y agentes de IA con el estilo mental de FastAPI: tipos, validación, inyección de dependencias, herramientas declarativas, salida estructurada, observabilidad y evals.

TL;DR

La keyword principal es Pydantic AI agentes; la intención de búsqueda en español es aprender cuándo usar Pydantic AI y cómo montar un agente Python de producción con output tipado, tools, límites de uso, MCP y trazas.

Mi postura: Pydantic AI tiene sentido cuando el agente va a tocar datos o decisiones reales. Si solo quieres un chat demo, cualquier wrapper sirve. Si necesitas que la salida sea validable, testeable y observable, aquí empieza a compensar.

Por qué Pydantic AI importa para devs Python

Una definición citable: Pydantic AI es un framework de agentes para Python que convierte prompts, herramientas, dependencias y resultados de modelos en contratos tipados que puedes validar, probar y observar como parte de una aplicación normal.

La mayoría de demos de agentes fallan por el mismo motivo: tratan el LLM como una caja mágica que devuelve texto. En producción eso no basta. Necesitas saber qué forma debe tener la respuesta, qué herramientas puede llamar, cuántas veces, con qué datos y bajo qué límites.

Pydantic AI ataca ese problema desde una idea muy pragmática: si ya usas Pydantic para validar entradas y salidas en APIs, usa el mismo músculo para validar decisiones generadas por modelos.

Recibe una lectura semanal de herramientas IA para devs

Si quieres seguir frameworks de agentes como Pydantic AI, OpenAI Agents SDK, Claude Agent SDK, MCP y evals sin leer veinte changelogs a la semana, DevAI Semanal te lo resume en un email de 5 minutos.

Suscribirme gratis

La arquitectura mínima de un agente serio

Un agente Pydantic AI razonable tiene cinco piezas. Primero, un Agent con instrucciones y modelo. Segundo, un output_type con un BaseModel que define qué debe devolver. Tercero, dependencias explícitas para pasar servicios, tenant, usuario o conexiones. Cuarto, tools con argumentos validados. Quinto, límites y observabilidad para no descubrir el coste en la factura.

La ventaja no es que el modelo sea más inteligente. La ventaja es que el contrato alrededor del modelo se vuelve más estrecho. Menos texto libre, menos estado implícito y menos magia escondida en el prompt.

La frontera sana: el LLM razona, pero tu aplicación define contratos, dependencias, tools permitidas, límites de uso y trazas revisables.

Primer ejemplo ejecutable: salida tipada

Este ejemplo no intenta ser sofisticado. La idea es mostrar el patrón: un BaseModel define la salida, el agente la valida y tu código consume result.output como objeto Python, no como JSON pegado con cinta.

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class ReviewDecision(BaseModel):
    verdict: str = Field(description="approve, request_changes or needs_human")
    risk: int = Field(ge=0, le=10)
    reasons: list[str]

agent = Agent(
    "openai:gpt-5.2",
    output_type=ReviewDecision,
    instructions=(
        "Eres un revisor senior. Devuelve una decision breve, "
        "un riesgo de 0 a 10 y razones accionables."
    ),
)

result = agent.run_sync(
    "El PR cambia autenticacion, no trae tests y toca sesiones."
)

decision = result.output
print(decision.verdict, decision.risk, decision.reasons)

Qué gana el output tipado

Ganas una frontera concreta entre IA y producto. Si el modelo responde con una forma inválida, no lo conviertes silenciosamente en estado de negocio. Lo validas, reintentas dentro del presupuesto o fallas de forma explícita.

Esto es especialmente importante en agentes que clasifican tickets, generan acciones, evalúan riesgos, enrutan incidencias, preparan PRs o deciden si una tarea necesita humano. En esos casos, texto bonito no es un contrato.

La documentación de Pydantic AI también remarca que el resultado conserva tipos genéricos, historial y uso de la ejecución. Esa metadata importa cuando quieres depurar por qué una decisión salió cara o mala.

Dependencias: no metas datos vivos en el prompt

El patrón correcto es pasar dependencias por deps, no pegar media base de datos en instrucciones. Las dependencias permiten que tools e instrucciones dinámicas accedan a servicios concretos con tipos claros: cliente HTTP, conexión a DB, tenant, usuario, feature flags o repositorio.

Esto reduce tres riesgos: fuga accidental de contexto, prompts imposibles de testear y herramientas que leen datos que no deberían. Si una tool necesita tenant_id, que venga de una dependencia controlada, no de un texto que el modelo puede reinterpretar.

Segundo ejemplo ejecutable: tool con deps y límite de uso

El siguiente patrón es el que usaría para un agente interno que consulta deuda técnica. La tool recibe argumentos validados, accede a servicios desde RunContext y la ejecución aplica límites para que una pregunta torpe no dispare diez llamadas innecesarias.

from dataclasses import dataclass

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext, UsageLimits

class Finding(BaseModel):
    file: str
    problem: str
    next_step: str

@dataclass
class RepoDeps:
    repo_name: str
    index: object

agent = Agent(
    "anthropic:claude-sonnet-4-6",
    deps_type=RepoDeps,
    output_type=list[Finding],
    instructions="Encuentra problemas concretos y devuelve acciones pequenas.",
)

@agent.tool
async def search_code(ctx: RunContext[RepoDeps], query: str) -> list[str]:
    """Busca fragmentos relevantes en el indice del repositorio."""
    return await ctx.deps.index.search(ctx.deps.repo_name, query, limit=5)

async def review(repo_index):
    deps = RepoDeps(repo_name="billing-api", index=repo_index)
    return await agent.run(
        "Busca riesgos en el modulo de invoices.",
        deps=deps,
        usage_limits=UsageLimits(request_limit=4, tool_calls_limit=3),
    )

Tools: la docstring también es interfaz

En Pydantic AI, las funciones registradas como tools exponen argumentos al modelo. Eso significa que nombres, tipos y docstrings son parte de la interfaz. Una tool vaga produce llamadas vagas.

Lo que conviene comprobar

Regla práctica: una tool debe hacer una cosa, aceptar pocos parámetros y devolver datos que no obliguen al modelo a inferir demasiado. Si devuelves una lista gigante de strings, has trasladado el problema al prompt. Si devuelves objetos pequeños y consistentes, reduces alucinaciones operativas.

También conviene separar tools de lectura y tools mutantes. Las primeras pueden tener permisos amplios dentro de un entorno controlado; las segundas necesitan scopes mínimos, logging y aprobación humana cuando tocan repos, tickets, cloud o datos de clientes.

MCP: úsalo para capacidades externas, no para saltarte diseño

Pydantic AI puede actuar como cliente MCP y conectar tools locales o remotas mediante MCPToolset o la capacidad MCP. Eso encaja muy bien con el ecosistema actual: servidores MCP para documentación, repos, observabilidad, datos internos o automatización.

Pero MCP no arregla una arquitectura mala. Si conectas diez servidores sin política, solo has dado más botones al modelo. La pregunta correcta es: qué tool necesita esta tarea, con qué transporte, con qué lifecycle, con qué credenciales y qué salida espero validar después.

Para equipos que ya usan MCP en Copilot, Claude Code o Cursor, Pydantic AI puede ser la capa Python donde conviertes esas capacidades en producto: controlas el cliente, los tipos, el flujo de ejecución y las pruebas.

Modelos y proveedores: no cases tu dominio con una API

Pydantic AI abstrae modelos y proveedores: puedes instanciar agentes con nombres tipo openai:gpt-5.2 o usar clases de modelo/proveedor más explícitas cuando necesitas Azure, OpenAI-compatible providers, LiteLLM, Ollama, GitHub Models u otro gateway.

Esto no significa que cambiar de modelo sea gratis. Cada proveedor tiene límites, perfiles, capacidades de herramientas y detalles de JSON schema. Pero sí te permite aislar el dominio de la aplicación del SDK de un proveedor concreto.

Mi recomendación: empieza con un proveedor explícito en configuración, registra métricas por modelo y guarda casos de evaluación. Cambiar de modelo sin evals es fe, no ingeniería.

Observabilidad y evals: el punto donde deja de ser demo

Pydantic AI se integra con Logfire y Pydantic Evals. Esa combinación importa porque los agentes fallan de formas no deterministas: hoy responden bien, mañana el modelo cambia, una tool tarda más, un prompt arrastra contexto viejo o un output validator empieza a reintentar demasiado.

Las evals no sustituyen tests unitarios. Sirven para otra capa: casos representativos, outputs esperados, evaluadores deterministas o LLM judges, métricas por experimento y comparación entre implementaciones.

Una batería mínima debería incluir: casos felices, inputs ambiguos, intentos de prompt injection, datos incompletos, límite de tools, errores de proveedor, salida inválida y ejemplos donde el agente debe decir necesita humano.

Durable execution: solo si el agente dura más que una request

Para tareas cortas, run_sync o run basta. Para flujos largos, multi-step o con reintentos de infraestructura, necesitas ejecución durable. La documentación de Pydantic AI cubre integraciones como Temporal, DBOS, Prefect y Restate.

No metas durable execution el primer día si no sabes todavía qué workflow quieres preservar. Primero define contrato de salida, tools, límites y evals. Después, si el agente tarda minutos, llama APIs externas o debe sobrevivir a caídas, añade durable execution.

Checklist de producción

• Define output_type para cualquier decisión que consuma tu aplicación.
• Pasa datos vivos por deps, no por prompts enormes.
• Separa tools de lectura y tools mutantes.
• Pon UsageLimits en runs que puedan llamar tools.
• Registra modelo, tokens, tool calls, latencia, reintentos y coste.
• Crea evals antes de cambiar de modelo o prompt principal.
• Conecta MCP solo para capacidades concretas y auditables.
• Haz que el agente pueda decir no sé o necesita humano.
• Versiona prompts, schemas y datasets de evaluación junto al código.

Errores que evitaría

El primero es vender Pydantic AI como garantía de verdad. Validar estructura no valida factualidad. Un BaseModel puede contener basura perfectamente tipada si no hay tools, fuentes o evaluadores.

Lo que conviene comprobar

El segundo es meter todos los datos en instrucciones. Si el prompt contiene secretos, datos de cliente o reglas efímeras, cada run se vuelve más caro, menos auditable y más difícil de limpiar.

El tercero es conectar MCP como catálogo infinito. Un agente con demasiadas tools se parece a un junior con permisos de producción y una wiki enorme: quizá acierte, pero no es un control.

El cuarto es no medir reintentos de validación. Si tu schema es demasiado estricto o ambiguo, el agente puede gastar tokens intentando satisfacer una forma que el prompt no explica bien.

Cuándo elegir Pydantic AI frente a OpenAI o Claude SDK

Elige Pydantic AI si tu equipo trabaja en Python, ya usa Pydantic/FastAPI, necesita salida tipada, quiere cambiar de proveedor con menos fricción y va a tratar agentes como componentes de backend.

Elige el SDK nativo de OpenAI o Anthropic si necesitas exprimir una capacidad específica del proveedor, si tu app depende de una superficie muy concreta o si prefieres controlar directamente cada request.

La decisión práctica no es framework contra framework. Es capa de dominio contra API de proveedor. Pydantic AI brilla cuando quieres una capa de dominio estable por encima de modelos que van a cambiar.

Plan de adopción de una semana

• Día 1: elige un caso acotado donde la salida pueda representarse como BaseModel: clasificación de tickets, revisión de riesgo, resumen técnico o extracción estructurada.
• Día 2: escribe el agente con una sola tool de lectura y UsageLimits bajos. No conectes todavía acciones mutantes.
• Día 3: añade diez casos de evaluación: cinco normales, tres ambiguos y dos hostiles.
• Día 4: instrumenta trazas y registra uso por ejecución. Mira reintentos, tool calls y latencia antes de optimizar prompts.
• Día 5: prueba un segundo modelo o gateway y compara evals. Si no puedes comparar, todavía no estás listo para producción. > ### Conclusión > > Pydantic AI es interesante porque baja los agentes al suelo: tipos, validación, dependencias, límites, trazas y evals. No promete que el modelo piense mejor. Promete que tu aplicación tenga mejores fronteras alrededor del modelo. > > Esa es exactamente la dirección correcta para equipos Python. Los agentes no deberían ser prompts sueltos con permisos. Deberían parecerse a servicios: contratos claros, herramientas pequeñas, límites explícitos, tests probabilísticos y logs que expliquen qué pasó cuando algo sale mal.

Preguntas frecuentes

¿Qué es Pydantic AI?

Pydantic AI es un framework Python para construir aplicaciones y agentes de IA con contratos tipados, herramientas validadas, dependencias explícitas, observabilidad y evals.

¿Pydantic AI reemplaza a OpenAI Agents SDK o Claude Agent SDK?

No necesariamente. Puede usarse como capa Python de dominio cuando quieres tipos, validación y portabilidad; los SDK nativos siguen siendo útiles para capacidades específicas del proveedor.

¿Pydantic AI soporta MCP?

Sí. Pydantic AI puede actuar como cliente MCP y conectar servidores locales o remotos para usar sus tools dentro de ejecuciones de agente.

¿La salida tipada evita alucinaciones?

No. Evita que la forma sea inválida, pero no garantiza que el contenido sea verdadero. Para factualidad necesitas fuentes, tools, validadores y evals.

¿Cuándo merece la pena usar Pydantic Evals?

Cuando vas a cambiar prompts, modelos, tools o workflows y necesitas comparar comportamiento con casos representativos, no solo confiar en una demo.

¿Pydantic AI sirve para producción?

Sí, si lo usas con límites de uso, observabilidad, evals, control de tools y revisión humana en acciones de riesgo. Sin eso, sigue siendo una demo con buen tipado.

Fuentes y referencias

• Pydantic AI overview
• Pydantic AI Agents
• Pydantic AI Output
• Pydantic AI model providers
• Pydantic AI MCP client
• Pydantic AI agent API
• Pydantic Evals overview
• Pydantic Evals Logfire integration
• Pydantic AI changelog and V2 upgrade guide
• pydantic/pydantic-ai GitHub repository

También te puede interesar

• OpenAI Agents SDK: MCP, guardrails y tracing
• Claude Agent SDK en Python y TypeScript
• LiteLLM Proxy: gateway IA, costes y modelos
• MCP outputSchema y structuredContent
• Métricas para agentes de código

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis