PydanticAI

1. Visión general del concepto y problema sistémico

La primera ola de bibliotecas para trabajar con modelos de lenguaje se creó en una era de prototipado rápido: se basaban en clases dinámicas anidadas, diccionarios no tipados, prompts invisibles y herencia compleja. En el backend de producción, esto generaba dificultades catastróficas:

1. Falta de autocompletado y refactorización: IDE no entiende qué campos devuelve el agente, y cambiar el nombre de una propiedad rompe el código en tiempo de ejecución sin advertencias.
2. Dificultades con la testabilidad: Imposible aislar la lógica del agente de servicios externos o sustituir la base de datos por un mock de prueba debido a la falta de una inyección de dependencias adecuada.
3. Manejo poco confiable de errores de estructura: Los modelos a menudo omiten campos obligatorios o confunden tipos (por ejemplo, una cadena en lugar de un número), lo que lleva a caídas en la API.

PydanticAI de Samuel Colvin (autor de Pydantic) devuelve el desarrollo de agentes al ámbito de la ingeniería de software clásica y limpia: es un marco tipado, minimalista y rápido, construido sobre el estándar Pydantic v2.

2. Taxonomía arquitectónica y modelo mental

La arquitectura de PydanticAI se basa en cuatro pilares conceptuales:

• 1. Agente parametrizado (Agent[Deps, ResultType]): El agente se tipa explícitamente con dos parámetros: el tipo de dependencias contextuales (Deps) que necesita para operar, y el tipo del resultado final (ResultType). Si el resultado es un modelo Pydantic, el agente garantiza devolver una instancia validada de la clase.
• 2. Contexto de ejecución y DI (RunContext[Deps]): Mecanismo de inyección de dependencias. Cada herramienta y prompt dinámico accede a ctx.deps, donde se almacenan conexiones activas a bases de datos, configuraciones o información sobre los derechos del usuario.
• 3. Herramientas tipadas (@agent.tool): Funciones de Python cuyos argumentos se traducen automáticamente a JSON Schema para LLM. Las descripciones de los argumentos se obtienen de Type Hints y docstrings.
• 4. Prompts de sistema dinámicos (@agent.system_prompt): Funciones asíncronas que generan la instrucción del sistema 'sobre la marcha' basándose en las dependencias pasadas (por ejemplo, insertando el saldo actual del usuario o la zona horaria).

3. Pipeline técnico y mecánica interna

El ciclo de vida de la ejecución de una solicitud en PydanticAI:

1. Instantiation & Context Binding (Instanciación y vinculación de contexto): Al llamar a agent.run(prompt, deps=my_deps), el framework inicializa RunContext y resuelve todas las funciones marcadas con el decorador @agent.system_prompt.
2. Schema Generation & Model Inference (Generación de esquema e inferencia de modelo): Los tipos de los argumentos de las herramientas y el ResultType final se convierten en estrictos esquemas JSON a través del motor Pydantic Core (escrito en Rust, que proporciona velocidad en microsegundos).
3. Tool Invocation with Self-Correction (Invocación de herramientas con autocorrección): Cuando el modelo devuelve una llamada a la herramienta, los argumentos de entrada se procesan a través del validador de Pydantic. Si la validación falla (por ejemplo, se pasa un número negativo donde se espera un PositiveInt), PydanticAI no lanza una excepción, sino que envía automáticamente un mensaje al modelo: “Error de validación en el campo X: se esperaba un valor > 0. Intenta de nuevo.”
4. Structured Output Serialization & Streaming (Serialización de salida estructurada y transmisión): La respuesta final se deserializa en el objeto Python objetivo. Se admite el método run_stream(), que permite transmitir campos parcialmente formados del objeto al cliente en tiempo real.

4. Escenarios prácticos de ingeniería en producción

01. Agentes nativos dentro de FastAPI

Uso compartido de modelos: el mismo esquema InvoiceExtractionResponse se utiliza como esquema de salida de PydanticAI, como response_model en el endpoint de FastAPI y para la generación automática del tipo TypeScript del cliente a través de OpenAPI.

02. Trabajo seguro con transacciones de bases de datos

A través de RunContext, se inyecta una sesión transaccional AsyncSession de SQLAlchemy en las herramientas. El agente puede realizar verificaciones y escribir datos. Si ocurre un error en la etapa final, el gestor de contexto externo revierte la transacción, evitando la persistencia de datos semisólidos.

03. Streaming de interfaces estructuradas (Generative UI)

El agente genera un dashboard dinámico. Gracias al soporte de validación de flujo de PydanticAI, el frontend puede renderizar gráficos y tarjetas antes de que el modelo termine de formar el documento JSON completo.

5. Errores comunes, trampas y seguridad

• Falta de descripciones de campos (Field(description=...)): El modelo forma la llamada basándose únicamente en los nombres y descripciones de los campos. Si un campo tiene un nombre ambiguo (por ejemplo, status: int), y falta la descripción, el modelo puede generar regularmente valores incorrectos.
• Agotamiento de intentos de corrección de errores (Max Retries Exceeded): Si el esquema es demasiado complicado, el modelo puede agotar el límite de retries=3, intentando ajustar la respuesta al validador, lo que llevará a la caída de la solicitud. Simplifique los esquemas o descompóngalos en subtareas.
• Fugas de ciclo de vida de recursos en Deps: Asegúrese de que los objetos que pasa en deps (pools de conexiones, clientes HTTP) se cierren correctamente después de que el agente haya terminado su trabajo (a través de async with).