PydanticAI: agentes IA con tipado seguro en Python

Instalación

PydanticAI se instala desde PyPI con pip. Para trabajar con todos los proveedores de modelos, se pueden instalar los extras correspondientes en la misma instrucción:

# Instalación básica
pip install pydantic-ai

# Con soporte para Anthropic Claude y Google Gemini además de OpenAI
pip install "pydantic-ai[anthropic,google-generativeai]"

# Con soporte para Logfire (observabilidad)
pip install "pydantic-ai[logfire]"

Primer agente: respuesta en texto libre

El agente más sencillo posible requiere solo el modelo y una llamada a run_sync(). PydanticAI infiere el proveedor del modelo a partir del nombre del string — los modelos openai:gpt-*, anthropic:claude-* y google-gla:gemini-* se resuelven automáticamente con la clave de API correspondiente en el entorno:

from pydantic_ai import Agent

agente = Agent(
    model="anthropic:claude-3-5-sonnet-latest",
    system_prompt="Eres un asistente que responde en espanol de forma concisa.",
)

resultado = agente.run_sync("Cual es la capital de Francia?")
print(resultado.data)
# Paris

Agente con herramienta y system prompt dinámico

Las herramientas se registran con el decorador @agent.tool_plain (sin acceso al contexto de ejecución) o @agent.tool (con acceso al RunContext para leer dependencias). El system prompt puede ser una cadena estática o una función decorada con @agent.system_prompt que se evalúa en cada ejecución con acceso a las dependencias de la llamada:

from pydantic_ai import Agent, RunContext
from datetime import date

agente = Agent(
    model="openai:gpt-4o",
    system_prompt="Eres un asistente de calendario. Hoy es {date}.",
)

@agente.system_prompt
def system_prompt_dinamico() -> str:
    return f"Eres un asistente de calendario. Hoy es {date.today().isoformat()}."

@agente.tool_plain
def obtener_dia_semana(fecha: str) -> str:
    """Devuelve el dia de la semana para una fecha en formato YYYY-MM-DD."""
    d = date.fromisoformat(fecha)
    dias = ["lunes", "martes", "miercoles", "jueves", "viernes", "sabado", "domingo"]
    return dias[d.weekday()]

resultado = agente.run_sync("En que dia de la semana cae el 15 de agosto de 2025?")
print(resultado.data)
# 15 de agosto de 2025 cae en viernes.

Structured output con modelos Pydantic

Para obtener datos estructurados en lugar de texto libre basta con pasar un modelo Pydantic como result_type al instanciar el agente. PydanticAI genera internamente el schema JSON del modelo, lo incluye en la llamada al LLM como restricción de formato de salida, y valida la respuesta con Pydantic v2 antes de devolverla — incluyendo todas las validaciones personalizadas definidas con @field_validator o @model_validator:

from pydantic import BaseModel, field_validator
from pydantic_ai import Agent

class ExtraccionContacto(BaseModel):
    nombre: str
    email: str
    empresa: str | None = None
    telefono: str | None = None

    @field_validator("email")
    @classmethod
    def validar_email(cls, v: str) -> str:
        if "@" not in v:
            raise ValueError(f"Email invalido: {v}")
        return v.lower()

agente = Agent(
    model="anthropic:claude-3-5-sonnet-latest",
    result_type=ExtraccionContacto,
    system_prompt="Extrae los datos de contacto del texto proporcionado.",
)

texto = """
Hola, me llamo Maria Garcia. Mi email es maria@ejemplo.com
y trabajo en Tecnologias SA. Puedes llamarme al +34 612 345 678.
"""

resultado = agente.run_sync(texto)
contacto = resultado.data
print(contacto.nombre)  # Maria Garcia
print(contacto.email)   # maria@ejemplo.com
print(contacto.empresa) # Tecnologias SA

Reintento automático ante fallos de validación

Cuando el LLM devuelve una respuesta que no supera la validación Pydantic, PydanticAI reintenta la llamada incluyendo el error de validación en el contexto del siguiente intento. El número máximo de reintentos se configura con el parámetro retries en el agente. Este mecanismo es especialmente valioso con modelos más pequeños o cuando los schemas son complejos — en lugar de propagar una excepción al código llamante, el agente da al modelo la oportunidad de corregir su salida con información concreta sobre qué falló:

from pydantic import BaseModel, model_validator
from pydantic_ai import Agent

class Distribucion(BaseModel):
    categoria_a: float
    categoria_b: float
    categoria_c: float

    @model_validator(mode="after")
    def suma_debe_ser_cien(self) -> "Distribucion":
        total = self.categoria_a + self.categoria_b + self.categoria_c
        if abs(total - 100.0) > 0.01:
            raise ValueError(
                f"Los porcentajes deben sumar 100. Suma actual: {total}"
            )
        return self

agente = Agent(
    model="openai:gpt-4o-mini",
    result_type=Distribucion,
    retries=3,  # hasta 3 reintentos si la validacion falla
    system_prompt=(
        "Analiza el texto y estima la distribucion porcentual del presupuesto "
        "entre tres categorias: marketing, desarrollo y operaciones. "
        "Los porcentajes deben sumar exactamente 100."
    ),
)

resultado = agente.run_sync(
    "Una startup de 10 empleados con foco en producto y poco marketing."
)
print(resultado.data)
# Distribucion(categoria_a=20.0, categoria_b=60.0, categoria_c=20.0)

PydanticAI abstrae las diferencias entre proveedores a través de su sistema de modelos. El string del modelo sigue el formato proveedor:nombre-modelo. Las claves de API se leen de las variables de entorno estándar de cada proveedor (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY) sin configuración adicional. Para modelos locales con Ollama no se necesita ninguna clave de API — solo que el servidor Ollama esté en ejecución:

from pydantic_ai import Agent

# OpenAI (requiere OPENAI_API_KEY)
agente_openai = Agent(model="openai:gpt-4o")

# Anthropic Claude (requiere ANTHROPIC_API_KEY)
agente_claude = Agent(model="anthropic:claude-3-5-sonnet-latest")

# Google Gemini (requiere GEMINI_API_KEY)
agente_gemini = Agent(model="google-gla:gemini-1.5-pro")

# Groq — inferencia rapida de modelos open source (requiere GROQ_API_KEY)
agente_groq = Agent(model="groq:llama-3.1-70b-versatile")

# Mistral (requiere MISTRAL_API_KEY)
agente_mistral = Agent(model="mistral:mistral-large-latest")

# Ollama — modelo local, sin clave de API
agente_local = Agent(model="ollama:llama3.2")

Configuración avanzada: parámetros del modelo

Para ajustar parámetros del modelo — temperatura, número máximo de tokens de salida, top_p — se instancia directamente la clase del modelo en lugar de usar el string abreviado. Esto da acceso completo a la configuración específica de cada proveedor sin perder la compatibilidad con el resto del framework:

from pydantic_ai import Agent
from pydantic_ai.models.anthropic import AnthropicModel

modelo = AnthropicModel(
    model_name="claude-3-5-sonnet-20241022",
    # temperature y otros parametros se pasan en cada llamada via model_settings
)

agente = Agent(
    model=modelo,
    model_settings={"temperature": 0.2, "max_tokens": 1024},
    system_prompt="Eres un extractor de datos preciso. Sin inventar informacion.",
)

Ejemplo de test con TestModel y pytest

import pytest
from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel

class ResumenDocumento(BaseModel):
    titulo: str
    puntos_clave: list[str]
    longitud_palabras: int

agente = Agent(
    model="anthropic:claude-3-5-sonnet-latest",
    result_type=ResumenDocumento,
    system_prompt="Resume el documento proporcionado de forma estructurada.",
)

def test_agente_genera_resumen_valido():
    with agente.override(model=TestModel()):
        resultado = agente.run_sync("Texto del documento de prueba")
        resumen = resultado.data
        assert isinstance(resumen, ResumenDocumento)
        assert resumen.titulo != ""
        assert len(resumen.puntos_clave) > 0
        assert resumen.longitud_palabras >= 0

Regla de decisión rápida

Elige PydanticAI cuando la fiabilidad del output sea la prioridad, cuando tu proyecto ya usa Pydantic para validar otros datos, o cuando necesites tests unitarios rápidos para el comportamiento del agente. Elige LangChain cuando necesites muchas integraciones con sistemas externos o flujos de control complejos con LangGraph. Elige CrewAI cuando el caso de uso sea un equipo de agentes con roles bien definidos. Elige Claude Agent SDK cuando quieras que Anthropic gestione el bucle del agente y el sandbox de ejecución de herramientas con Claude como modelo exclusivo.