Pydantic AI + Ertas

Construye agentes en producción con Pydantic AI — el framework de agentes Python con seguridad de tipos del equipo de Pydantic, con soporte de primera clase para modelos locales ajustados vía endpoints compatibles con OpenAI.

Overview

Pydantic AI es el framework de agentes del equipo detrás de Pydantic y Logfire — la biblioteca de validación que se convirtió en el estándar de facto de Python para integridad de datos en tiempo de ejecución, usada por prácticamente todos los frameworks web modernos de Python. Pydantic AI extiende esa misma disciplina de seguridad de tipos a los agentes LLM: cada herramienta, cada entrada, cada salida es un modelo Pydantic tipado, validado en tiempo de ejecución, con la informe de errores completo de Pydantic y el autocompletado del IDE en el que los desarrolladores Python ya confían. El framework alcanzó su lanzamiento v1 en abril de 2026 y rápidamente se convirtió en la alternativa estrella en ascenso a LangGraph para equipos que priorizan la seguridad de tipos y la ergonomía del desarrollador frente a las funciones de orquestación basadas en grafos. Los lanzamientos puntuales v1.90.x y v1.93.x de principios de mayo de 2026 añadieron una configuración explícita de `tool_choice` en `Agent`, eventos dedicados `OutputToolCallEvent` y `OutputToolResultEvent` para streaming de grano fino, y soporte de estado de la API OpenAI Conversations — mejoras que hacen que el uso en producción sea más controlable y observable.

El diseño del framework toma directamente de FastAPI: las dependencias se declaran mediante anotaciones de tipo, las herramientas son funciones decoradas con `@agent.tool`, y la validación es automática. A diferencia de los frameworks de agentes más antiguos que manejan la salida estructurada mediante ingeniería de prompts y parsing posterior, Pydantic AI utiliza las capacidades nativas de llamada de funciones del modelo subyacente y expone los fallos de validación como excepciones de Python que puedes capturar y reintentar. Esto produce agentes dramáticamente más confiables — cuando algo sale mal, obtienes un stack trace claro, no un modelo que alucina campos y falla silenciosamente más adelante.

Pydantic AI es agnóstico al modelo. El framework admite OpenAI, Anthropic, Google y cualquier endpoint compatible con OpenAI a través de su abstracción de proveedor, lo que lo convierte en una opción natural para modelos locales auto-hospedados servidos a través de Ollama, vLLM o LM Studio. La combinación de la seguridad de tipos de Pydantic AI y un modelo local ajustado es particularmente atractiva: el framework impone el cumplimiento del esquema en el límite, el modelo ajustado produce salidas de alta calidad en el formato entrenado, y juntos ofrecen agentes que son tanto confiables como económicos.

How Ertas Integrates

Los modelos entrenados con Ertas funcionan con Pydantic AI a través de su proveedor de OpenAI configurado contra un endpoint local. Después de ajustar tu modelo en Ertas Studio y exportarlo a GGUF, lo sirves a través de Ollama, vLLM o Ertas Cloud, luego apuntas el proveedor `OpenAIModel` de Pydantic AI al endpoint. Cada agente en tu base de código — ya sea que haga una sola llamada al LLM o coordine un flujo de trabajo complejo de múltiples pasos — usa tu modelo entrenado con Ertas como motor subyacente.

La integración es particularmente potente debido a cómo Pydantic AI maneja las salidas estructuradas. El parámetro `result_type` del framework acepta cualquier modelo Pydantic, y el agente validará la salida del LLM contra ese esquema, lanzando un `ValidationError` si la salida no se ajusta. Para modelos ajustados específicamente — donde el proceso de entrenamiento de Ertas Studio puede incluir ejemplos de conformidad de esquema — esto se convierte en un bucle auto-reforzante: el modelo produce salidas que coinciden con el esquema, Pydantic AI las valida, y cualquier fallo (que se vuelve raro tras el ajuste) emerge como excepciones capturables que puedes reintentar o registrar.

Para despliegues móviles a través de Ertas Deployment CLI, el runtime ligero de Pydantic AI es un buen ajuste. El framework añade una sobrecarga mínima más allá de la propia llamada al LLM, lo cual importa cuando se ejecuta un bucle de agente en el dispositivo a través de llama.cpp. La seguridad de tipos en el lado de la aplicación host (ya sea que el host sea un backend Python o una aplicación móvil que llame a un servidor de inferencia local) hace que los contratos sean explícitos y reduce la superficie de integración donde típicamente se ocultan los errores.

Getting Started

1
Ajusta tu modelo de dominio en Ertas Studio
Entrena con datos que incluyan las salidas estructuradas y las llamadas a herramientas que tu agente Pydantic AI utilizará. El formato JSONL de Studio se mapea directamente a los patrones `messages` y `result_type` de Pydantic AI.
2
Despliega en un endpoint compatible con OpenAI
Exporta a GGUF y sirve vía Ollama, vLLM o Ertas Cloud. El proveedor de OpenAI de Pydantic AI se conecta a cualquier endpoint que exponga la API estándar de chat-completion.
3
Instala Pydantic AI y configura el proveedor del modelo
Instala pydantic-ai. Crea una instancia de `OpenAIModel` (o `OpenAIProvider`) apuntada a tu endpoint de inferencia de Ertas con el nombre de tu modelo.
4
Define herramientas tipadas y esquemas de resultado
Declara herramientas como funciones Python decoradas con anotaciones de tipo. Define los esquemas de resultado como modelos Pydantic. Pydantic AI maneja la validación, los reintentos en caso de fallos de esquema, y el reporte claro de errores automáticamente.
5
Ejecuta el agente y maneja la validación
Llama a `agent.run()` o `agent.run_sync()` con tu entrada. Pydantic AI devuelve un resultado tipado. Captura `ValidationError` para lógica de reintento estructurada, o confía en el comportamiento de reintento integrado del framework.

python

from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel

# Apunta Pydantic AI a tu modelo entrenado con Ertas servido vía Ollama
model = OpenAIModel(
    "ertas-support-agent-7b",
    base_url="http://localhost:11434/v1",
    api_key="not-needed",
)

class TicketTriage(BaseModel):
    category: str
    priority: int  # 1-5
    suggested_team: str
    requires_human: bool

agent = Agent(
    model,
    result_type=TicketTriage,
    system_prompt="You triage customer-support tickets for a SaaS product.",
)

@agent.tool
async def lookup_customer(ctx, customer_id: str) -> dict:
    """Fetch customer record from the CRM."""
    return await crm.get_customer(customer_id)

# El agente devuelve un objeto TicketTriage validado — o lanza ValidationError
result = agent.run_sync(
    "Customer 12345 says the dashboard hasn't loaded for 30 minutes."
)
print(result.data.priority, result.data.suggested_team)

Construye un agente de triaje de tickets con seguridad de tipos en Pydantic AI respaldado por un modelo entrenado con Ertas. La salida del agente se valida automáticamente contra un esquema Pydantic.

Benefits

Seguridad de tipos en cada límite — herramientas, entradas, salidas son todos modelos Pydantic tipados
Ergonomía similar a FastAPI que los desarrolladores Python ya conocen
Soporte nativo de llamada de funciones — sin parsing JSON ingenierado por prompts
Validación de esquema automática con excepciones Python capturables en caso de fallo
Runtime ligero — añade una sobrecarga mínima más allá de la propia llamada al LLM
Se combina naturalmente con modelos ajustados que producen salidas conformes al esquema
Integración con Logfire para observabilidad en producción