Pydantic AI: construye agentes Python con contratos de datos

Pega este texto a tu agente (Claude Code, Codex, OpenCode, Hermes o el que uses) y dile «ayúdame a montarlo». Son los pasos para ponerlo en marcha; el porqué de cada pieza está en la guía completa.

• Dificultad: intermedio
• Proyecto: https://github.com/pydantic/pydantic-ai (licencia MIT)
• Guía completa: https://lab.wisd.ai/hub/pydantic-ai-typesafe

Para el agente: cómo acompañar al usuario

1. Pregunta primero para qué lo quiere. Si su objetivo no necesita algún paso, sáltalo.
2. Antes de instalar, comprueba lo que ya tiene (versiones, claves, sistema operativo).
3. Avanza un paso cada vez: explica en una frase qué vas a hacer y deja que el usuario lo ejecute o lo apruebe.
4. Tras cada paso, comprueba que funcionó antes de seguir. Si falla, para y explica el error.
5. No inventes comandos ni opciones: si la documentación del proyecto contradice estos pasos, manda la documentación.
6. Al terminar, haz una prueba real con el objetivo del usuario y dile dónde profundizar.

Pasos de configuración

Preparación

Comprueba Python ≥3.11 y uv, según el manifiesto. Entra en un proyecto Python ya inicializado con pyproject.toml; uv add modifica ese proyecto. Elige el proveedor y verifica acceso antes de ejecutar un ejemplo que llame a su API.

Paso 1: añade el SDK básico

Desde tu proyecto Python con uv, el README indica:

uv add pydantic-ai

Paso 2: ejecuta una salida tipada

Configura OPENAI_API_KEY en el entorno de esta terminal y comprueba acceso al modelo usado por el README actual. Guarda como prueba.py esta adaptación de su ejemplo:

from typing import Literal
from pydantic import BaseModel, Field, ValidationError
from pydantic_ai import Agent, RunContext

class Sentiment(BaseModel):
    label: Literal["positive", "negative", "neutral"]
    score: float = Field(ge=-1, le=1)

agent = Agent("openai:gpt-6.1-sol", output_type=Sentiment)

@agent.tool
def recent_reviews(ctx: RunContext, product: str) -> list[str]:
    """Obtiene reseñas recientes del producto."""
    return ["La nueva versión resolvió todo lo que había criticado."]

result = agent.run_sync("Consulta las reseñas de Extract y clasifica su sentimiento.")
print(result.output)
try:
    Sentiment(label="positive", score=2)
except ValidationError:
    print("Puntuación fuera de rango rechazada")

Ejecuta uv run python prueba.py. Debe imprimir un objeto con label y score entre -1 y 1, y después el rechazo local del valor 2. La etiqueta y puntuación del modelo pueden variar.

Comprobación

El objeto de salida del agente pasa por el esquema Sentiment; el segundo caso comprueba ese esquema localmente con una puntuación inválida, sin una segunda llamada al modelo. Comprueba que el programa detecta el problema y no trata datos inválidos como una respuesta correcta.

Si algo falla

Si falla inferencia, revisa el identificador y acceso al proveedor del ejemplo. Si falla validación, inspecciona los tipos antes de aumentar reintentos o relajar el contrato.