Ingeniería de arnés para agentes

Un agente de codificación es el modelo más todo lo que se construye a su alrededor. La ingeniería de harness trata ese andamiaje como un artefacto vivo, ajustándolo cada vez que el agente comete un error.

En pocas palabras: cada vez que un agente falla, se diseña una solución permanente para que nunca vuelva a cometer ese mismo error.

Durante los últimos dos años, la industria ha debatido sobre modelos: cuál es el más inteligente, cuál escribe el React más limpio o cuál alucina menos. Si bien esa conversación es importante, ignora la otra mitad del sistema.

El modelo es solo una entrada en un agente en ejecución. El resto es el harness: los prompts, herramientas, políticas de contexto, hooks, sandboxes, subagentes, bucles de retroalimentación y rutas de recuperación que envuelven al modelo para que pueda completar tareas.

Un modelo decente con un gran harness supera consistentemente a un gran modelo con un mal harness. Cada vez más, el trabajo de ingeniería más interesante no está en seleccionar el modelo, sino en diseñar el andamiaje a su alrededor.

Esa disciplina ahora tiene un nombre. @Vtrivedy10 acuñó el término "harness engineering", proporcionando un desglose claro de lo que realmente es un harness y por qué existe cada pieza. Otras voces de la industria como @dexhorthy rastreando patrones emergentes, HumanLayer enmarcando los fallos de los agentes como "problemas de configuración", el equipo de ingeniería de Anthropic publicando guías sobre diseño de aplicaciones de larga duración, y Birgitta Böckeler explorando la experiencia del usuario — todas convergen aproximadamente en la misma idea.

Este artículo une esos hilos.

¿Qué es realmente un Harness?

La definición central de Trivedy hace la mayor parte del trabajo pesado:

Agente = Modelo + Harness. Si no eres el modelo, eres el harness.

Un harness abarca cada pieza de código, configuración y lógica de ejecución que no es el modelo en sí. Un modelo en bruto no es un agente. Solo se convierte en uno cuando un harness le proporciona estado, ejecución de herramientas, bucles de retroalimentación y restricciones aplicables.

Concretamente, un harness incluye:

• Prompts del sistema, CLAUDE.md, AGENTS.md, archivos de habilidades e instrucciones de subagentes.
• Herramientas, habilidades, servidores MCP y sus descripciones técnicas.
• Infraestructura empaquetada, como el sistema de archivos, sandboxes y navegadores sin interfaz gráfica.
• Lógica de orquestación para generar subagentes, manejar traspasos y enrutar modelos.
• Hooks y middleware para ejecución determinista, como verificaciones de lint o compactación de contexto.
• Herramientas de observabilidad para registros, trazas, medición de costos y latencia.

En esencia, un agente es un sistema que ejecuta herramientas en un bucle para lograr un objetivo. La verdadera habilidad está en diseñar tanto las herramientas como ese bucle.

Si bien esto representa una superficie masiva, es tu superficie, no la del proveedor del modelo. Claude Code, Cursor, Codex, Aider y Cline son todos harnesses. El modelo subyacente puede ser idéntico entre plataformas, pero el comportamiento que experimentas está dominado por el harness.

Replanteemos el "problema de habilidad"

Es común ver a ingenieros culpar al modelo cuando un agente hace algo sin sentido, a menudo archivando el problema como algo que "esperar a la próxima versión" para solucionar.

La mentalidad de la ingeniería de harness rechaza este comportamiento por defecto. Los fallos suelen ser algo legibles. Si el agente ignoró una convención, agrégala a AGENTS.md. Si ejecutó un comando destructivo, escribe un hook para bloquearlo. Si se perdió en una tarea de 40 pasos, divide la arquitectura en un planificador y un ejecutor. Si termina consistentemente con código roto, conecta una señal de contrapresión de verificación de tipos en el bucle.

Como dice HumanLayer: "No es un problema del modelo. Es un problema de configuración." Considera los benchmarks de rendimiento: un modelo líder ejecutándose dentro de un framework estándar a menudo obtiene puntuaciones drásticamente más bajas que el mismo modelo ejecutándose en un harness personalizado y altamente ajustado. Mover un modelo a un entorno con mejores herramientas de código base, prompts más ajustados y una contrapresión más precisa puede desbloquear capacidades que la configuración original dejó atrás.

La brecha entre lo que los modelos actuales pueden hacer teóricamente y lo que realmente ves que hacen es en gran medida una brecha de harness.

El Trinquete: Cada error se convierte en una regla

El hábito más vital en la ingeniería de harness es tratar los errores del agente como señales permanentes, no como casualidades únicas para reintentar y olvidar.

Si un agente envía un PR con un test comentado que se fusiona por accidente, eso es una entrada. La siguiente iteración de AGENTS.md debe indicar: "Nunca comentes los tests; bórralos o arréglalos." El siguiente hook de pre-commit debe marcar automáticamente .skip( en el diff. El subagente revisor debe actualizarse para bloquear tests comentados.

Las restricciones solo deben agregarse cuando observas un fallo real, y eliminarse solo cuando un modelo capaz las vuelva redundantes. Cada línea en un buen prompt del sistema debería remontarse a un fallo histórico específico.

Debido a esto, la ingeniería de harness es una disciplina más que un framework único para todos. El harness adecuado para un código base específico está completamente moldeado por su historial único de fallos.

Trabajando hacia atrás desde el comportamiento

La forma más efectiva de diseñar un harness es comenzar con el comportamiento deseado y construir el componente que lo entrega: Comportamiento que queremos → Diseño del harness para lograrlo.

Cada pieza del harness debe tener un trabajo distinto. Si no puedes nombrar el comportamiento específico que un componente existe para entregar, debe ser eliminado.

Sistema de archivos y Git — estado duradero

El sistema de archivos es fundamental. Los modelos solo pueden operar sobre lo que cabe en su ventana de contexto. Un sistema de archivos proporciona un espacio de trabajo para leer datos, un lugar para descargar trabajo intermedio y una superficie para que múltiples agentes se coordinen.

Agregar Git proporciona versionado gratuito, permitiendo al agente rastrear el progreso, ramificar experimentos y revertir errores.

Bash y Ejecución de Código: herramientas de propósito general

La mayoría de los agentes operan en un bucle ReAct: razonar, actuar mediante una llamada a herramienta, observar, repetir. En lugar de preconstruir una herramienta para cada acción concebible, darle al agente acceso a bash le permite construir lo que necesita sobre la marcha.

Los agentes generalmente sobresalen en comandos de shell, haciendo de bash y la ejecución de código la estrategia predeterminada para la resolución autónoma de problemas.

Sandboxes y Herramientas Predeterminadas

Bash solo es útil si se ejecuta de forma segura. Los sandboxes proporcionan a los agentes un entorno aislado para ejecutar código, inspeccionar archivos y verificar el trabajo sin arriesgar la máquina anfitriona.

Un buen sandbox viene con valores predeterminados sólidos: entornos de ejecución de lenguajes preinstalados, CLI de pruebas y navegadores sin interfaz gráfica, permitiendo al agente observar su propio trabajo y cerrar el bucle de autoverificación.

Memoria y Búsqueda: Aprendizaje Continuo

Los modelos no tienen conocimiento más allá de sus pesos de entrenamiento y el contexto actual. Los harnesses cierran esta brecha usando archivos de memoria (como AGENTS.md) que inyectan conocimiento en cada sesión.

Para información en tiempo real como nuevas versiones de librerías o datos en vivo, la búsqueda web y las herramientas MCP están integradas directamente en el harness.

Combatiendo la Degradación del Contexto

Los modelos degradan su razonamiento a medida que sus ventanas de contexto se llenan. Los harnesses gestionan esta escasez usando tres técnicas principales:

• Compactación: Resumir inteligentemente y descargar contexto antiguo para evitar errores de API.
• Descarga de llamadas a herramientas: Almacenar salidas masivas de herramientas (como registros de 2,000 líneas) en el sistema de archivos mientras se mantienen solo los encabezados y pies esenciales en el contexto.
• Divulgación progresiva: Revelar instrucciones y herramientas solo cuando una tarea las requiere explícitamente, en lugar de cargar todo al inicio.

Ejecución a Largo Plazo

El trabajo autónomo de larga duración sufre de detención temprana y mala descomposición de problemas. Los harnesses contrarrestan esto mediante diseño estructural:

• Bucles: Interceptar el intento de un modelo de salir y forzarlo a continuar hacia un objetivo de finalización en una ventana de contexto nueva.
• Planificación: Forzar al modelo a descomponer los objetivos en un archivo de plan paso a paso, verificando su trabajo mediante hooks de autoverificación después de cada paso.
• Divisiones: Separar la generación y la evaluación en agentes distintos, evitando el sesgo positivo inherente que tienen los modelos al calificar su propio trabajo.

Los Hooks son tu Capa de Aplicación

Los hooks cierran la brecha entre solicitar una acción y aplicarla. Se ejecutan en ciclos de vida específicos: antes de una llamada a herramienta, después de una edición de archivo o antes de un commit. Los hooks bloquean comandos destructivos, aplican formato automático para ahorrar tokens y ejecutan suites de pruebas.

Idealmente, el éxito es silencioso y los fallos son detallados. Si una verificación de tipos pasa, el agente no escucha nada; si falla, el error se inyecta directamente de vuelta en el bucle para autocorrección.

Aquí está el libro de reglas y la elección de herramientas

Un archivo markdown plano en la raíz de un repositorio sigue siendo el punto de configuración de mayor apalancamiento. Sin embargo, debe tratarse como la lista de verificación de un piloto, no como una guía de estilo. Mantenlo corto y asegúrate de que cada regla se haya ganado a través de un fallo pasado.

La misma disciplina se aplica a las herramientas. Diez herramientas altamente enfocadas siempre superarán a cincuenta que se superponen.

Además, debido a que las descripciones de herramientas llenan el prompt, las integraciones externas maliciosas o descuidadas (como servidores MCP no verificados) pueden inyectar prompts malos en el agente antes de que siquiera comience a trabajar.

Cómo se ve esto en producción

La imagen pública más clara que he visto de un harness maduro es el desglose (estimado) de Fareed Khan de la arquitectura de Claude Code.

Casi todos los conceptos de la sección anterior aparecen en este diagrama como un componente nombrado. La inyección de contexto es la capa de conocimiento. El estado del bucle reside en el almacén de memoria y el aislador del árbol de trabajo. Los hooks de acciones destructivas se encuentran detrás de la puerta de permisos. Los cortafuegos de contexto de subagentes son toda la capa multiagente. El registro de despacho de herramientas es donde se conectan tanto los servidores MCP como bash. La trayectoria de Claude Code trata tanto del harness como del modelo subyacente.

Los Harnesses no se Reducen, se Mueven

A medida que los modelos mejoran, la necesidad de un harness no desaparece, se desplaza.

Es tentador asumir que mejores modelos vuelven obsoleto el andamiaje. Por ejemplo, las actualizaciones recientes de modelos redujeron drásticamente la necesidad de mitigaciones de "ansiedad de contexto". Pero a medida que el piso sube, también lo hace el techo. Las tareas que antes eran inalcanzables ahora están en juego, trayendo modos de fallo completamente nuevos.

Cada componente en un harness codifica una suposición sobre lo que el modelo no puede hacer por sí solo. Cuando el modelo mejora, el andamiaje obsoleto debe eliminarse, y se debe construir un nuevo andamiaje para alcanzar el próximo horizonte.

¿Qué pasa con el Bucle de Entrenamiento?

Hay un bucle de retroalimentación activo entre el diseño del harness y el entrenamiento del modelo.

Los modelos actuales a menudo se entrenan posteriormente con harnesses específicos en el bucle, creando un grado de sobreajuste. El modelo se vuelve excepcionalmente bueno en las acciones específicas que los diseñadores del harness priorizaron (por ejemplo, operaciones del sistema de archivos, bash, despacho de subagentes).

Esto hace del harness un sistema vivo, no un archivo de configuración estático, y demuestra que el "mejor" harness es aquel optimizado específicamente para tus tareas y flujos de trabajo particulares.

Harness como Servicio (HaaS)

La industria está pasando de construir sobre APIs de LLM (que proporcionan completaciones) a construir sobre APIs de Harness (que proporcionan un entorno de ejecución). Los SDK ahora ofrecen el bucle, herramientas, gestión de contexto, hooks y sandboxes listos para usar.

En lugar de construir orquestación desde cero, el valor predeterminado moderno es seleccionar un framework de harness, configurar sus pilares centrales y centrarse puramente en el diseño de prompts y herramientas específicos del dominio.

Esto es lo que hace que la resolución de problemas sea escalable: estás ajustando una superficie de configuración bien factorizada en lugar de reinventar toda la arquitectura del agente.

Hacia Dónde Se Dirige Esto

Si observas los mejores agentes de codificación hoy, se parecen más entre sí que sus modelos subyacentes. Los modelos difieren, pero los patrones de harness están convergiendo. La industria está identificando rápidamente el andamiaje estructural necesario para convertir texto generativo en software entregable.

Los problemas abiertos más emocionantes están yendo más allá de los agentes individuales: orquestar múltiples agentes en paralelo, permitir que los agentes analicen sus propias trazas para corregir fallos a nivel de harness, y construir entornos que ensamblen herramientas dinámicamente justo a tiempo.

En última instancia, esta es la fase donde los harnesses dejan de ser archivos de configuración estáticos y comienzan a actuar mucho más como compiladores.

Si estás buscando un gran framework de harness para agentes, @FredKSchott escribió Flue. Es sólido y aparentemente fue inspirado por una versión anterior de este artículo.