Agent framework vs agent harness: cuál elegir y cuándo

Hay dos formas de tener un agente de IA trabajando para ti. Una es montarlo pieza a pieza, como un mueble de esos que vienen con 47 tornillos y una llave Allen. La otra es llevarte uno que ya anda y ajustarle el asiento, los espejos y la radio.

La primera es un framework de agentes. La segunda, un harness de agentes.

Parece una distinción de glosario, pero decide cuánto código vas a mantener, quién controla el flujo (tú o el modelo) y lo que vas a tardar en tener algo útil delante. Y hay mucha confusión porque, en 2026, casi todos los productos se venden como “las dos cosas a la vez”.

En este artículo vas a encontrar:

• La diferencia en una frase y qué pieza aporta cada uno
• La infografía de “framework vs harness” explicada pieza a pieza
• Por qué la frontera entre los dos se ha vuelto tan borrosa (Claude Agent SDK, Deep Agents, Microsoft Agent Framework)
• El mismo agente montado con LangGraph y con el Claude Agent SDK, comparado punto por punto
• Cuándo te compensa cada uno, los errores típicos y una lista rápida para decidir

La diferencia en una frase: ensamblar o configurar ¶

Con un framework, escribes el agente. Con un harness, configuras el agente.

La frase la repiten casi todas las comparativas publicadas este año. Laurie Voss lo resume en el blog de Arize así: “un framework lo ensamblas; un harness se entrega como un agente que ya funciona y tú solo aportas el objetivo” (fuente: Arize, 2026). TrueFoundry lo dice todavía más corto: los frameworks son para construir agentes y los harnesses, para ejecutarlos.

La línea divisoria más clara es el bucle de ejecución. Plane lo señala en su comparativa: el loop de ejecución “suele ser la frontera más nítida” (fuente: Plane, 2026). En un framework, el bucle lo dibujas tú: qué nodo va después de cuál, cuándo se llama a una herramienta, cuándo se termina. En un harness, el bucle ya está escrito y probado. El modelo decide el siguiente paso, y tú le das material para decidir bien.

🔑 Si solo te quedas con una idea: la pregunta no es “qué librería uso”, es “¿quién controla el flujo, mi código o el modelo?”.

Esto conecta con algo que ya contamos al hablar de qué es un AI harness y por qué importa más que el propio modelo: el modelo es el motor, pero el coche entero es el harness. Aquí vamos un paso más allá. No te explico qué es un harness, sino cuándo te conviene uno frente a ponerte a ensamblar.

Qué te da un framework de agentes ¶

Un framework de agentes es un conjunto de librerías, abstracciones y primitivas para construir agentes. Esa es la definición que usa Plane, y coincide con la de FutureAGI: “un framework aporta abstracciones reutilizables para construir un agente” (fuente: FutureAGI, 2026).

Las primitivas cambian de un framework a otro, pero la familia es reconocible:

• Adaptadores de modelo: una interfaz común para hablar con Claude, GPT, Gemini o un modelo local sin reescribir nada.
• Nodos y aristas (o pasos, tareas, roles): las cajitas del diagrama y las flechas que las unen.
• Estado: un objeto que viaja por el flujo y que cada paso lee y modifica.
• Herramientas: funciones que defines tú y que el modelo puede invocar.
• Persistencia y checkpoints: guardar el estado para reanudar, repetir o meter a un humano en medio.

Los nombres que salen en todas las comparativas son LangGraph, CrewAI, Google ADK y Microsoft Agent Framework. Este último es la fusión de AutoGen y Semantic Kernel, que llegó a su versión 1.0 en abril de 2026 (fuente: TrueFoundry, 2026). Cada uno con su sabor: LangGraph piensa en grafos de estado, CrewAI en equipos con roles y Google ADK en agentes que se componen entre sí. En la arquitectura de agentes de IA para developers comparamos nueve de ellos con sus capas y componentes.

Ahora mira lo que no te dan. Un framework no trae, de serie, un agente que sepa leer tu repositorio, ejecutar comandos en una shell, compactar el contexto cuando se llena o pedirte permiso antes de borrar algo. Todo eso lo puedes construir con sus piezas. Pero lo construyes tú.

⚠️ El framework te da el control total y, con él, la factura total. Cada decisión que no toma el framework la tomas tú, y cada decisión que tomas tú es código que mantienes.

Curso en vídeo

Antes de ensamblar nada, mira lo lejos que llegas con un harness y tus prompts

La primera lección arranca un flujo completo con un agente de código y tus prompts, sin framework, y la tercera escribe el AGENTS.md que lo configura regla a regla.

Entra en el curso gratis →

Qué trae un harness de agentes de serie ¶

Un harness es el entorno de ejecución y control que rodea al modelo mientras trabaja. Otra vez Plane: “the execution and control environment that surrounds an AI agent while it works”. FutureAGI lo define como la capa configurada de ejecución que hace girar el bucle modelo-herramienta.

Dicho en cristiano: es Claude Code sin la parte de Claude Code que ves. Lo que hay debajo del chat.

Cuando te llevas un harness, te llevas ya resuelto:

1. El bucle del agente: pensar, llamar a una herramienta, leer el resultado, repetir, saber cuándo parar.
2. Herramientas básicas: leer y escribir ficheros, buscar en el código, ejecutar comandos en una shell, a veces navegar.
3. Gestión del contexto: qué entra en la ventana, cuándo se resume, cómo se recupera lo que se compactó.
4. Permisos y sandbox: qué puede hacer el agente sin preguntarte y qué no.
5. Memoria y sesiones: retomar una conversación, guardar lo aprendido.
6. Subagentes: repartir trabajo en contextos separados para no ensuciar el principal.
7. Puntos de extensión: instrucciones (CLAUDE.md, AGENTS.md), skills, servidores MCP y hooks.

Los ejemplos más conocidos son los agentes de código: Claude Code, Codex, OpenCode, Cursor o Pi. Arize cuenta que estos harnesses “nacieron de abajo arriba, a partir de los agentes de código”, y que todos convergieron en la misma forma. TrueFoundry mete en la misma bolsa al Claude Agent SDK, a opencode, a Pi y a OpenHands.

Fíjate en el Claude Agent SDK. La propia documentación de Anthropic lo presenta como un SDK construido sobre el mismo harness que mueve Claude Code: el mismo bucle, las mismas herramientas y la misma gestión de contexto, programable desde Python o TypeScript (fuente: documentación de Claude Agent SDK). Antes se llamaba Claude Code SDK. Le cambiaron el nombre porque la gente lo estaba usando para cosas que no tenían nada que ver con programar.

💡 Con un harness tu trabajo cambia de naturaleza. Ya no escribes el flujo: escribes el contexto. Instrucciones, skills, herramientas y datos. Si quieres ver cómo se hace eso bien, tenemos los 12 pasos del harness engineering para tu agente de código.

La infografía, pieza a pieza ¶

Hay una infografía titulada “Agent framework vs. agent harness” que lo cuenta muy bien con dos dibujos. Aquí la tienes redibujada y en castellano:

A la izquierda, un diagrama de flujo. Tiene un inicio y un final. Las flechas las pones tú. La bifurcación es una condición que has escrito en código: si pasa esto, ve a herramientas; si no, al paso a medida. El estado es el cuaderno compartido donde cada paso apunta lo suyo.

A la derecha, un círculo. No hay inicio ni final dibujados. En el centro está el modelo y alrededor, las capacidades que el harness pone a su alcance. Tú no dibujas flechas: enchufas cosas al anillo (tus instrucciones, tus skills, tus herramientas, tus datos) y el modelo decide qué usar y en qué orden.

La diferencia de fondo es esta:

La penúltima fila es la que más se olvida. Si tu flujo dice “paso 1, paso 2, paso 3”, un modelo el doble de listo seguirá haciendo paso 1, paso 2, paso 3. En un harness, un modelo mejor encuentra atajos que tú no habías previsto.

La frontera se ha vuelto borrosa ¶

Si la tabla te ha parecido demasiado limpia, es porque lo es. En la práctica, muchos productos son las dos cosas.

FutureAGI lo plantea con precisión: la distinción “va de rol, no de empaquetado”. Una misma librería puede darte solo primitivas o darte también un bucle gestionado con sus valores por defecto. TrueFoundry da tres motivos para la confusión: hay productos que son ambas cosas, el marketing persigue el volumen de búsqueda (la palabra “harness” no empezó a aparecer hasta 2026) y la frontera se mueve a medida que los productos maduran.

Así queda el reparto, de más piezas sueltas a más agente de serie:

Lo de Microsoft lo cuenta Plane (fuente: Plane, 2026). OpenAI Agents SDK aparece en las tablas de FutureAGI como “SDK/framework con comportamiento de runtime gestionado”: tiene agentes, handoffs y guardrails, pero también un bucle propio. Y Flue, el de la gente de Astro, lo analizamos en qué es Flue 2.0.

🔑 Juzga por el comportamiento, no por la etiqueta. Pregúntate: si no escribo ningún flujo, ¿esto ya hace algo útil? Si la respuesta es sí, tienes un harness delante, se llame como se llame.

Hay una tercera palabra que conviene separar: el agente. FutureAGI distingue entre el framework (la caja de herramientas), el harness (una instancia configurada) y el agente (el proceso vivo que ejecuta ese harness). Es la diferencia entre la receta, la cocina montada y el plato que sale.

El debate de si los harnesses se comen a los frameworks ¶

Arize tituló su artículo sin rodeos: “por qué los harnesses están sustituyendo a los frameworks”. Su tesis es que el harness se ha convertido en la verdadera superficie de producto, y que el trabajo se ha movido “del ajuste de prompts a bucles, herramientas, trazas, evaluaciones y métricas operativas”.

Es una tesis con buenos apoyos. Harrison Chase, de LangChain, resume la idea con aquello de “si no eres el modelo, eres el harness”. Mitchell Hashimoto acuñó el término harness engineering, del que ya hablamos en cómo ser Harness Engineer. Y los datos de los que se presume apuntan en esa dirección:

• LangChain mejoró Deep Agents de un 52,8% a un 66,5% en Terminal-Bench 2.0 cambiando solo el harness, con el mismo modelo GPT-5.2-Codex (citado por FutureAGI, 2026).
• Vercel, en un agente de texto a SQL, redujo un 37% el consumo de tokens y ganó 3,5 veces en velocidad al simplificar su harness. Eso sí: la muestra era pequeña, pasó de acertar cuatro de cinco a cinco de cinco.
• Hugging Face cuenta que su línea base sin CLI llegaba a quemar hasta seis veces más tokens (citado por Arize, 2026).
• Un trabajo de la CMU con uso multiagente del ordenador sube la tasa de éxito del 3,4% al 25,5% (citado por Arize, 2026).

Ahora, el contrapunto. Ni FutureAGI ni TrueFoundry compran la idea de la sustitución. FutureAGI dice que el harness “empaqueta y configura capacidades del framework en lugar de dejar obsoletos a los frameworks”. TrueFoundry habla de “el error que atrapa a los equipos: tratarlo como una elección binaria”. Y la mayoría de esos datos son casos de los propios fabricantes.

Mi lectura: los harnesses no matan a los frameworks, los bajan un piso. El framework pasa a ser la fontanería sobre la que alguien construye un harness. Tú, como developer, cada vez te relacionas menos con la fontanería y más con el harness. Igual que casi nadie escribe hoy su propio servidor HTTP aunque los sockets sigan ahí.

Y la adopción crece en las dos capas. Según el State of AI Engineering 2026 de Datadog, la adopción de frameworks de agentes pasó de un 9% de organizaciones a principios de 2025 a casi un 18% a comienzos de 2026. Y según el informe State of Agent Engineering de LangChain, el 57% de las organizaciones encuestadas ya tiene agentes en producción.

Un mismo agente, montado de las dos maneras ¶

Vamos a lo concreto. Quieres un agente de guardia que reciba un error de producción, mire el código del repositorio y proponga un arreglo. Con LangGraph dibujas un flujo de cuatro pasos. Con el Claude Agent SDK le das un objetivo, unas instrucciones y unos permisos.

Punto por punto, las dos versiones se diferencian en esto:

⚠️ El precio de la versión harness es la predictibilidad. Si que cambie el recorrido es un problema para tu caso, quizá necesitas el framework (o un harness con hooks que le pongan raíles).

Si quieres verlo montado de verdad, con herramientas MCP propias, tienes el tutorial del Claude Agent SDK con TypeScript.

Construye agentes con criterio

Si vas a ensamblar tu agente, que no se te descontrole en producción

Seis niveles de arquitectura, de un LLM con tools a un sistema multiagéntico revisado por otro modelo, con código, Mastra y OpenCode: guardarraíles, memoria, skills, MCP, orquestación y evals.

Quiero ver la masterclass →

6 niveles de arquitectura, en directo · Acceso con suscripción Web Reactiva Premium

Cuándo te compensa cada uno ¶

El framework gana cuando el flujo es parte del producto: necesitas poder dibujar en una pizarra lo que va a hacer el sistema y que lo haga así, siempre. El harness gana cuando el camino no se puede dibujar de antemano y el valor está en que el agente explore, pruebe y corrija.

Un framework se parece a una cadena de montaje. Es aburrida, es rígida y por eso funciona. Nadie quiere que la cadena de montaje de coches tenga creatividad.

🛡️ Si eliges framework, invierte desde el primer día en trazas y evaluaciones. La predictibilidad que compras solo vale si puedes comprobarla.

Un harness se parece más a dar de alta a un empleado nuevo. Le explicas las normas de la casa, le das acceso a lo que necesita, le quitas acceso a lo que no y lo dejas trabajar. Las normas de la casa viven en ficheros como el AGENTS.md: si quieres afinarlo, mira cómo escribir reglas de contexto que el agente sí sigue.

Si necesitas que un harness sea un poco más predecible, no tienes que saltar al framework. Los hooks te dejan imponer reglas en puntos del bucle (antes de ejecutar un comando, después de editar un fichero) y los subagentes te dejan partir el trabajo en trozos con su propio contexto. Es la vía intermedia: el bucle es del modelo, pero hay raíles.

Los errores que más se repiten al elegir ¶

He visto (y cometido) unos cuantos. Estos son los que más duelen:

1. Reconstruir el bucle de un harness con un framework. Te pasas tres semanas escribiendo la gestión de contexto, la herramienta de leer ficheros y el sistema de permisos. Al final tienes un Claude Code peor. TrueFoundry lo señala de forma explícita: no reconstruyas un bucle que un harness ya te da.
2. Usar un harness para un proceso que debe ser determinista. Si el proceso legal dice “paso A y luego paso B”, que el agente decida hacer B antes que A no es creatividad, es un incidente.
3. Elegir por la etiqueta. “Usamos un framework” o “usamos un harness” no dice nada. Mira qué hace si no escribes ningún flujo.
4. Olvidar el coste de mantenimiento. Cada nodo que escribes es una pieza que hay que actualizar cuando cambia la API del modelo. El harness lo mantiene otro (y eso también es una dependencia, ojo).
5. No medir. En los dos mundos. Sin trazas ni evaluaciones no sabes si tu flujo rígido acierta ni si tu harness gasta el triple de tokens de lo necesario.
6. Pensar que es para siempre. Mucha gente empieza con un harness para validar la idea y, cuando el proceso se estabiliza, congela las partes repetitivas en un flujo. O al revés: un flujo con un nodo que, por dentro, lanza un harness para la parte abierta.

La combinación más potente que se ve hoy es un framework por fuera y un harness por dentro: el flujo de alto nivel es fijo (recibir, clasificar, ejecutar, revisar, notificar) y el paso “ejecutar” lo hace un agente con harness que tiene libertad dentro de su caja. Es lo que ya contamos al hablar de montar un sistema de agentes autónomos con loops.

Cómo decidir en cinco minutos ¶

Si estás delante de un proyecto nuevo y no sabes por dónde tirar, hazte estas preguntas en orden:

No hace falta que gane uno por goleada. Si sale un empate, empieza por el harness: es más barato descubrir que necesitas un framework que descubrir que te sobraba.

💡 Si dudas, prototipa con un harness y extrae a un framework solo las partes que se repitan igual cien veces. Así tiras menos código a la basura.

TL;DR ¶

• 🧩 Un framework de agentes (LangGraph, CrewAI, Google ADK, Microsoft Agent Framework) te da las piezas para construir un agente: tú dibujas el flujo.
• 🔁 Un harness de agentes (Claude Code, Codex, OpenCode, Pi, Claude Agent SDK) te da un agente que ya funciona: tú configuras instrucciones, skills, herramientas y permisos, y el modelo decide los pasos.
• 🌫️ La frontera es borrosa: Deep Agents es un harness sobre LangGraph y Microsoft Agent Framework trae su propio Harness Agent. Juzga por el comportamiento, no por la etiqueta.
• 📈 Cambiar solo el harness llevó a Deep Agents del 52,8% al 66,5% en Terminal-Bench 2.0 con el mismo modelo, según LangChain.
• 🎯 Framework para procesos fijos y auditables; harness para tareas abiertas. Y muchas veces, framework por fuera y harness por dentro.

Preguntas frecuentes ¶

¿Qué es un agent harness? ¶

Un agent harness es el entorno de ejecución que rodea a un modelo de IA y lo convierte en un agente que funciona: el bucle de razonar y actuar, las herramientas (ficheros, shell, búsqueda), la gestión del contexto, los permisos y la memoria. Claude Code, Codex u OpenCode son harnesses. Tú lo configuras con instrucciones, skills y herramientas en lugar de programar el flujo.

¿Qué es un framework de agentes? ¶

Es un conjunto de librerías y abstracciones para construir agentes: adaptadores de modelo, nodos, aristas, estado, herramientas y persistencia. LangGraph, CrewAI, Google ADK y Microsoft Agent Framework son los más citados. Con un framework escribes tú el flujo que seguirá el agente.

¿Cuál es la diferencia principal entre framework y harness? ¶

Quién controla el bucle de ejecución. En un framework, el flujo lo defines tú en código y el agente lo sigue. En un harness, el bucle ya está construido y el modelo decide el siguiente paso, mientras tú aportas el contexto y los límites.

¿El Claude Agent SDK es un framework o un harness? ¶

Es un harness empaquetado como SDK. La documentación de Anthropic lo describe como el mismo harness que usa Claude Code (bucle, herramientas y gestión de contexto), programable desde Python o TypeScript. Por eso con muy poco código tienes un agente capaz de leer un repositorio y ejecutar comandos.

¿LangGraph es un harness? ¶

LangGraph es un framework de orquestación de bajo nivel: grafos de estado con nodos y aristas que defines tú. LangChain ha construido encima Deep Agents, que sí funciona como un harness con planificación, sistema de ficheros y subagentes incluidos.

¿Los harnesses van a sustituir a los frameworks? ¶

Hay división de opiniones. Arize defiende que los harnesses están sustituyendo a los frameworks como superficie de producto; FutureAGI y TrueFoundry sostienen que el harness empaqueta capacidades del framework y que no es una elección binaria. Lo más probable es que convivan, con el framework como capa inferior.

¿Cuándo debo usar un framework de agentes en lugar de un harness? ¶

Cuando el proceso tiene pasos fijos que no deben cambiar, cuando necesitas auditar cada decisión, cuando el agente es una pieza del backend de tu aplicación o cuando quieres controlar una a una las llamadas al modelo. Para tareas abiertas como arreglar bugs o investigar, un harness suele ir mejor.

¿Puedo combinar un framework y un harness? ¶

Sí, y es de las combinaciones más útiles. Un flujo fijo de alto nivel con un framework (recibir, clasificar, ejecutar, revisar) donde el paso de ejecución lo hace un agente con harness. Así tienes predictibilidad por fuera y flexibilidad por dentro.

¿Qué es harness engineering? ¶

Es la disciplina de diseñar todo lo que rodea al modelo para que el agente trabaje bien: instrucciones, skills, herramientas, sensores, hooks, subagentes y bucles de verificación. El término lo popularizó Mitchell Hashimoto. Mejorar el harness puede dar más rendimiento que cambiar de modelo, como muestran los datos de Deep Agents en Terminal-Bench 2.0.

¿Un harness es menos seguro que un framework? ¶

Depende de cómo lo configures. Un buen harness trae un modelo de permisos, sandbox y aprobaciones que con un framework tendrías que construir tú. La diferencia es que en un harness el agente elige qué hacer, así que tienes que acotar bien qué herramientas y permisos le das, y usar hooks donde una regla deba cumplirse siempre.

Fuentes ¶

• Agent harness vs. agent framework: why harnesses are replacing frameworks — Laurie Voss, Arize
• Agent harness vs. agent framework: What’s the difference? — Sneha Kanojia, Plane
• Agent harness vs framework — FutureAGI
• Agent harness vs agent framework: what’s actually different — Sahajmeet Kaur, TrueFoundry
• Agent SDK overview — Documentación oficial de Claude Agent SDK
• LangGraph — Documentación oficial de LangChain
• Deep Agents — Documentación oficial de LangChain

🧨 Última oportunidad para recibir la dinamita que mereces sobre programación con IA el próximo domingo: Suscríbete gratis a Web Reactiva en https://webreactiva.com/newsletter