Pydantic AI vs LangGraph: Qué Framework de Agentes para Modelos Ajustados

Actualizado 2026-05-10 — Refleja los lanzamientos de Pydantic AI v1.90.x / v1.93.x de principios de mayo (tool_choice explícito, eventos de streaming dedicados OutputToolCallEvent / OutputToolResultEvent, estado de la API OpenAI Conversations). La matriz de decisión de abajo no cambia; las nuevas primitivas mayormente refuerzan la historia de seguridad de tipos y observabilidad en la que Pydantic AI ya estaba ganando.

Para 2026 el panorama de frameworks de agentes Python se ha consolidado. El enfoque artesanal de "bucle while llamando a OpenAI" ha desaparecido de cualquier equipo que envíe agentes a producción. El stack Frankenstein del LangChain temprano con sus cuarenta abstracciones componibles también ha desaparecido. Dos frameworks permanecen en el centro del trabajo serio: LangGraph, el framework de máquina de estados basado en grafos que ahora ejecuta agentes de producción en Uber, JPMorgan, BlackRock y Replit; y Pydantic AI, el framework con seguridad de tipos al estilo FastAPI cuyo lanzamiento 1.0 en abril de 2026 lo convirtió en el predeterminado obvio para nuevos proyectos.

Ambos son agnósticos al modelo. Ambos funcionan limpiamente con modelos open-weight ajustados servidos a través de Ollama, vLLM o Ertas Cloud. Ambos tratan las llamadas a herramientas como una primitiva de primera clase. Elegir entre ellos no es una cuestión de cuál es "mejor" — es una elección de filosofía de diseño sobre cómo deberían estructurarse tus agentes. Esta pieza recorre los compromisos honestamente, luego muestra cómo cualquiera de los frameworks se beneficia dramáticamente al añadir un modelo ajustado debajo.

Pydantic AI: agentes con tipos primero

Pydantic AI está construido por el equipo detrás de Pydantic y Logfire. La filosofía de diseño se toma directamente de FastAPI: los tipos son contratos, la validación es no negociable, y el framework debería desaparecer en el fondo una vez que hayas declarado tus formas. Un Agent está parametrizado por un tipo de resultado. Las herramientas son funciones decoradas cuyas firmas Pydantic AI parsea para construir esquemas de herramientas. Las salidas se validan automáticamente contra el tipo de resultado. Si el modelo emite algo que no se ajusta, obtienes un ValidationError, no un bug silencioso.

El runtime es ligero. No hay motor de grafos, no hay capa de checkpointing, no hay scheduler de ejecución. Un agente se ejecuta como Python ordinario: llama a agent.run o agent.run_sync, y el framework maneja el bucle del LLM, el dispatch de herramientas y la validación. Toda la biblioteca está bajo licencia MIT y el árbol de dependencias es lo suficientemente pequeño como para que apenas lo notes en tu pyproject.toml.

Esto convierte a Pydantic AI en un ajuste natural para el caso de producción más común: un agente que toma entrada, llama a unas pocas herramientas, devuelve salida estructurada. Agentes de extracción, clasificadores, enrutadores, asistentes ligeros. Si tu flujo de trabajo es mayormente lineal y te importan los esquemas de salida, Pydantic AI te lleva a un agente de producción probado más rápido que cualquier otra cosa disponible. El lanzamiento 1.0 en abril de 2026 estabilizó la API y hizo seguro construir productos comerciales encima.

LangGraph: con estado, durable, orquestado por grafos

LangGraph tomó el camino de diseño opuesto. Un agente es un grafo dirigido de nodos conectados por aristas. Cada nodo es una función (una llamada al LLM, una ejecución de herramienta, una verificación condicional). Las aristas describen cómo fluye el estado entre nodos, incluyendo aristas condicionales que se ramifican según el estado intermedio. El motor del grafo ejecuta todo, persistiendo el estado en cada paso.

Tres cosas surgen de este diseño que Pydantic AI no intenta hacer.

Checkpoints durables. Cada transición de estado se persiste. Si tu agente crashea a mitad de ejecución — proceso terminado, servidor reiniciado, partición de red — puedes reanudar desde el último checkpoint en lugar de empezar de nuevo. Para agentes que se ejecutan durante horas o días, esta es la diferencia entre viable y no.

Ramas paralelas. Como el motor del grafo programa los nodos, puedes hacer fan-out a múltiples ramas paralelas y unirlas más tarde. Un agente de investigación que llama a cinco APIs diferentes en paralelo y agrega sus resultados es una definición de grafo, no una capa de coordinación async artesanal.

Interrupción humano-en-el-bucle. Un grafo puede pausar en un nodo designado, exponer el estado a un revisor humano, y reanudar una vez que vuelva una decisión. Para flujos de trabajo de aprobación, escalaciones y cualquier agente operando en industrias reguladas, esto es esencial. La primitiva interrupt de LangGraph convierte la "aprobación humana" de una idea posterior en un nodo de grafo como cualquier otro.

El coste de estas capacidades es la complejidad. LangGraph requiere que pienses en tu agente como una máquina de estados. Las definiciones de grafos son más verbosas que los agentes basados en decoradores de Pydantic AI. El runtime es más pesado — lleva el motor del grafo, la capa de checkpointing y (en producción) típicamente un backend de Postgres o Redis para persistencia. Para un agente de extracción lineal esto es excesivo. Para un flujo de trabajo de aprobación multi-etapa es exactamente lo que necesitas.

LangGraph es lo que JPMorgan, BlackRock y Uber eligieron para agentes de producción que tocan dinero, soporte al cliente y operaciones relevantes para cumplimiento. El modelo de grafo les da los registros de auditoría que sus equipos de cumplimiento requieren: cada transición de estado se registra, cada llamada a herramienta es reproducible, cada decisión puede reproducirse. El runtime ligero de Pydantic AI no puede proporcionar fácilmente ese nivel de trazabilidad.

Dónde se solapan los dos frameworks

A pesar de filosofías diferentes, ambos frameworks aterrizan en el mismo lugar en varios puntos prácticos.

Ambos hablan la API compatible con OpenAI como un transporte de primera clase. Ambos funcionan con cualquier servidor de modelos que exponga esa interfaz — Ollama, vLLM, llama-server de llama.cpp, LM Studio, Ertas Cloud, la propia API de OpenAI, Anthropic vía proxies compatibles con OpenAI, o cualquier stack de servicio personalizado. Esto significa que un modelo ajustado que has enviado en Ertas Studio funciona idénticamente contra cualquiera de los frameworks sin cambios de código.

Ambos tienen soporte de llamadas a herramientas de primera clase. Declaras funciones, el framework extrae sus esquemas, y al LLM se le da un formato estructurado de uso de herramientas. Ambos validan los argumentos de herramientas antes de la ejecución; ambos exponen los resultados de herramientas de vuelta al LLM en el siguiente turno.

Ambos tienen historias de observabilidad que importan en producción. Pydantic AI se integra estrechamente con Logfire (mismo equipo) y emite trazas OpenTelemetry. LangGraph se integra con LangSmith para tracing de ejecución de grafos y admite exportadores OpenTelemetry. Cualquiera te dará latencia por llamada a herramienta, uso de tokens y trazas de errores en producción.

Así que la elección entre ellos no es sobre capacidades básicas. Es sobre la forma del flujo de trabajo y los requisitos operativos.

Matriz de decisión

Nota el patrón. Pydantic AI gana cuando el flujo de trabajo es mayormente lineal, la estructura de salida importa, y quieres moverte rápido. LangGraph gana cuando el flujo de trabajo es genuinamente una máquina de estados, cuando la durabilidad y los registros de auditoría son no negociables, y cuando el equipo tiene el ancho de banda de ingeniería para diseñar grafos cuidadosamente.

El ángulo del fine-tuning: por qué ambos frameworks lo necesitan

Aquí está la verdad incómoda sobre los frameworks de agentes en 2026: asumen que el modelo puede producir salidas estructuradas de forma confiable. Pydantic AI lo asume porque el validador se dispara en cada salida. LangGraph lo asume porque la salida de cada nodo se convierte en la entrada del siguiente nodo. Cuando el modelo se comporta mal, ambos frameworks recurren a reintentos — y los reintentos cuestan latencia, cuestan tokens y erosionan la confianza del usuario.

Contra una API frontier como Claude o GPT-5 Pro, esa suposición se cumple lo suficientemente bien. Contra un modelo open-weight genérico — Qwen3-7B, Llama 3.3 8B, Mistral Small directo del estante de Hugging Face — no se cumple. Las violaciones de esquema son comunes. Aparecen nombres de herramientas incorrectos. Los tipos de parámetros derivan. La capa de validación del framework pasa de "baranda" a "fuente recurrente de excepciones," y tu equipo empieza a envolver cada llamada al agente en decoradores de reintento que tapan el problema real.

El fine-tuning arregla esto en la fuente. Entrena el modelo en los esquemas de herramientas exactos que tu agente usa, en los formatos de salida exactos que tu código espera, en unas pocas cientos de conversaciones representativas de tu dominio. El modelo se convierte en un productor confiable de salidas estructuradas. El validador de Pydantic AI vuelve a ser una baranda. Los nodos de LangGraph fluyen entre ellos sin lógica envolvente.

La economía se inclina de la misma forma. Una llamada a una API frontier para un agente multi-paso cuesta $0,01 a $0,05 por ejecución. A 10,000 ejecuciones diarias eso son $100 a $500 por día, $36,000 a $180,000 por año. Un modelo de 7B u 8B ajustado servido en una sola instancia GPU cuesta órdenes de magnitud menos, y un modelo de 4B ajustado puede ejecutarse en el dispositivo del usuario gratis. Para los desarrolladores de aplicaciones móviles que sienten el precipicio de costes agéntico morder entre 500 y 5,000 usuarios — el momento en el que las facturas de API empiezan a consumir margen más rápido de lo que crecen los ingresos — el fine-tuning no es una optimización, es el único camino hacia adelante.

La integración es idéntica para ambos frameworks: entrena tu modelo en Ertas Studio, exporta a GGUF, sirve vía Ollama o vLLM, y apunta el base_url de tu agente al endpoint compatible con OpenAI. Desde la perspectiva del framework, tu modelo ajustado es solo otro modelo compatible con OpenAI. Desde la perspectiva del usuario, el agente es dramáticamente más confiable y la factura es dramáticamente más pequeña.

El mismo agente, dos frameworks

Para hacer la comparación concreta, aquí está el mismo agente de triaje — un clasificador de enrutamiento de reclamaciones que mapea tickets de soporte al equipo correcto — implementado en ambos frameworks contra un Qwen3-4B ajustado por Ertas servido vía Ollama.

Versión Pydantic AI:

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

model = OpenAIModel(
    "ertas-claims-router-4b",
    base_url="http://localhost:11434/v1",
    api_key="not-needed",
)

class TriageDecision(BaseModel):
    team: Literal["billing", "technical", "fraud", "general"]
    priority: Literal["low", "normal", "high", "urgent"]
    reasoning: str

agent = Agent(
    model,
    result_type=TriageDecision,
    system_prompt="Route incoming support tickets to the right team and priority.",
)

@agent.tool
async def lookup_account(ctx, account_id: str) -> dict:
    """Look up account history to inform routing."""
    return await crm.get_account(account_id)

result = agent.run_sync(
    "My card was charged twice for the same order this morning."
)
print(result.data)
# TriageDecision(team='billing', priority='high', reasoning='Duplicate charge')

Versión LangGraph:

from typing import TypedDict, Literal
from langgraph.graph import StateGraph, END
from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage

llm = ChatOpenAI(
    model="ertas-claims-router-4b",
    base_url="http://localhost:11434/v1",
    api_key="not-needed",
).bind_tools([lookup_account_tool])

class TriageState(TypedDict):
    ticket: str
    account_data: dict | None
    team: str | None
    priority: str | None

def fetch_account(state):
    if account_id := extract_account_id(state["ticket"]):
        return {"account_data": crm.get_account(account_id)}
    return {"account_data": None}

def classify(state):
    msg = llm.invoke([HumanMessage(content=build_prompt(state))])
    parsed = parse_triage_decision(msg.content)
    return {"team": parsed["team"], "priority": parsed["priority"]}

graph = StateGraph(TriageState)
graph.add_node("fetch", fetch_account)
graph.add_node("classify", classify)
graph.set_entry_point("fetch")
graph.add_edge("fetch", "classify")
graph.add_edge("classify", END)

app = graph.compile()
result = app.invoke({"ticket": "My card was charged twice this morning."})

Ambas implementaciones funcionan. Ambas usan el mismo modelo ajustado. Ambas son aproximadamente treinta líneas de código. La versión Pydantic AI es más corta y te da salidas tipadas por construcción; la versión LangGraph es más verbosa pero cada transición de estado puede tener checkpoint, el grafo puede pausarse para revisión humana añadiendo un nodo interrupt, y todo escala naturalmente a un flujo de trabajo que — digamos — también notifica al equipo, abre un ticket Jira, y espera a que un humano confirme la prioridad antes del enrutamiento final.

Para un clasificador puro, Pydantic AI es la elección obvia. Para un clasificador que es el primer nodo en un flujo de trabajo más largo que involucra aprobaciones y escalaciones, LangGraph empieza a ganarse su complejidad.

Recomendación

Para la mayoría de los equipos en 2026, la respuesta correcta es empezar con Pydantic AI. La carga cognitiva es menor, el runtime es más ligero, la API es más agradable, y la seguridad de tipos se paga por sí misma la primera vez que captura una salida malformada del modelo antes de que llegue a producción. El noventa por ciento de los casos de uso de agentes son lineales o casi lineales, y Pydantic AI los maneja limpiamente.

Gradúate a LangGraph cuando la orquestación de grafo se convierta en el cuello de botella — cuando te encuentres construyendo capas de checkpointing a mano, cuando necesites interrupciones genuinas humano-en-el-bucle, cuando el cumplimiento exija registros de auditoría de cada transición de estado, cuando los flujos de trabajo se ramifiquen y rejunten naturalmente de formas que el control de flujo artesanal no pueda expresar limpiamente. Ese es un momento real para algunos equipos. No es un momento al que la mayoría de los equipos lleguen jamás.

Añade fine-tuning debajo de cualquiera de los frameworks tan pronto como veas la segunda o tercera factura de API. La combinación de un modelo ajustado de 4B-a-8B y un framework de agentes real es lo que hace los agentes de producción tanto confiables como económicos en 2026. Sin fine-tuning, tu framework gasta la mayor parte de su energía pavimentando sobre la falta de confiabilidad del modelo. Con fine-tuning, el framework puede hacer el trabajo para el que fue diseñado.

Ertas Studio maneja el lado del fine-tuning. Elige tu modelo base — Qwen3-4B para móvil y edge, Qwen3-7B o Llama 3.3 8B para agentes del lado del servidor — cura unas pocas cientos de ejemplos en Data Craft, entrena, evalúa, exporta a GGUF. El Ertas Deployment CLI se encarga del camino de envío móvil cuando eso importa. El servicio compatible con OpenAI significa que cualquiera que sea el framework que elegiste, la integración es una línea de configuración.

Elige tu framework por la forma del flujo de trabajo. Elige tu modelo por el dominio. Ajusta para que el modelo hable tus herramientas nativamente. Esa es la receta de producción en 2026.

Lectura Adicional

• Pydantic AI en Dispositivo: Ajusta Qwen3-4B para Agentes Móviles con Seguridad de Tipos — el pipeline completo de Pydantic AI más modelo ajustado en el dispositivo para aplicaciones móviles
• FunctionGemma y el Auge de los Modelos Dedicados de Tool-Calling — cuando un especialista de tool-calling de 270M supera a un agente ajustado de 7B
• Fine-Tuning para Tool Calling: Cómo Construir Agentes de IA Confiables — la guía completa para entrenar modelos que impulsan frameworks de agentes de forma confiable