Claude Agent SDK y LangGraph construyen agentes de IA, pero no coinciden en quién decide el siguiente paso. Esta comparación analiza el bucle del agente frente al grafo explícito, las herramientas integradas, el estado y la persistencia, la aprobación humana, la dependencia de un modelo y los costos de producción, y después da una regla sencilla para elegir entre ambos.
Elegir entre el Claude Agent SDK y LangGraph depende de una pregunta: ¿debe decidir el modelo qué pasa después, o tu código? El Claude Agent SDK entrega a tu aplicación el mismo bucle de agente que funciona dentro de Claude Code, así que Claude elige sus propias herramientas y pasos. LangGraph, en cambio, te ofrece una máquina de estados. Tú dibujas los nodos y las aristas, y el modelo hace el trabajo en cada nodo. Ambos construyen agentes de IA capaces. Simplemente no están de acuerdo en quién lleva el volante.
Esta comparación analiza el flujo de control, las herramientas, el estado, la aprobación humana, la elección de modelo y los costos de producción, para que elijas uno antes de escribir mil líneas del código equivocado.
Si tu agente consiste sobre todo en «dale a un modelo capaz buenas herramientas y deja que trabaje», empieza con el Claude Agent SDK. Si tu agente es un flujo de trabajo con etapas fijas, ramificaciones, reintentos y puntos de auditoría, empieza con LangGraph. La mayor parte de la confusión desaparece en cuanto encajas tu proyecto en una de esas dos formas.
Esta es la comparación lado a lado antes de los detalles:
| Pregunta | Claude Agent SDK | LangGraph |
|---|---|---|
| Idea central | Bucle de agente listo para usar en torno a Claude | Grafo de nodos, aristas y estado compartido |
| Quién elige el siguiente paso | El modelo | Tu grafo, con el modelo trabajando dentro de los nodos |
| Modelos | Claude, mediante la API de Anthropic, Amazon Bedrock o Google Vertex AI | Cualquier modelo con una integración de LangChain |
| Herramientas integradas | Lectura, escritura, edición, shell, búsqueda y obtención web | Ninguna; tú vinculas las tuyas |
| Estado | Sesiones con gestión automática del contexto | Estado tipado con un checkpoint por paso |
| Aprobación humana | Modos de permiso y hooks | Interrupciones y reanudación |
| Lenguajes | Python, TypeScript | Python, JavaScript y TypeScript |
| Mejor opción para | Agentes de programación, de investigación, de archivos y de shell | Flujos de trabajo empresariales de varias etapas con enrutamiento estricto |
💡 Regla general: cuenta los pasos que puedes escribir de antemano. Si los podrías anotar en una servilleta, dibuja un grafo. Si la respuesta honesta es «depende de lo que encuentre el agente», usa el bucle.
Anthropic lo publicó primero como Claude Code SDK y después lo renombró Claude Agent SDK, porque la gente lo usaba para mucho más que programar. Instalas claude-agent-sdk para Python o @anthropic-ai/claude-agent-sdk para TypeScript, llamas a query() con un prompt y algunas opciones, y recibes mensajes en streaming mientras el agente trabaja.
Por debajo está el mismo arnés que impulsa Claude Code. Envía contexto a Claude, ejecuta las herramientas que Claude pida, devuelve los resultados y repite hasta que Claude decide que el trabajo está terminado. Esto es lo que obtienes sin escribirlo tú:
CLAUDE.md y skills cargados desde el sistema de archivosLangGraph viene del equipo de LangChain y está pensado para agentes de larga duración con estado. Alcanzó su versión 1.0 a finales de 2025. Defines un esquema de estado, escribes los nodos como funciones normales, los conectas con aristas fijas o condicionales y compilas el resultado en un grafo ejecutable.
El grafo es el producto. Cada paso lee el estado compartido y devuelve una actualización, así que puedes ver exactamente en qué punto está una ejecución en cualquier momento. Los checkpointers guardan ese estado después de cada paso, y eso es lo que hace posible pausar, reanudar y reproducir. LangGraph es independiente del modelo: cualquier modelo de chat con una integración de LangChain encaja en un nodo, y LangSmith añade trazabilidad cuando quieres observar las ejecuciones.
Aquí está la verdadera bifurcación. En el SDK, Claude elige el siguiente movimiento en cada turno: leer otro archivo, ejecutar un comando, buscar en la web o detenerse. En LangGraph, las aristas eligen, y el modelo solo decide dentro del nodo que le han asignado.
| Rasgo | Bucle (Claude Agent SDK) | Grafo (LangGraph) |
|---|---|---|
| Previsibilidad | Menor, el modelo improvisa | Mayor, los caminos están declarados |
| Flexibilidad | Alta, maneja tareas que no previste | Limitada por las aristas que dibujaste |
| Depuración | Lee la transcripción de las llamadas a herramientas | Inspecciona el estado en cada nodo |
| Tiempo hasta la primera demo | Minutos | Una tarde para un grafo real |
| Fallo típico | Divagar, llamadas extra a herramientas | Un camino rígido con una rama que falta |
Ninguno de los dos enfoques es erróneo. Un bucle maneja las sorpresas, como un reporte de error que resulta ser un problema de configuración. Un grafo garantiza el proceso, como «valida siempre la dirección antes de cobrar la tarjeta».
Tomemos un trabajo sencillo: auditar un módulo de autenticación e informar de las funciones más arriesgadas. Así se hace con el Claude Agent SDK:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
options = ClaudeAgentOptions(
allowed_tools=["Read", "Grep", "Glob"],
system_prompt="You review code for security risks.",
)
async for message in query(
prompt="Audit the auth module and list the three riskiest functions.",
options=options,
):
print(message)
asyncio.run(main())
Eso es todo el programa. Claude decide qué archivos abrir, en qué orden y cuándo ha visto lo suficiente.
Ahora, el mismo trabajo en LangGraph, con un paso de revisión garantizado. Los auxiliares run_audit y passes_checks son marcadores de posición para tu propio código:
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
class State(TypedDict):
question: str
report: str
approved: bool
def audit(state: State) -> dict:
return {"report": run_audit(state["question"])}
def review(state: State) -> dict:
return {"approved": passes_checks(state["report"])}
def route(state: State) -> str:
return "done" if state["approved"] else "retry"
builder = StateGraph(State)
builder.add_node("audit", audit)
builder.add_node("review", review)
builder.add_edge(START, "audit")
builder.add_edge("audit", "review")
builder.add_conditional_edges("review", route, {"done": END, "retry": "audit"})
graph = builder.compile()
Aquí tú escribiste el proceso: cada informe se revisa, y una revisión fallida siempre vuelve atrás. El modelo nunca puede saltarse la revisión. El precio es el trabajo de infraestructura: más código, más decisiones y un grafo que mantener.
El SDK gestiona la delegación con subagentes. Defines cada ayudante con una descripción, un prompt y una lista restringida de herramientas, y el agente principal les pasa el trabajo. Cada subagente se ejecuta en su propio contexto, lo que mantiene limpia la ventana del agente principal. Es rápido de configurar, y las decisiones de delegación siguen en manos de Claude.
LangGraph modela lo mismo como subgrafos o como un nodo supervisor que enruta hacia nodos trabajadores. Los traspasos son explícitos, el estado compartido está tipado y puedes probar cada trabajador por separado. Cuando cinco agentes deben cooperar en un orden fijo, esa explicitud compensa. Cuando los agentes son especialistas independientes, puede resultar burocrático.
El SDK llega con una caja de herramientas completa, por eso resulta productivo desde el primer día. Un agente que puede leer un repositorio, editar archivos y ejecutar pruebas funciona en cuanto pasas allowed_tools. Las herramientas personalizadas se incorporan mediante servidores MCP en proceso o cualquier servidor MCP externo. Restringir el acceso importa tanto como llenar la caja: Bash es potente, así que dáselo solo a los agentes que lo necesiten.
LangGraph empieza con un banco de trabajo vacío. Las herramientas son funciones que vinculas a un modelo dentro de un nodo, y un nodo de herramientas preconstruido ejecuta las llamadas. Eso significa más configuración y más libertad: una herramienta puede ser cualquier cosa que Python o JavaScript puedan invocar, y tú decides a qué puede acceder cada nodo.
El SDK registra una sesión. Cada ejecución tiene un ID, y puedes reanudarla más tarde con el historial completo de la conversación, o bifurcarla para probar otra dirección. El arnés compacta los turnos antiguos para que los trabajos largos no se ahoguen en el contexto.
LangGraph registra un checkpoint por cada paso, agrupados por hilo. Puedes reanudar un hilo tras un fallo, reproducir desde un paso anterior o editar el estado y bifurcar desde ahí. Un almacén aparte guarda la memoria a largo plazo compartida entre hilos, como las preferencias del usuario.
💡 La diferencia: una sesión recuerda la conversación. Un checkpoint recuerda en qué punto está el flujo de trabajo. Si tu agente debe reiniciarse en el paso cuatro de siete en otro servidor, los checkpoints son la opción natural.
Los agentes que tocan dinero, datos de producción o correos de clientes necesitan a una persona en el proceso. Ambas herramientas lo admiten, en lugares distintos.
El SDK protege las acciones. Los modos de permiso van desde pedir confirmación para todo, hasta aceptar automáticamente las ediciones de archivos, pasando por un modo de planificación de solo lectura. Puedes permitir o denegar herramientas por nombre, proporcionar un callback que apruebe cada llamada y añadir hooks que se ejecutan antes de una herramienta y pueden bloquearla o reescribirla. Un hook que rechace cualquier comando de shell que contenga rm -rf es una función corta.
LangGraph protege las etapas. Un nodo llama a interrupt(), el grafo se detiene y el checkpointer guarda todo. Horas o días después, una persona responde, reanudas con un Command y la ejecución continúa desde el mismo punto, incluso en otra máquina. Eso hace que las colas de aprobación, como los reembolsos por encima de un umbral, sean sencillas de construir.
¿Cuál es mejor? Si te preocupa qué puede hacer el agente, encajan los permisos del SDK. Si te preocupa cuándo debe firmar una persona en un proceso empresarial, encajan las interrupciones de LangGraph.
El Claude Agent SDK ejecuta modelos Claude. Puedes llegar a ellos mediante la API de Anthropic o a través de proveedores en la nube como Amazon Bedrock y Google Vertex AI, pero no puedes cambiar a otro proveedor. Si de todos modos Claude es tu elección, eso es una ventaja, porque el arnés está afinado para la forma en que Claude usa las herramientas.
LangGraph es neutral. Puedes ejecutar un nodo en un modelo rápido y barato para el enrutamiento, otro en un modelo de razonamiento potente, y cambiar cualquiera con un cambio de configuración. Antes de comprometerte, ejecuta el mismo prompt de agente en varios modelos de PicassoIA: Claude Sonnet 5 para programación equilibrada y uso de herramientas, Claude Opus 4.7 para razonamiento más exigente, Claude Fable 5 para tareas de programación complejas, GPT 5.6 Sol, Gemini 3.1 Pro y Kimi K2.6, que se presenta como pensado para construir agentes. Si un proveedor gana claramente en tu tarea, la pregunta sobre la dependencia se responde sola.
Un agente del SDK ejecuta el entorno de ejecución de Claude Code, así que despliega el agente donde pueda ejecutarse ese entorno, normalmente un contenedor con un sistema de archivos restringido. Como el agente puede ejecutar comandos de shell, el aislamiento en sandbox no es opcional. Para la visibilidad obtienes el flujo de mensajes, las transcripciones guardadas y los hooks que registran cada llamada a una herramienta.
Los agentes de LangGraph son servicios sencillos. LangSmith traza cada nodo, un estudio visual te permite recorrer el estado paso a paso, y existe una opción de despliegue alojado para grafos de larga duración. La ejecución duradera mediante checkpoints significa que un redespliegue o un fallo no borra una ejecución en curso.
Ambos son gratuitos de instalar. La factura son los tokens del modelo más el alojamiento. Los bucles tienden a costar más cuando la tarea es vaga, porque el modelo puede abrir diez archivos cuando bastarían tres. Los grafos te permiten limitarlo: envía los pasos sencillos a un modelo pequeño, acota los reintentos con un límite de recursión y omite el modelo por completo en los pasos deterministas. Por otro lado, un bucle a menudo llega antes a un resultado funcional en trabajos abiertos, porque nadie tiene que diseñar primero el grafo.
No son mutuamente excluyentes. Un patrón habitual usa LangGraph como flujo de trabajo externo, con un nodo que llama al Claude Agent SDK para la parte abierta, como «arregla las pruebas que fallan». El grafo se encarga del enrutamiento, la aprobación y los reintentos. El SDK se encarga del tramo complicado del medio.
| Tu situación | Mejor opción |
|---|---|
| Desarrollador independiente que lanza un agente de programación esta semana | Claude Agent SDK |
| Flujo de soporte con aprobaciones de reembolsos | LangGraph |
| Asistente de investigación construido sobre Claude | Claude Agent SDK |
| Pipeline que combina modelos de tres proveedores | LangGraph |
| Paso de reparación abierto dentro de un flujo regulado | Ambos |
💡 Vale la pena recordar: ambos proyectos publican cambios con rapidez. Revisa las notas de versión de cada uno antes de fiarte de cualquier detalle de aquí, sobre todo de los nombres y valores por defecto de las opciones.
La mejor manera de zanjar un debate sobre frameworks es probarlo con algo pequeño. Lo mismo vale para lo visual. Tu proyecto de agente necesitará una imagen principal para el README, una foto para la publicación de lanzamiento o un moodboard para la página del producto, y Picasso IA lo hace rápido.
Prueba tu prompt de agente con Claude Sonnet 5 en PicassoIA:
Después crea algo que acompañe al proyecto. Describe una escena, por ejemplo un equipo de software frente a una pizarra blanca con luz suave de mañana, fotografiado en película de 35 mm, y genéralo en segundos. Explora todos los modelos disponibles en picassoia.com/en/all-models, prueba tres o cuatro prompts y comprueba hasta dónde llega una sola frase. Tu próximo agente merece un lanzamiento con buena imagen.
Elige tu idioma
