OpenAI Agents SDK vs LangGraph: comparación práctica para elegir framework

Un equipo arma un prototipo de agente de soporte con LangGraph. Cuando empieza a funcionar, descubre que la mayoría de los nodos hacen lo mismo: llamar a un modelo y luego a una herramienta. El código está ordenado, pero el boilerplate pesa. Entonces aparece la pregunta: ¿se puede cambiar a OpenAI Agents SDK para quitar esa capa?

Otro caso es más delicado. Un agente de reporting corre 20 minutos cada día y, a mitad de camino, debe esperar a que una persona apruebe el SQL antes de continuar. Ahí “menos código” deja de ser el único criterio. Pausar, reanudar y auditar se vuelven centrales. OpenAI Agents SDK tiene sessions y guardrails, pero ¿puede reemplazar los checkpoints e interrupts de LangGraph?

Los dos escenarios llevan a la misma pregunta: OpenAI Agents SDK parece ligero, pero ¿sirve para reemplazar a LangGraph o solo para una parte del trabajo? La decisión real es si tu agente solo necesita modelos, herramientas y delegación, o si ya necesita estado persistente, pausas humanas, ejecución reanudable y replay para auditoría.

Primero aclara la capa: no son la misma abstracción

Antes de hablar de reemplazo, conviene separar el rol de cada framework. OpenAI describe Agents SDK como un toolkit ligero, fácil de usar y con pocas abstracciones para crear aplicaciones agentic. Su centro es el agent loop, las llamadas a herramientas, los handoffs, los guardrails y el tracing. LangGraph se define como infraestructura de orquestación de bajo nivel para workflows largos y con estado. Su centro es el grafo de estado explícito, la persistencia con checkpoints, interrupts, resume, time travel y fault tolerance.

Uno se parece más a un runtime de conversación y delegación. El otro se parece más a una máquina de estados dirigida. La diferencia de abstracción queda así:

La tabla muestra el punto central: Agents SDK está más cerca de primitivas de runtime de agente, mientras LangGraph está más cerca de orquestación de workflow con estado. Si solo necesitas un agent loop que llame herramientas y delegue a un agente especialista de vez en cuando, Agents SDK puede bastar. Si la tarea debe pausar, reanudarse, auditarse o continuar después de un fallo, los checkpoints e interrupts de LangGraph son la parte importante.

No se trata de cuál es “más potente”. Trabajan en capas distintas. Agents SDK es como un SDK con tracing para ejecutar agentes. LangGraph es como un motor de máquina de estados con persistencia. Si tu proceso se puede dibujar como transiciones de estado claras, LangGraph suele encajar mejor. Si es sobre todo “modelo + herramientas + escalado ocasional”, Agents SDK puede ser más liviano. Para entender por qué un prompt no reemplaza fácilmente una máquina de estados, revisa máquinas de estado de agentes y límites del workflow.

Matriz de capacidades: 10 dimensiones prácticas

Que estén en capas distintas no impide compararlos en capacidades concretas. Esta tabla resume 10 dimensiones de ingeniería:

Las diferencias más importantes están en persistencia de estado, recuperación ante fallos y workflows reproducibles. Las sessions de Agents SDK sirven para continuidad de conversación. Los checkpointers de LangGraph guardan todo el estado del grafo: historial de nodos, variables intermedias y entradas externas en espera. Si un agente de reporting se cae a mitad de ejecución, Agents SDK normalmente debe empezar desde cero. LangGraph puede continuar desde el último checkpoint y evitar repetir pasos ya completados.

Otra diferencia clave es HITL. Agents SDK tiene guardrails y HITL API, útiles para validar entradas y salidas, pero el mecanismo de guardrail es un tripwire: cuando se dispara, la ejecución se detiene. Los interrupts de LangGraph son pausas de máquina de estados. interrupt() puede pausar dentro de un nodo, el checkpointer guarda el estado y luego se reanuda con Command(resume=...). Eso permite pausar antes de un tool call, esperar aprobación humana y continuar. Los guardrails de Agents SDK sirven más para “detener si la entrada no corresponde” que para “pausar, revisar y seguir”. Para una frontera más completa, consulta diseño de aprobaciones human-in-the-loop para agentes.

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

La tercera diferencia es replay. El time travel de LangGraph permite volver a cualquier checkpoint, inspeccionar estado y ruta de ejecución, y depurar o auditar. El tracing de Agents SDK puede visualizar el camino, pero no volver a un estado histórico y reejecutar desde ahí. Si necesitas responder “¿por qué tomó esta rama hace dos horas?”, LangGraph encaja mejor.

Qué ofrece Agents SDK: primitivas centrales

OpenAI Agents SDK se organiza alrededor de cinco primitivas: Agents, Handoffs, Guardrails, Tracing y Sessions/HITL/MCP. En la práctica:

Agents: un agente combina un LLM, instrucciones, herramientas y comportamiento runtime opcional. Ese comportamiento incluye handoffs a otros agentes, guardrails para validar input/output y structured outputs para forzar formatos. Agent y Runner trabajan juntos para que el SDK gestione el agent loop, turns, tool calls, guardrail checks y delegaciones.

Handoffs: un handoff permite que un agente delegue trabajo a otro. En la práctica, el agente destino se expone al LLM como una herramienta. handoff() permite configurar el agente destino, nombre y descripción de herramienta, on_handoff, input_type, input_filter e is_enabled. Encaja bien con especialistas: un agente de soporte clasifica el problema y lo deriva a soporte técnico o consulta de pedidos.

Guardrails: los guardrails funcionan en dos niveles: input y output. Los input guardrails revisan la entrada antes de que llegue al agente. Los output guardrails revisan la respuesta antes de devolverla. Un tripwire detiene la ejecución. Sirve para “detener si la entrada está fuera de alcance” o “bloquear una salida con información sensible”. Los ejemplos oficiales usan un modelo más rápido para comprobar si la petición está dentro del alcance.

Tracing: el SDK incluye tracing para LLM generations, tool calls, handoffs, guardrail checks y custom events dentro de un agent run. Cada span registra tiempos y metadata, útil para debug, visualización y monitoreo de workflows. El tracing viene activado por defecto, y trace_include_sensitive_data controla si se registran campos sensibles.

Sessions, HITL y MCP tools: las sessions dan continuidad de conversación: varios runs con el mismo session_id comparten historial. La HITL API puede esperar entrada externa durante la ejecución, pero su modelo de interrupción no es la misma abstracción que los interrupts de LangGraph. Los MCP tools permiten que un agente llame herramientas expuestas por MCP servers, gestionadas como function tools.

Estas primitivas cubren agent loop, tool calling, delegación, validación, tracing y continuidad de conversación. No ofrecen grafo de estado explícito, persistencia con checkpoints, interrupts, resume, time travel ni fault tolerance. Si tu caso es “modelo + herramientas + delegación ocasional”, Agents SDK puede bastar. Si necesitas “pausa para aprobación + reanudación + seguir tras fallo + auditoría de estado”, LangGraph encaja mejor.

Fortalezas de LangGraph: mecanismos de estado

Las fortalezas de LangGraph están en gestión de estado y recuperación: Checkpointers, Interrupts, Time travel, Fault tolerance y Stores. En la práctica:

Checkpointers: guardan thread graph state como checkpoints. Incluyen historial de nodos, variables intermedias, entradas externas pendientes y posición actual. Cada checkpoint es un snapshot completo de estado, usado para continuidad de conversación, HITL, time travel y fault tolerance. La documentación oficial diferencia sessions de Agents SDK y checkpointers de LangGraph: sessions es continuidad de conversación; checkpointers son snapshots del estado del grafo.

Interrupts: interrupt() puede pausar la ejecución dentro de un graph node. El checkpointer guarda el estado actual y espera entrada externa. Se reanuda con Command(resume=...), y el mismo thread_id actúa como cursor persistente. La documentación enumera patrones como approval workflows, review/edit state, interrupting tool calls y validating human input. No es lo mismo que un guardrail tripwire de Agents SDK: interrupt pausa la máquina de estados; guardrail detiene la ejecución.

Time travel: permite volver a cualquier checkpoint y revisar el estado y la ruta de ejecución de ese momento. Sirve para auditoría, depuración y reproducción de problemas, por ejemplo “¿por qué tomó esta rama hace dos horas?”. El tracing de Agents SDK muestra la ruta, pero no reejecuta desde un estado histórico.

Fault tolerance: es la capacidad de continuar después de un fallo. Si un agente de reporting se cae a mitad de ejecución, LangGraph puede reanudar desde el último checkpoint y evitar repetir pasos completados. Agents SDK no tiene fault tolerance integrada, así que normalmente se reinicia desde el principio.

Stores: guardan datos de largo plazo entre threads, como preferencias de usuario, historial o estado de negocio. La documentación separa stores de checkpointers: checkpointers guardan thread graph state; stores guardan datos persistentes entre threads. Si varios agent runs deben compartir estado, stores es la capa adecuada.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Estos mecanismos hacen que LangGraph sea más adecuado para workflows largos y con estado: tareas largas, múltiples ramas, ejecución reanudable, estado auditable e intervención humana. Si tu proyecto ya necesita eso, la complejidad de LangGraph vale la pena. Si solo es un tool agent simple o un specialist handoff, Agents SDK puede ser más liviano.

Cuándo usar Agents SDK

Según la matriz y las primitivas, Agents SDK encaja mejor en estos escenarios:

1. Tool agents simples: búsqueda, resumen y escalado ocasional a una persona. Por ejemplo, un agente de Q&A de base de conocimiento interna recupera documentos, resume la respuesta y, si no está seguro, sugiere contactar a soporte. No necesita recuperación de estado compleja ni flujos de aprobación; tools + handoffs + guardrails pueden bastar.

2. Handoff a varios especialistas: escenarios donde se delega a varios agentes expertos. Un agente de soporte clasifica el tipo de problema y luego delega a soporte técnico, consulta de pedidos o reembolsos. Los handoffs de Agents SDK son literalmente “agent as tool”, así que este patrón encaja bien.

3. Prototipos rápidos: proyectos que necesitan validar una idea sin dibujar un grafo de estado explícito desde el inicio. Agents SDK requiere menos código y arranca más rápido. Si el prototipo demuestra que no hacen falta checkpoints ni interrupts, puede pasar a producción sobre Agents SDK.

4. Ajuste con el ecosistema OpenAI: si el proyecto usa sobre todo modelos OpenAI, Responses API u OpenAI hosted tools, Agents SDK es el toolkit oficial y la integración es más fluida. Agentes de voz en tiempo real, sandbox agents u herramientas alojadas por OpenAI son ejemplos naturales.

5. Otra capa ya gestiona el estado: si el proyecto ya tiene base de datos de negocio, queue o motor de workflow, Agents SDK puede ejecutar solo el agent loop. Un nodo usa Agents SDK para llamar herramientas, mientras la base de datos y la cola mantienen el estado.

El patrón común es claro: sin grafo de estado explícito, sin persistencia con checkpoints, sin interrupt + resume y sin time travel. Si tu proyecto coincide con ese perfil, empezar con Agents SDK puede ahorrar trabajo.

Cuándo conservar LangGraph

Si tu proyecto entra en estos casos, la complejidad de LangGraph suele justificarse:

1. Tareas largas (20+ minutos): agentes de reporting, procesamiento de datos o análisis complejos pueden correr más de 20 minutos y fallar o expirar a mitad de camino. Los checkpointers y fault tolerance de LangGraph permiten continuar desde el último checkpoint. Agents SDK no tiene fault tolerance integrada y suele repetir desde el inicio.

2. Aprobación humana obligatoria: escenarios de tool call interrupt, como borrar datos, enviar correos o cambiar permisos, requieren aprobación antes de continuar. Los interrupts de LangGraph pueden pausar antes del tool call, guardar estado con el checkpointer y reanudar con Command(resume=...). Los guardrails de Agents SDK son “disparar y detener”, no “pausar para revisión y continuar”.

3. Estado auditable obligatorio: algunos sistemas necesitan reproducir estados históricos, revisar rutas de ejecución o auditar decisiones. Una pregunta de cumplimiento como “¿por qué tomó esta rama hace dos horas?” exige más que un trace. Time travel de LangGraph vuelve a un checkpoint; tracing de Agents SDK muestra la ruta, pero no reejecuta desde un estado histórico.

4. La ejecución debe continuar tras fallos: si un agente se cae a mitad de run o falla la red, el sistema debe continuar en vez de empezar de cero. Fault tolerance de LangGraph reanuda desde checkpoint. Agents SDK empieza desde el principio. Si hay dependencias externas como llamadas API o escrituras en base de datos que no deben repetirse, esta diferencia importa mucho.

5. Múltiples ramas, routing condicional o máquina de estados de negocio: workflows con estados explícitos, condiciones o transiciones de negocio encajan mejor con LangGraph. Un pedido típico: pago exitoso -> envío; pago fallido -> cancelación; pago expirado -> intervención humana. Este flujo se entiende mejor como grafo de estado explícito; los handoffs de Agents SDK son para delegación, no para routing complejo.

El requisito común es estado explícito: persistencia con checkpoints, interrupts, resume, time travel o fault tolerance. Si tu proyecto lo necesita, la complejidad de LangGraph no es sobrecarga; es parte de la seguridad del sistema.

Decisión de reemplazo: checklist de cuatro pasos

Después de los escenarios, la decisión puede seguir poco clara. Usa esta checklist:

Paso 1: lista los requisitos principales

Divide el requisito en capacidades concretas: tool calling, recuperación de estado, aprobación humana, tareas largas, branching, replay de auditoría y recuperación ante fallos. No escribas solo “necesitamos un agente”. Hazlo específico. “Un agente de reporting corre 20 minutos, espera aprobación SQL y debe continuar tras un crash” son tres requisitos: tarea larga, aprobación y recuperación.

Paso 2: mapea los requisitos fuertes a la matriz

Toma la lista del paso 1 y llévala a las 10 dimensiones anteriores. “Tarea larga + aprobación + recuperación” corresponde a persistencia de estado, HITL y recuperación ante fallos. Agents SDK es débil o no existe en esas dimensiones, mientras LangGraph es fuerte. Si tus requisitos fuertes caen en los puntos débiles de Agents SDK, el reemplazo probablemente no conviene.

Paso 3: decide si necesitas un grafo de estado explícito

Haz una pregunta: ¿mi proceso puede dibujarse como transiciones de estado claras? Si sí, por ejemplo un pedido con éxito, fallo, timeout y pasos posteriores, el grafo de estado explícito de LangGraph encaja mejor. Si es más bien “modelo + herramientas + delegación ocasional” sin flujo fijo, Agents SDK puede ser más ligero.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Paso 4: evalúa la tolerancia del equipo a la complejidad

LangGraph exige diseñar grafos, estado y nodos. Si el equipo tiene poca tolerancia a esa complejidad, empieza con un prototipo en Agents SDK y agrega una capa de estado solo cuando sea necesaria. Si el equipo ya tiene experiencia con workflows o máquinas de estado, la complejidad de LangGraph puede no ser un problema.

Al terminar estos cuatro pasos, deberías poder elegir Agents SDK, LangGraph o una combinación. Si todavía estás comparando frameworks a nivel más amplio, usa la checklist de ingeniería de AI Agents 2026 como lectura complementaria.

Rutas de migración para proyectos LangGraph existentes

Si ya tienes un prototipo LangGraph y quieres reducir complejidad con Agents SDK, usa esta tabla:

Si ya usas Agents SDK y quieres saber cuándo subir a LangGraph, usa esta tabla de señales:

Ejemplo de patrón híbrido: no hace falta reemplazar todo. LangGraph gestiona el grafo de estado externo y un nodo usa Agents SDK para ejecutar un agente de tarea corta. Un agente de reporting puede usar LangGraph para el flujo principal: preparación de datos -> generación SQL -> aprobación humana -> ejecución de consulta -> exportación. Los nodos de generación SQL y exportación no necesitan checkpoints ni interrupts propios, así que pueden usar el agent loop y tool calls de Agents SDK mientras LangGraph conserva el estado.

La clave es la propiedad: LangGraph posee la capa de estado; Agents SDK puede ejecutar nodos cortos. No es una elección binaria, sino una forma de usar cada framework donde es más fuerte.

Conclusión

OpenAI Agents SDK y LangGraph no son una decisión binaria. La pregunta real es si necesitas una capa de estado. Si el proyecto solo necesita agent loop, tool calls, delegación y validación —por ejemplo Q&A de base de conocimiento, triage de soporte o un prototipo rápido— empieza con Agents SDK. Es más ligero y fácil de poner en marcha. Si el proyecto necesita recuperación de tareas largas, aprobación humana, auditoría de estado o continuación tras fallos —por ejemplo agentes de reporting, workflows de pedidos o procesos de cumplimiento— los checkpoints, interrupts, time travel y fault tolerance de LangGraph son capacidades necesarias.

No tienes que forzar un reemplazo. Un híbrido práctico es dejar que LangGraph gestione el grafo de estado externo y que Agents SDK ejecute nodos cortos. La decisión empieza por tus requisitos: lista las necesidades centrales, mapea las más fuertes a la matriz y decide si conservar, reemplazar o combinar.

Siguiente paso: si ya tienes un prototipo LangGraph, usa la tabla de migración para identificar qué nodos pueden pasar a Agents SDK. Si todavía estás eligiendo framework, usa la checklist de cuatro pasos para decidir primero si el proyecto necesita un grafo de estado explícito.