LangGraph 1.0: Framework de Orquestación Multi-Agente con Estado

1. ¿Qué es LangGraph?

LangGraph es un framework open-source de LangChain para construir agentes AI con estado y múltiples pasos como grafos dirigidos. En vez de escribir cadenas lineales o loops de agente monolíticos, modelas el workflow de tu agente como un grafo de nodos (funciones) y aristas (transiciones), con estado tipado fluyendo a través de cada paso. Esto te da control explícito sobre ramificación, loops, paralelismo y manejo de errores -- las propiedades exactas que los agentes de producción necesitan pero que los loops de agente ad-hoc carecen.

El framework es agnóstico al modelo: funciona con cualquier proveedor LLM (OpenAI, Anthropic, Google, modelos open-source vía Ollama). LangGraph está disponible para Python y TypeScript, con SDKs oficiales mantenidos por el equipo de LangChain. A julio de 2026, el paquete Python (langgraph en PyPI, actualmente v1.2.9) es la librería de orquestación de agentes más adoptada en el ecosistema Python, con la organización LangChain superando 142,000 estrellas en GitHub a través de sus repositorios.

LangGraph se ubica en una capa específica del stack de agentes AI: maneja la orquestación (qué corre cuándo, en qué orden, con qué estado) pero delega las llamadas al modelo, ejecución de herramientas e integraciones externas a las librerías que prefieras. Puedes usar las abstracciones de LangChain, llamar SDKs de proveedores directamente, o mezclar ambos. Esta composabilidad es la razón por la que LangGraph funciona bien junto con agentes del Claude Agent SDK, servidores MCP y otros frameworks en vez de reemplazarlos.

2. LangGraph 1.0: Qué Cambió

LangGraph 1.0 (disponible de forma general desde el 22 de octubre de 2025) marca la transición de iteración rápida a estabilidad de producción. El release codifica patrones que emergieron de miles de despliegues de producción en APIs estables y documentadas con garantías de compatibilidad retroactiva dentro de la versión mayor. Todas las APIs sin prefijos experimentales son ahora consideradas estables y listas para producción.

Los cambios clave en 1.0 incluyen: interfaces de checkpointer estables con serialización estandarizada en todos los backends (SQLite, PostgreSQL, Redis), primitivas interrupt/Command de primera clase para workflows human-in-the-loop reemplazando la API anterior de breakpoints, streaming refinado con modos de streaming a nivel de token y de nodo, composición de subgrafos mejorada para arquitecturas multi-agente, y reducers de estado tipados que permiten a múltiples nodos actualizar estado compartido sin conflictos.

La política de releases ahora sigue versionado semántico estrictamente: releases mayores cada 6-12 meses para estabilidad, releases menores cada 1-2 meses para features, y parches semanales para correcciones. Esta madurez hace a LangGraph viable para equipos enterprise que necesitan rutas de upgrade predecibles y soporte a largo plazo.

3. Conceptos Core: StateGraph, Nodos, Aristas

LangGraph modela cada workflow de agente como un StateGraph -- un grafo dirigido donde estado tipado fluye a través de nodos conectados por aristas. Entender estas tres primitivas es la base para todo lo demás en el framework.

from langgraph.graph import StateGraph, START, END
from typing import TypedDict, Annotated
from langgraph.graph.message import add_messages

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]
    next_action: str

def call_model(state: AgentState) -> dict:
    response = llm.invoke(state["messages"])
    return {"messages": [response]}

def should_continue(state: AgentState) -> str:
    last = state["messages"][-1]
    if last.tool_calls:
        return "tools"
    return END

graph = StateGraph(AgentState)
graph.add_node("agent", call_model)
graph.add_node("tools", tool_node)
graph.add_edge(START, "agent")
graph.add_conditional_edges("agent", should_continue)
graph.add_edge("tools", "agent")
app = graph.compile()

4. Checkpointing y Persistencia de Estado

La capa de persistencia integrada de LangGraph guarda un snapshot del estado del grafo en cada paso de ejecución, organizados en threads. Cuando compilas un grafo con un checkpointer, cada ejecución de nodo crea un checkpoint que puede ser inspeccionado, reproducido o reanudado. Esta es la base para memoria conversacional, workflows human-in-the-loop, tolerancia a fallos y time-travel debugging.

Tres backends de checkpointer de grado producción están disponibles:

from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.checkpoint.postgres import PostgresSaver

# Local development
with SqliteSaver.from_conn_string("checkpoints.db") as checkpointer:
    app = graph.compile(checkpointer=checkpointer)
    result = app.invoke(
        {"messages": [("user", "Plan my trip")]},
        config={"configurable": {"thread_id": "trip-123"}}
    )

# Production with PostgreSQL
async with PostgresSaver.from_conn_string(DATABASE_URL) as checkpointer:
    app = graph.compile(checkpointer=checkpointer)
    # Resume from last checkpoint
    state = await app.aget_state({"configurable": {"thread_id": "trip-123"}})

5. Patrones Human-in-the-Loop

LangGraph provee primitivas de primera clase para pausar la ejecución del agente, presentar información a un humano y reanudar con su input. Esto está construido sobre el sistema de checkpointing: cuando un grafo alcanza una llamada interrupt(), guarda el estado en el checkpointer y retorna el control al llamador. El llamador recolecta el input humano y reanuda el grafo con un Command conteniendo la respuesta.

Tres patrones primarios cubren la mayoría de escenarios human-in-the-loop:

from langgraph.types import interrupt, Command

def sensitive_action(state):
    # Pause and ask human for approval
    decision = interrupt({
        "action": "delete_records",
        "count": state["record_count"],
        "question": "Approve deletion of these records?"
    })
    if decision["approved"]:
        return execute_deletion(state)
    return {"messages": [("system", "Deletion cancelled by user.")]}

# Resume with human input
app.invoke(
    Command(resume={"approved": True}),
    config={"configurable": {"thread_id": "cleanup-456"}}
)

6. Orquestación Multi-Agente

LangGraph provee tres arquitecturas para coordinar múltiples agentes especializados. Cada arquitectura balancea entre control y autonomía, y puedes combinarlas en jerarquías donde un supervisor delega a swarms o cadenas secuenciales.

from langgraph_supervisor import create_supervisor
from langgraph.prebuilt import create_react_agent

# Specialized worker agents
researcher = create_react_agent(model, tools=[search, wiki])
coder = create_react_agent(model, tools=[run_code, read_file])
reviewer = create_react_agent(model, tools=[lint, test])

# Supervisor orchestrates workers
supervisor = create_supervisor(
    model=model,
    agents=[researcher, coder, reviewer],
    prompt="Route tasks to the appropriate specialist."
)
app = supervisor.compile()

7. LangGraph Platform (LangSmith Deployment)

LangGraph Platform (renombrado a LangSmith Deployment en octubre 2025) es la capa de infraestructura gestionada para desplegar y escalar agentes de larga duración con estado. Maneja la complejidad operativa que los agentes de producción demandan: estado persistente entre requests, escalado horizontal, recuperación de fallos y monitoreo -- sin requerir que construyas esta infraestructura tú mismo.

Cuatro opciones de despliegue están disponibles:

8. Trazas con LangSmith

LangSmith es la plataforma de observabilidad para agentes LangGraph. Cuando configuras LANGCHAIN_TRACING_V2=true y provees una API key, cada ejecución del grafo se traza automáticamente -- sin instrumentación custom requerida. Las trazas capturan el árbol completo de ejecución: qué nodos corrieron, en qué orden, con qué inputs y outputs, cuánto tardó cada paso y cuántos tokens se consumieron.

La vista de trazas en LangSmith muestra un árbol jerárquico representando la ejecución completa. Puedes profundizar en ejecuciones individuales de nodos, inspeccionar estado en cada checkpoint, ver prompts y completions del LLM, y ver argumentos y resultados de llamadas a herramientas. Para debugging en producción, puedes filtrar trazas por latencia, estado de error, uso de tokens o metadata custom. El Insights Agent (disponible para LangSmith self-hosted) analiza automáticamente las trazas para detectar patrones de uso, comportamientos comunes de agentes y modos de falla.

LangSmith no está limitado a LangGraph -- traza aplicaciones construidas con el OpenAI SDK, Anthropic SDK, Vercel AI SDK, LlamaIndex o implementaciones custom. Pero la integración con LangGraph es la más profunda: los logs de servidor de LangSmith Deployment están vinculados directamente a las vistas de trazas, dándote una ventana única a tanto el comportamiento a nivel de aplicación como los eventos a nivel de infraestructura.

# Enable tracing -- that's it
import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "lsv2_..."
os.environ["LANGCHAIN_PROJECT"] = "my-agent"

# Every graph.invoke() and graph.astream() is now traced
result = app.invoke(
    {"messages": [("user", "Analyze Q1 revenue")]},
    config={"configurable": {"thread_id": "analysis-789"}}
)
# View trace at: https://smith.langchain.com/

9. Comparación de Frameworks

LangGraph ocupa una posición específica en el paisaje de frameworks de agentes. Así se compara con los otros frameworks principales a abril de 2026:

Los frameworks son cada vez más interoperables en vez de mutuamente excluyentes. Google ADK puede tratar un agente LangGraph como AgentTool, LangGraph puede llamar agentes ADK como subgrafos vía API, y ambos soportan el protocolo MCP para integración de herramientas. Elige basado en tu restricción principal: LangGraph para orquestación compleja con estado, Claude Agent SDK para desarrollo MCP-nativo con seguridad primero, OpenAI SDK para el camino más rápido a un agente funcionando, Google ADK para agentes multimodales nativos de GCP, y CrewAI para prototipado rápido multi-agente con el soporte de protocolos más amplio.

10. Patrones de Producción

Desplegar agentes LangGraph a producción requiere patrones para manejo de errores, reintentos, observabilidad y gestión de recursos. Estos patrones aprovechan la estructura de grafo de LangGraph para hacer el manejo de fallos explícito y testeable en vez de escondido en bloques try-catch.

from langgraph.pregel import RetryPolicy

# Per-node retry with exponential backoff
retry = RetryPolicy(
    max_attempts=3,
    initial_interval=1.0,
    backoff_factor=2.0,
    retry_on=lambda e: isinstance(e, (TimeoutError, RateLimitError))
)

graph.add_node("api_call", call_external_api, retry=retry)

# Step limit to prevent runaway loops
app = graph.compile(
    checkpointer=checkpointer,
    recursion_limit=50  # Max node executions per invocation
)

11. langgraph-checkpoint v4.1 y Estrategias TTL

El release langgraph-checkpoint v4.0.2 (abril 2026) introduce la estrategia TTL keep_latest para poda automática de checkpoints. En vez de acumular historial de estado sin límites, configuras una política de retención que mantiene solo los N checkpoints más recientes por thread, con snapshots anteriores purgados de forma asíncrona. Esto reduce drásticamente los costos de almacenamiento para agentes de alto volumen en producción ejecutando miles de threads. El release v4.1.0 (12 de mayo de 2026) agregó DeltaChannel (beta): los canales que crecen con el tiempo (como listas largas de mensajes) almacenan solo el delta incremental de cada paso en vez de re-serializar el valor acumulado completo, con un snapshot completo forzado cada K supersteps. El release actual es v4.1.1 (22 de mayo de 2026).

El nuevo RemoteCheckpointer habilita checkpointing de subgrafos entre procesos. Cuando un grafo supervisor delega a un subgrafo corriendo en un proceso separado (o incluso en una máquina diferente), el RemoteCheckpointer sincroniza el estado vía una capa de transporte HTTP. Esto elimina la limitación anterior donde el estado del subgrafo solo era accesible desde el proceso padre, habilitando arquitecturas multi-agente verdaderamente distribuidas con escalado independiente de agentes supervisor y worker.

from langgraph.checkpoint.postgres import PostgresSaver
from langgraph.checkpoint.base import CheckpointConfig

# TTL strategy: keep only latest 50 checkpoints per thread
config = CheckpointConfig(
    ttl_strategy="keep_latest",
    keep_latest=50
)
checkpointer = PostgresSaver.from_conn_string(
    conn_string="postgresql://...",
    config=config
)

# RemoteCheckpointer for subgraph state across processes
from langgraph.checkpoint.remote import RemoteCheckpointer
sub_ckpt = RemoteCheckpointer(endpoint="https://worker-agent:8080/checkpoints")