La mayoría de la gente intenta arreglar los agentes de IA en la capa equivocada.
Cuando un agente falla, reescriben el prompt. Cuando vuelve a fallar, agregan más instrucciones, cambian de modelo, amplían la ventana de contexto o conectan otra herramienta.
Y entonces regresan los mismos problemas.
El agente olvida una decisión importante. Usa la herramienta incorrecta. Pierde el hilo de lo que pasó tres pasos atrás. Dice que la tarea terminó sin verificar el resultado. Reintenta la misma acción fallida hasta que se acaba el presupuesto.
El problema no siempre es el modelo.
El problema es el entorno que lo rodea.
Ese entorno es el harness.
La Ingeniería de Harness (Harness Engineering) es la práctica de construir el sistema alrededor de un modelo que decide qué puede ver, qué puede hacer, qué recuerda, qué cuenta como éxito y qué pasa cuando algo falla.
Un mejor prompt puede mejorar una sola respuesta.
Un mejor harness mejora cada ejecución.
Sigue mi Substack para más análisis prácticos sobre agentes de IA, automatización y sistemas en producción:
1. El modelo no es el agente
Un modelo puede razonar, generar, comparar y elegir.
Eso no lo convierte en un agente confiable.
Un agente real también necesita encontrar el contexto adecuado, usar herramientas, conservar el estado, respetar permisos, verificar su propio trabajo y recuperarse cuando el entorno se comporta de forma distinta a la esperada.
El modelo es solo el motor de razonamiento.
El harness es todo aquello que transforma ese razonamiento en ejecución real.
1SOLICITUD DEL USUARIO2 |3 v4+-----------------------------+5| HARNESS |6| |7| contrato contexto |8| herramientas estado |9| política verificación |10| trazas recuperación |11+-----------------------------+12 |13 v14 MODELO15 |16 v17ENTORNO REAL
Pon el mismo modelo dentro de un chat y responderá preguntas.
Ponlo dentro de un repositorio con acceso a terminal, pruebas, herramientas de navegador, memoria del proyecto, permisos controlados y un ciclo de revisión, y podrá completar trabajo real.
El modelo no cambió.
El harness sí.
2. Convierte cada solicitud en un contrato
El lenguaje natural es flexible.
La ejecución autónoma no debería serlo.
Una solicitud como:
Mejora el flujo de onboarding.
está bien cuando hay un humano sentado junto al modelo.
Es pésima como instrucción para producción.
Antes de que el agente actúe, convierte la solicitud en un contrato de tarea con límites claros.
1objetivo: reducir el abandono en el onboarding23entradas:4 - resumen del producto5 - datos de analítica6 - repositorio78restricciones:9 - conservar la autenticación10 - no cambiar el esquema de la base de datos11 - mantener el comportamiento actual en móviles1213entregable:14 - pull request revisable1516criterios_de_finalizacion:17 - las pruebas pasan18 - el evento de analítica se dispara correctamente19 - el flujo de escritorio pasa la revisión20 - el flujo móvil pasa la revisión2122aprobacion_requerida:23 - despliegue a producción
Lo importante son los criterios_de_finalizacion.
Sin ellos, el agente puede resolver una versión ligeramente más fácil del problema y aun así afirmar con total seguridad que la tarea está completa.
Con ellos, la finalización se vuelve medible.
El agente no debería preguntar:
¿Qué hago ahora?
Debería preguntar:
¿Qué acción acerca el entorno actual al resultado pactado en el contrato?
Ese es un ciclo mucho más sólido.
3. Dale al agente un mapa, no una ventana de contexto gigante
Una reacción común ante los errores de un agente es darle más contexto al modelo.
Más documentación.
Más historial de conversación.
Más archivos.
Más resultados de herramientas.
Al final, el agente recibe todo y entiende menos.
El contexto no es almacenamiento.
Es un presupuesto de atención.
En lugar de volcar todo el proyecto en cada ejecución, dale al agente un mapa pequeño de dónde está la información útil.
1MAPA DEL PROYECTO23reglas del producto -> docs/product/4arquitectura -> docs/architecture.md5frontend -> apps/web/6backend -> services/api/7pruebas -> tests/8comandos -> docs/commands.md9seguridad -> docs/security.md
Luego expándelo solo cuando sea necesario.
1TAREA2 |3 v4MAPA DEL PROYECTO5 |6 v7SISTEMA RELEVANTE8 |9 v10ARCHIVOS EXACTOS11 |12 v13INSTRUCCIONES LOCALES
El material original describe esto como divulgación progresiva: el harness debe cargar más información porque la tarea lo necesita, no simplemente porque la información existe.
El objetivo no es tener el máximo contexto.
El objetivo es tener la máxima señal útil.
4. Pon una puerta de enlace entre el modelo y sus herramientas
Un modelo con veinte herramientas no es automáticamente veinte veces más capaz.
Quizás solo tenga veinte formas más de fallar.
Cada herramienta debería tener un contrato.
1HERRAMIENTA: edit_file23ENTRADAS4ruta5patch67PRECONDICIONES8la ruta existe9la ruta está dentro del espacio de trabajo1011ÉXITO12patch aplicado13diff devuelto1415FALLO16error estructurado17sin sobrescritura parcial1819RIESGO20reversible
Entonces la ruta de ejecución se convierte en:
1EL MODELO PROPONE2 |3 v4LA PUERTA DE ENLACE VALIDA5 |6 v7LA POLÍTICA AUTORIZA8 |9 v10LA HERRAMIENTA EJECUTA11 |12 v13EL HARNESS REGISTRA EL RESULTADO
El modelo decide qué acción quiere tomar.
El harness decide si esa acción es válida, permitida y segura.
Esa distinción se vuelve crítica cuando las herramientas pueden enviar mensajes, modificar producción, gastar dinero o borrar datos.
Una buena puerta de enlace de herramientas también puede agregar tiempos de espera, validar argumentos, restringir rutas de archivos, normalizar errores y hacer que los reintentos sean seguros.
Las buenas herramientas reducen la cantidad de cosas que el modelo tiene que adivinar.
5. Saca la memoria de la conversación
La conversación no debería ser el registro oficial del sistema.
Los agentes que corren por mucho tiempo terminan chocando con los límites de contexto, fallando, reiniciándose o pasando el trabajo a otra sesión.
Si cada decisión importante existe solo dentro de la transcripción, el flujo de trabajo es frágil.
Guarda el estado persistente por separado.
1{2 "id_tarea": "feature_042",3 "estado": "verificando",4 "paso_actual": "revision_movil",56 "completado": [7 "implementacion",8 "pruebas_unitarias",9 "revision_escritorio"10 ],1112 "decisiones": [13 "reutilizar el endpoint de exportacion existente",14 "mantener el formato de fecha actual"15 ],1617 "artefactos": [18 "export.csv",19 "desktop-after.png"20 ],2122 "riesgos_abiertos": [23 "la barra de herramientas movil podria desbordarse"24 ],2526 "siguiente_accion": "renderizar viewport movil"27}
Un sistema útil separa la memoria en cuatro categorías:
1HECHOS2conocimiento estable34DECISIONES5qué se eligió y por qué67ESTADO8en qué punto va la ejecución actual910LECCIONES11fallos que deberían afectar ejecuciones futuras
La siguiente sesión del agente debería heredar el estado del trabajo, no un resumen comprimido de la conversación anterior.
6. Haz que la evidencia sea la puerta hacia la finalización
Que un agente diga "listo" no prueba que el trabajo esté terminado.
Es solo otra salida del modelo.
El harness necesita evidencia observable.
1AFIRMACIÓN EVIDENCIA23"el bug está arreglado" la prueba que fallaba ahora pasa45"la página funciona" el flujo en el navegador se completó67"los datos son correctos" los valores coinciden con la fuente89"la migración es segura" simulación + rollback exitosos1011"la tarea está completa" todas las verificaciones de aceptación pasan
Usa primero las comprobaciones deterministas.
1sintaxis2 |3 v4tipos5 |6 v7pruebas específicas8 |9 v10pruebas de integración11 |12 v13revisión visual / semántica14 |15 v16aprobación humana
No le pidas a otro modelo que responda algo que un compilador, una prueba, un esquema o una consulta a la base de datos puede demostrar.
Usa los modelos para emitir juicios.
Usa los sistemas deterministas para los hechos.
El modelo crea el artefacto.
El entorno genera evidencia sobre el artefacto.
El harness decide si la evidencia es suficiente.
7. Separa al constructor del verificador
Hay otro problema con la autorrevisión.
El agente que cometió el error suele llevar las mismas suposiciones a la revisión.
Una arquitectura más sólida separa al trabajador del verificador.
1CONSTRUCTOR2 |3 v4crea un candidato5 |6 v7VERIFICADOR8 |9 +-- comprueba el contrato10 +-- busca casos faltantes11 +-- pone a prueba afirmaciones sin respaldo12 +-- intenta romper el resultado13 |14 +------ ÉXITO ------> ACEPTAR15 |16 +------ FALLO ------> DEVOLVER EVIDENCIA
El verificador no debería preguntar:
¿Esto se ve bien?
Debería preguntar:
¿Qué haría que esto fuera inaceptable?
Eso transforma la revisión: deja de ser una confirmación y pasa a ser un intento de refutación.
El material original recomienda explícitamente darle a la verificación sus propios criterios de rechazo y la independencia suficiente para cuestionar las suposiciones que generaron el primer resultado.
8. Saca los permisos del modelo
Algunas reglas nunca deberían depender de que el modelo las recuerde.
1nunca publicar sin aprobación2nunca exponer secretos3nunca exceder el límite de gasto4nunca escribir fuera del espacio de trabajo5nunca afirmar que las pruebas pasaron si no se ejecutaron
Estas no son sugerencias para el prompt.
Son políticas.
Una escala simple de permisos:
1BAJO RIESGO23leer4buscar5inspeccionar67-> automático89REVERSIBLE1011editar el espacio de trabajo12ejecutar pruebas13crear borradores1415-> automático + traza1617EFECTO EXTERNO1819enviar20desplegar21comprar2223-> requiere aprobación2425IRREVERSIBLE / SENSIBLE2627borrar datos28rotar credenciales29publicar globalmente3031-> bloqueo estricto o prohibido
Cuanto mayor sea la consecuencia, más fuerte debe ser el control.
El modelo puede recomendar la acción.
El harness la autoriza.
La herramienta la ejecuta.
La autonomía no es la ausencia de control.
Es libertad dentro de un límite impuesto.
9. Deja de reintentar a ciegas
Una de las peores políticas de recuperación es:
Algo falló. Inténtalo de nuevo.
Si nada cambia, el sistema simplemente está pagando por reproducir el mismo fallo.
Primero hay que clasificar los fallos.
1TIEMPO DE ESPERA AGOTADO EN LA HERRAMIENTA2-> reintentar con backoff34ARGUMENTOS INVÁLIDOS5-> reparar la llamada a la herramienta67CONTEXTO FALTANTE8-> recuperar la fuente faltante910PRUEBA FALLIDA11-> inspeccionar el comportamiento que falla1213PERMISO DENEGADO14-> solicitar aprobación1516REQUISITOS CONTRADICTORIOS17-> escalar1819FALLO REPETIDO SIN CAMBIOS20-> detener
Un ciclo de agente útil se ve así:
1OBSERVAR2 |3 v4DECIDIR5 |6 v7ACTUAR8 |9 v10MEDIR11 |12 +---- ACEPTAR13 |14 +---- REPARAR15 |16 +---- ESCALAR17 |18 +---- DETENER
Cada ciclo debería tener límites de intentos, tiempo, gasto y alcance destructivo.
Un agente confiable necesita saber cómo continuar.
También necesita saber cuándo otro intento ya no vale la pena.
10. Convierte las instrucciones repetidas en infraestructura
Supongamos que el prompt dice:
Ejecuta siempre el formateador.
Esa regla es más sólida si el formateador se ejecuta automáticamente.
Supongamos que las instrucciones dicen:
El código de UI no puede acceder directamente a la base de datos.
Eso es más sólido como una prueba de arquitectura que falla cuando se rompe la regla.
La progresión se ve así:
1EXPLICACIÓN2 |3 v4LISTA DE VERIFICACIÓN5 |6 v7PLANTILLA8 |9 v10COMPROBACIÓN AUTOMATIZADA11 |12 v13POLÍTICA IMPUESTA
El prompt debería explicar el criterio.
El harness debería imponer las invariantes.
Cada error recurrente debería avanzar un poco más en esta escalera.
Eventualmente, el modelo ya no necesitará recordar la lección.
El entorno la recordará por él.
11. Registra la ejecución
Un artefacto final perfecto puede ocultar una ruta de ejecución terrible.
Quizás el agente accedió a la fuente equivocada.
Quizás ignoró un comando fallido.
Quizás repitió una acción externa dos veces.
Quizás gastó diez veces el presupuesto esperado.
Quizás dio la respuesta correcta por la razón equivocada.
Registra suficiente información para reconstruir lo que pasó.
109:14 contrato de tarea creado209:15 architecture.md cargado309:17 checkout.ts editado409:18 prueba específica falló509:21 implementación reparada609:22 prueba específica pasó709:24 prueba de integración pasó809:25 despliegue bloqueado: se requiere aprobación
Las trazas útiles incluyen fuentes de contexto, llamadas a herramientas, cambios de estado, resultados de verificación, motivos de reintento, decisiones de aprobación, costo y latencia.
La idea no es recolectar logs por diversión.
La idea es localizar el fallo.
Si el paso 18 se rompe, deberías poder reparar el paso 18.
No deberías tener que repetir toda la ejecución.
12. Dale un recibo a cada ejecución
No obligues al humano a revisar una transcripción de cuarenta mensajes.
Resume el resultado en un recibo breve.
1OBJETIVO23Corregir la aplicación duplicada de cupones.45MODIFICADO67validación de checkout8prueba de regresión910VERIFICADO1112lint pasó13pruebas unitarias pasaron14prueba de integración pasó1516NO VERIFICADO1718proveedor de pagos de producción1920RIESGOS2122cliente móvil heredado no disponible2324APROBACIÓN NECESARIA2526desplegar a staging
Este no es un resumen de lo que el modelo afirma que pasó.
Es un resumen de lo que el harness puede probar que pasó.
Esa diferencia hace que el recibo sea útil para revisiones, entregas y futuras sesiones del agente.
13. Haz que cada fallo mejore el harness
La mayoría de los equipos corrige el resultado fallido.
El mejor enfoque es corregir el sistema que permitió el fallo.
1CONTEXTO FALTANTE2-> mejorar el mapa del proyecto34HERRAMIENTA INCORRECTA5-> mejorar el enrutamiento o el contrato de la herramienta67RESULTADO DEFICIENTE8-> agregar un validador910CICLO REPETITIVO11-> agregar un límite de reintentos1213ACCIÓN INSEGURA14-> agregar una puerta de enlace de permisos1516DECISIÓN PERDIDA17-> persistir el estado1819FALLO DESCONOCIDO20-> mejorar el trazado
Aquí es donde la ingeniería de harness empieza a generar un efecto compuesto.
Un resultado corregido ayuda a una ejecución.
Un harness corregido mejora todas las ejecuciones posteriores.
Los mejores sistemas de agentes se vuelven más confiables porque los errores dejan infraestructura detrás.
14. Empieza con el harness útil más pequeño
No necesitas una plataforma de orquestación enorme para empezar.
Construye por capas.
1NIVEL 023prompt4modelo56NIVEL 178contrato de tarea9mapa del proyecto10herramientas1112NIVEL 21314estado estructurado15verificación16ciclo acotado1718NIVEL 31920permisos21trazas22recuperación23puertas de enlace humanas
Una tarea corta de investigación quizás solo necesite un prompt y una revisión.
Una tarea de programación de seis horas con acceso a archivos, acceso a red y capacidad de despliegue necesita mucho más.
Agrega complejidad cuando la superficie de fallo lo justifique.
No porque la arquitectura de agentes se vea genial.
La lista de verificación de la Ingeniería de Harness
Antes de darle autonomía real a un agente, pregúntate:
1[ ] ¿El éxito está definido antes de la ejecución?23[ ] ¿Puede el agente encontrar el contexto correcto4 sin cargar absolutamente todo?56[ ] ¿Tiene cada herramienta un propósito claro,7 un esquema y un estado de fallo?89[ ] ¿Se almacenan las decisiones importantes10 fuera de la conversación?1112[ ] ¿La finalización requiere evidencia?1314[ ] ¿Las acciones riesgosas están protegidas por políticas?1516[ ] ¿Tiene cada ciclo un límite de reintentos?1718[ ] ¿Puede reanudarse la ejecución tras una interrupción?1920[ ] ¿Puedes reconstruir cada acción importante?2122[ ] ¿El fallo mejora alguna regla, herramienta,23 prueba, mapa o permiso?2425[ ] ¿Se puede revertir el cambio final?
Si varias respuestas son "no", un modelo más potente no hará que el agente sea confiable automáticamente.
Quizás solo haga que el fallo sea más rápido y más caro.
El verdadero cambio
La ingeniería de prompts pregunta:
¿Qué debo decirle al modelo?
La ingeniería de contexto pregunta:
¿Qué debería saber el modelo en este momento?
La ingeniería de harness pregunta:
¿Qué sistema le permite al modelo actuar, verificar su trabajo, recuperarse de los fallos y operar de forma segura?
1PROMPT2-> instrucción34CONTEXTO5-> vista de trabajo67HARNESS8-> entorno operativo910CICLO11-> corrección local1213GRAFO14-> coordinación
Los modelos seguirán cambiando.
La ventaja duradera vive a su alrededor.
Tus contratos mejoran.
Tus herramientas mejoran.
Tus pruebas mejoran.
Tu estado se vuelve más limpio.
Tus permisos se vuelven más seguros.
Tu lógica de recuperación se vuelve más inteligente.
Tus fallos se convierten en infraestructura.
Así es como los modelos capaces se transforman en agentes confiables.
Eso es la Ingeniería de Harness.
Si llegaste hasta aquí
Guarda esta guía en tus marcadores.
Sígueme en X: x.com/0xjmori
Suscríbete a mi Substack: substack.com/@lunarresearcher
Envíale este artículo a alguien que todavía intenta arreglar cada fallo de un agente con un prompt más largo.
![[Disculpa] Ya no recomiendo el trabajo freelance para lograr independencia.](/cdn-cgi/image/width=1920,quality=90,format=auto,metadata=none/https%3A%2F%2Fcms-assets.youmind.com%2Fmedia%2F1790615558140_ndvona_HTQ9s6laYAAX4J7.jpg)
