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 arnés trata ese andamiaje como un artefacto vivo, ajustándolo cada vez que el agente comete un error.

Dicho de forma simple: cada vez que un agente falla, diseñas una solución permanente para que nunca vuelva a cometer ese mismo error exacto.

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. Aunque esa conversación importa, ignora la otra mitad del sistema.

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

Un modelo decente con un gran arnés supera sistemáticamente a un gran modelo con un arnés malo. Cada vez más, el trabajo de ingeniería más interesante no está en seleccionar el modelo, sino en diseñar el andamiaje que lo rodea.

Esa disciplina ya tiene nombre. @Vtrivedy10 acuñó el término ingeniería de arnés, ofreciendo un desglose claro de lo que realmente es un arnés y por qué existe cada pieza. Otras voces del sector como @dexhorthy, que rastrea patrones emergentes; HumanLayer, que enmarca los fallos de los agentes como "problemas de configuración"; el equipo de ingeniería de Anthropic, que publica guías sobre diseño de aplicaciones de larga duración; y Birgitta Böckeler, que explora la experiencia del usuario, están convergiendo en la misma idea.

Este artículo une esos hilos.

¿Qué es realmente un arnés?

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

Agente = Modelo + Arnés. Si no eres el modelo, eres el arnés.

Un arnés 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 arnés le proporciona estado, ejecución de herramientas, bucles de retroalimentación y restricciones aplicables.

Concretamente, un arnés 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, gestionar traspasos y enrutar modelos.
• Hooks y middleware para ejecución determinista, como comprobaciones de lint o compactación de contexto.
• Herramientas de observabilidad para registros, trazas, costos y medición de latencia.

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

Aunque esto representa una superficie enorme, es tu superficie, no la del proveedor del modelo. Claude Code, Cursor, Codex, Aider y Cline son todos arneses. El modelo subyacente puede ser idéntico en todas las plataformas, pero el comportamiento que experimentas está dominado por el arnés.

Reformulemos el "problema de habilidad"

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

La mentalidad de la ingeniería de arnés rechaza esta postura por defecto. Los fallos suelen ser, hasta cierto punto, comprensibles. 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 constantemente con código roto, incorpora 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". Piensa en 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 exacto ejecutándose en un arnés personalizado y altamente ajustado. Mover un modelo a un entorno con mejores herramientas de base de código, prompts más precisos y una contrapresión más afinada puede desbloquear capacidades que la configuración original dejó sin explotar.

La brecha entre lo que los modelos actuales pueden hacer en teoría y lo que realmente ves que hacen es, en gran medida, una brecha de arnés.

El trinquete: cada error se convierte en una regla

El hábito más vital en la ingeniería de arnés es tratar los errores de los agentes como señales permanentes, no como rarezas puntuales que se reintentan y olvidan.

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 añadirse 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 arnés es una disciplina más que un framework único para todos. El arnés adecuado para una base de código específica está completamente moldeado por su historial único de fallos.

Trabajar hacia atrás desde el comportamiento

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

Cada pieza del arnés debe tener un trabajo distinto. Si no puedes nombrar el comportamiento específico que un componente existe para proporcionar, debe eliminarse.

Sistema de archivos y Git: estado duradero

El sistema de archivos es fundamental. Los modelos solo pueden operar con 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.

Añadir 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 construir previamente 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 destacan en comandos de shell, lo que convierte a bash y la ejecución de código en 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 arneses salvan esta brecha utilizando archivos de memoria (como AGENTS.md) que inyectan conocimiento en cada sesión.

Para información en tiempo real, como nuevas versiones de bibliotecas o datos en vivo, la búsqueda web y las herramientas MCP están integradas directamente en el arnés.

Combatir la degradación del contexto

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

• Compactación: resumir y descargar inteligentemente el contexto más antiguo para evitar errores de API.
• Descarga de llamadas a herramientas: almacenar salidas masivas de herramientas (como registros de 2000 líneas) en el sistema de archivos, manteniendo solo los encabezados y pies esenciales en el contexto.
• Revelación progresiva: mostrar instrucciones y herramientas solo cuando una tarea las requiere explícitamente, en lugar de cargar todo al inicio.

Ejecución de horizonte largo

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

• Bucles: interceptar el intento de salida de un modelo y forzarlo a continuar contra 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 verbosos. Si una verificación de tipos pasa, el agente no oye nada; si falla, el error se inyecta directamente de nuevo en el bucle para su autocorrección.

Aquí están 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 breve y asegúrate de que cada regla se haya ganado mediante un fallo pasado.

La misma disciplina se aplica a las herramientas. Diez herramientas muy enfocadas siempre superarán a cincuenta superpuestas.

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

Cómo se ve esto en producción

La imagen pública más clara que he visto de un arnés 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 están 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 sobre el arnés al menos tanto como sobre el modelo subyacente.

Los arneses no se encogen, se mueven

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

Es tentador asumir que mejores modelos hacen obsoleto el andamiaje. Por ejemplo, las actualizaciones recientes de modelos redujeron drásticamente la necesidad de mitigaciones de "ansiedad por el contexto". Pero a medida que el suelo 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 arnés 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 debe construirse un nuevo andamiaje para alcanzar el siguiente horizonte.

¿Y el bucle de entrenamiento?

Existe un bucle de retroalimentación activo entre el diseño del arnés y el entrenamiento del modelo.

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

Esto convierte al arnés en un sistema vivo, no en un archivo de configuración estático, y demuestra que el "mejor" arnés es aquel optimizado específicamente para tus tareas y flujos de trabajo particulares.

Arnés como servicio (HaaS)

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

En lugar de construir la orquestación desde cero, el valor predeterminado moderno es seleccionar un framework de arnés, 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 estructurada en lugar de reinventar toda la arquitectura del agente.

Hacia dónde se dirige esto

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

Los problemas abiertos más emocionantes van 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 arnés, y construir entornos que ensamblen herramientas dinámicamente justo a tiempo.

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

Si estás buscando un gran framework de arnés para agentes, @FredKSchott escribió Flue. Es sólido y aparentemente se inspiró en una versión anterior de este artículo.