Pydantic AI: agentes de IA en Python con salidas validadas

Información verificada con la documentación del desarrollador y la licencia del repositorio el 17 de octubre de 2026. Los criterios de elección que siguen son la validación de las salidas, el acceso a los servicios de la aplicación, la responsabilidad sobre el flujo de trabajo y la recuperación ante fallos, sin establecer un ranking de rendimiento.

¿Qué es Pydantic AI?

Pydantic AI es el SDK de agentes para Python del equipo de Pydantic. Reúne un modelo, instrucciones, funciones de Python que se pueden invocar y un tipo de salida opcional en un Agent: el objeto que ejecuta tu aplicación. El modelo genera las respuestas; el SDK gestiona la interacción que lo rodea. La descripción general actual presenta un SDK más amplio, pero este es el núcleo que necesitas para desarrollar una funcionalidad de producto.

Es como darle a un colaborador impredecible el contrato de una función. Tu aplicación aporta el contexto y las operaciones permitidas, y exige a cambio un resultado con campos definidos. Esto resulta útil, por ejemplo, cuando una función de soporte debe devolver una categoría y un siguiente paso que el código Python convencional pueda procesar.

El agente de Pydantic AI como unidad reutilizable

Un Agent contiene la configuración de una tarea. Cada ejecución es un intento concreto de realizarla con un prompt y unas dependencias en tiempo de ejecución. Puedes llamar a run_sync() desde un script síncrono o a await agent.run() desde código asíncrono de la aplicación. Una vez completada la ejecución, el valor final está disponible en .output. Estas interfaces están documentadas en la API de Agent.

El tipado cumple dos funciones distintas. El tipado estático ayuda al editor o al verificador de tipos a detectar incompatibilidades en el código Python. La validación de la salida en tiempo de ejecución comprueba que los datos devueltos por el modelo se ajusten al esquema declarado. Ninguna de las dos cosas elimina la ambigüedad de una solicitud de soporte.

Herramientas de Pydantic AI: funciones con contexto de la aplicación

Las herramientas basadas en funciones permiten que el modelo solicite operaciones que tu código sabe realizar, como consultar una suscripción. Registra una función que necesite contexto con @agent.tool; si no lo necesita, usa @agent.tool_plain. Las anotaciones de tipo describen los argumentos y los docstrings ayudan a explicar la herramienta al modelo. La documentación sobre herramientas basadas en funciones detalla cómo se convierten en esquemas de herramientas.

La inyección de dependencias consiste en pasar a cada ejecución los servicios que necesita. Con deps_type=CustomerContext declaras el tipo de Python esperado; con deps=customer_context pasas la instancia concreta. La herramienta recibe RunContext[CustomerContext] y accede a esa instancia mediante ctx.deps. El contexto puede contener un cliente autenticado, una conexión a la base de datos o un cliente de API. La guía de dependencias aclara que deps_type sirve para la comprobación de tipos, no para validar el objeto de dependencias en tiempo de ejecución.

Para quien desarrolla un SaaS, la ventaja es concreta: el servidor puede elegir la cuenta del cliente antes de que el modelo solicite una consulta. Mantén la autorización en el código que realiza esa consulta. Pasar un cliente de base de datos a través de un contexto tipado no limita las filas que ese cliente puede leer.

Salidas estructuradas en Pydantic AI: ¿qué se valida?

output_type define el resultado que tu aplicación espera recibir. Proporciona un BaseModel de Pydantic, una clase de Python con campos tipados, y Pydantic AI generará un esquema y validará los datos producidos. La documentación de salidas también contempla otros tipos, como dataclasses, listas y uniones.

Los tres modos de salida cambian la forma de pedirle esos datos al modelo:

Son los tres modos de salida documentados del SDK, no tres niveles de precisión. Elige el mecanismo que admita tu modelo y evalúa después el resultado en tu tarea.

Si la validación falla, el error puede devolverse al modelo para que lo intente de nuevo. Los reintentos tienen un límite y, cuando se agotan los de salida, puede lanzarse UnexpectedModelBehavior. Tu aplicación necesita una vía para gestionar ese fallo, como pedir la información que falta o derivar la solicitud a una persona. Consulta el funcionamiento de los reintentos.

Tutorial de Pydantic AI: devuelve una decisión de soporte validada

Empieza con un objeto de decisión de solo lectura antes de permitir que el agente haga cambios. Este ejemplo adapta los patrones documentados de Agent, RunContext y output_type a una pequeña tarea de clasificación de solicitudes de soporte.

La guía de instalación actual exige Python 3.11 o posterior. Instala la biblioteca en un entorno virtual:

python -m pip install pydantic-ai

Configura OPENAI_API_KEY en el entorno con una clave de una cuenta que tenga acceso al modelo. Guarda el siguiente código como triage.py y ejecuta python triage.py. El identificador del modelo sigue la documentación actual de Agent; puedes sustituirlo por un modelo compatible al que tenga acceso tu cuenta.

from dataclasses import dataclass
from typing import Literal

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

@dataclass
class Customer:
    plan: str

class Triage(BaseModel):
    category: Literal['billing', 'technical']
    priority: Literal['normal', 'urgent']
    summary: str

agent = Agent(
    'openai:gpt-6.1-sol',
    deps_type=Customer,
    output_type=Triage,
    instructions=(
        'Triage the support message. Use customer_plan for context. '
        'Summarize the issue without inventing account facts.'
    ),
)

@agent.tool
def customer_plan(ctx: RunContext[Customer]) -> str:
    """Return the authenticated customer's plan."""
    return ctx.deps.plan

if __name__ == '__main__':
    result = agent.run_sync(
        'I was charged twice for my subscription.',
        deps=Customer(plan='business'),
    )
    print(result.output.model_dump())

Si la ejecución termina correctamente, result.output es un objeto Triage. La categoría y la prioridad deben ajustarse a las opciones declaradas, y model_dump() convierte el objeto en un diccionario. La herramienta de contexto, el resultado tipado y el rechazo de una categoría no válida se comprobaron sin conexión mediante TestModel. La redacción que genere el modelo y la precisión de la clasificación todavía deben evaluarse con tus propios casos.

El contexto del cliente es ilustrativo. En un producto, constrúyelo a partir de la solicitud autenticada y los registros de las cuentas. Define también qué hace que un caso sea urgente: el esquema enumera las etiquetas válidas, pero no contiene una política de urgencia. Resolver esa regla de negocio pendiente importa más que añadir otro agente.

Modelos en Pydantic AI: cambiar de proveedor no garantiza el mismo comportamiento

Pydantic AI reduce el trabajo de integración específico de cada proveedor, pero cambiar de modelo sigue alterando el comportamiento. Muchas vías de acceso usan un identificador <provider>:<model>. Otras requieren un modelo o cliente explícito, las credenciales correspondientes y componentes adicionales de instalación. Las funciones disponibles dependen del modelo y de la API elegidos, como deja claro el directorio de proveedores.

El directorio incluye OpenAI, Anthropic, Google/Gemini, AWS Bedrock, Groq, Mistral, xAI y Ollama. Las demás vías documentadas abarcan:

• Servicios de modelos e inferencia: Alibaba Cloud/Qwen, Cerebras, Cohere, Crusoe, DeepSeek, Fireworks AI, Heroku AI, Hugging Face, Meta, Moonshot AI/Kimi, Nebius AI Studio, OVHcloud AI Endpoints, SambaNova, Snowflake Cortex, Together AI y Z.AI.
• Opciones en la nube, pasarelas y alojamiento propio: Google Cloud/Vertex AI, Microsoft Azure/Foundry, Pydantic AI Gateway, LiteLLM, OpenRouter, Vercel AI Gateway y vLLM.
• Vías adicionales de acceso y modelos de decisión: GitHub Copilot, OpenAI Codex, OpenAI Decisions API, System One API y TypeSafe (Jev).

Estos nombres representan distintas formas de acceder a modelos, no conjuntos de funciones intercambiables. Un modelo local puede usar las herramientas de forma distinta a un modelo de vanguardia alojado por un proveedor. Una API compatible también puede imponer otras restricciones a los esquemas.

Para quien funda una empresa, la portabilidad ofrece una salida y margen para experimentar. Para quien la implementa, la prueba de aceptación sigue siendo la misma: ¿el sustituto elige las herramientas correctas, respeta el esquema de salida y toma decisiones aceptables con los mismos casos? Conserva esas pruebas antes de cambiar el modelo predeterminado en producción.

MCP y ejecución duradera: conecta herramientas y conserva el progreso

MCP conecta un agente con servidores de herramientas; la ejecución duradera ayuda a que una tarea sobreviva a una interrupción. Cada uno resuelve un problema distinto.

Model Context Protocol, o MCP, estandariza cómo las aplicaciones exponen herramientas y contexto a los clientes de IA. La compatibilidad con MCP de Pydantic AI permite usar URL de servidores y pasar clientes o conjuntos de herramientas, además de las opciones de MCP nativas del proveedor cuando están disponibles. Así puedes reutilizar un servidor de herramientas sin escribir una integración nueva para cada agente. MCP no decide qué cliente tiene permiso para usar las operaciones de ese servidor.

La ejecución duradera conserva el progreso para que el trabajo pueda continuar después de un fallo, un reinicio o una espera prolongada. La documentación actual sobre ejecución duradera enumera 9 soluciones:

• Mantenidas en colaboración con los equipos de los proveedores: Temporal, DBOS, Prefect, Restate y AWS Lambda.
• Integraciones externas con el SDK: Kitaru, Apache Airflow, Absurd y pgtask.

También hay una herramienta para crear backends destinados a otros motores. Elige una integración documentada cuando el agente deba seguir trabajando más allá de la solicitud o del proceso que lo inició. Que existan estas integraciones no convierte una simple llamada a Agent en un despliegue con ejecución duradera.

Piensa en una tarea de soporte que prepara una recomendación de reembolso, espera una aprobación y después la aplica. Guardar la ejecución permite conservar el trabajo pendiente, pero la operación de pago sigue necesitando idempotencia: repetir la solicitud no debería generar otro reembolso. Decide cómo identificar una operación ya realizada y cómo aclarar un resultado incierto. Esa responsabilidad corresponde a la aplicación, además de lo que haga el motor.

Pydantic AI Evals: evalúa la decisión que hay detrás del objeto

Pydantic Evals comprueba si el agente hizo un trabajo aceptable, más allá de que su salida se pueda analizar. Es un paquete de evaluación independiente, basado en código, que no requiere Pydantic AI. Defines casos y evaluadores, ejecutas la tarea con ellos y revisas un informe. La documentación explica cómo evaluar tanto las salidas finales como las trayectorias de llamadas a herramientas: la secuencia de acciones realizadas durante una ejecución.

Para el ejemplo de clasificación, prepara casos de cobros duplicados, errores al iniciar sesión, falta de contexto de la cuenta y mensajes que pidan al asistente ignorar sus instrucciones. Comprueba la categoría, la decisión de derivar el caso y si se realizó la consulta de cuenta necesaria. Incluye situaciones en las que la respuesta adecuada sea hacer una pregunta.

Para quien opera el sistema, una traza explica una ejecución; una evaluación mide el comportamiento en distintos casos. Pydantic AI utiliza OpenTelemetry, un estándar de telemetría de aplicaciones, y admite otros backends de observabilidad mediante su instrumentación. Cuando falle un caso, revisa la solicitud al modelo y las llamadas a herramientas, y conserva ese caso en el conjunto de evaluación.

Pydantic Logfire es opcional y ofrece trazas de agentes, modelos y herramientas. Su plan Personal es gratuito y Team parte de 49 USD/mes; el uso adicional y los puestos de usuario se facturan por separado, según su página de precios.

¿Cuándo conviene elegir Pydantic AI frente a otro framework?

Elige la abstracción que encaje con la parte difícil de tu funcionalidad. Si desarrollas en Python y ya tienes modelos de dominio y servicios, incluye Pydantic AI entre las opciones cuando el principal reto de integración sean las entradas, las herramientas y las salidas tipadas. Si eres fundador y tienes perfil técnico, pregúntate qué opción permite operar un sistema más pequeño que tu empresa pueda explicar y mantener.

Pydantic AI vs LangGraph

LangGraph es un mejor punto de partida cuando quieres diseñar explícitamente el flujo de trabajo que rodea al agente. Su documentación se centra en agentes de larga duración con estado, ejecución duradera e intervención humana. Piensa en una aplicación con etapas obligatorias: reunir pruebas, obtener aprobación, ejecutar una acción autorizada y verificar el resultado.

Pydantic AI resulta atractivo cuando el agente tipado es un componente de un proceso que tu aplicación ya controla. También puede participar en flujos duraderos, por lo que la persistencia no basta para decidir. La pregunta clave es si quieres modelar el proceso de negocio que rodea al agente o, principalmente, configurar el comportamiento del propio agente. Con LangGraph, debes asumir el diseño del flujo y la gestión del estado; con Pydantic AI, el límite es que su práctico contrato de agente no diseña por ti el proceso completo.

Pydantic AI vs LangChain

LangChain tiene sentido cuando sus integraciones existentes de modelos y herramientas y su arquitectura de agentes ya encajan con tu aplicación. Los agentes de LangChain se construyen sobre LangGraph, según la descripción general de LangChain. Por tanto, elegir su API de agentes de mayor nivel no implica prescindir de esa base de ejecución.

Elige Pydantic AI para un servicio Python si sus contratos de dependencias y salidas encajan con tu forma habitual de programar. Conserva una funcionalidad que ya funcione en LangChain, salvo que puedas señalar una fuente concreta de complejidad que la migración vaya a eliminar. Sigue siendo necesario entender la abstracción de LangChain cuando el comportamiento atraviesa las capas del agente y del flujo de trabajo; cambiar de biblioteca solo traslada ese trabajo. La relación entre ambos se desarrolla en LangChain vs LangGraph.

OpenAI Agents SDK o llamadas directas a la API

OpenAI Agents SDK encaja cuando tu aplicación gestiona el ciclo del agente, con herramientas, transferencias entre agentes y trazas. El SDK se ejecuta dentro de tu aplicación y admite salidas estructuradas. Sus interfaces de proveedores también permiten usar modelos ajenos a OpenAI. No sería correcto presentar las salidas tipadas o la elección de proveedor como ventajas exclusivas de Pydantic AI.

Elige ese SDK si su modelo de agentes y transferencias encaja con la integración de OpenAI que quieres mantener. Elige Pydantic AI si su modelo de dependencias de Python y su configuración de proveedores se ajustan mejor. En ambos casos, el despliegue, la autorización de herramientas y el funcionamiento correcto de la aplicación quedan en tus manos.

Usa llamadas directas a la API cuando la tarea consista en una solicitud al modelo acompañada de una pequeña cantidad de código determinista. Las API directas ya pueden devolver salidas restringidas por un esquema. Un extractor de recibos no necesita un framework de agentes solo porque el resultado sea un objeto Pydantic. El límite aparece cuando te encuentras reconstruyendo una y otra vez los ciclos de llamadas a herramientas, los reintentos de validación y la instrumentación para distintas funcionalidades.

Para comparar más opciones, consulta la guía de frameworks de agentes de IA. Si la duda pendiente es si priorizar el control explícito del flujo o los roles de agentes especializados, continúa con LangGraph vs CrewAI.

¿Qué se exagera sobre los agentes tipados?

La exageración consiste en presentar un agente tipado como un sistema que, por ese solo hecho, funciona correctamente en producción. La biblioteca no puede eliminar ciertos límites:

• La seguridad de tipos no garantiza la exactitud de los hechos. Una respuesta bien formada puede interpretar mal la solicitud del usuario. Decide qué debes contrastar con registros de referencia fiables.
• La portabilidad entre modelos no garantiza la misma calidad. Una nueva configuración de proveedor necesita la misma evaluación de la tarea que un prompt nuevo.
• La ejecución duradera no resuelve automáticamente el despliegue. Elige y opera el motor, el almacenamiento y la vía de recuperación que necesite tu funcionalidad.
• Un reintento supone trabajo adicional. Otra solicitud al modelo añade latencia y consumo. Define qué hará la aplicación cuando se agoten los reintentos.

Da el paso si tu próxima funcionalidad en Python ya necesita herramientas y decisiones estructuradas. Pospón la migración de framework si el sistema actual funciona y la única ventaja propuesta es que el código de demostración se vea más limpio. Si tu funcionalidad es una llamada sencilla de extracción con validación y gestión de errores suficientes, esta elección apenas te afecta.

Preguntas frecuentes sobre Pydantic AI

Qué poner en marcha la próxima semana

Antes de ampliar la autonomía, fija criterios claros de aceptación para una pequeña funcionalidad de solo lectura. En un producto de soporte, empieza con el objeto de clasificación del ejemplo y deja la acción final sobre la cuenta en el código convencional de la aplicación.

Para recibir notas prácticas sobre el desarrollo de funcionalidades de IA, suscríbete al boletín.