La mayoría de las personas intenta mejorar los agentes de IA en la capa equivocada.
Cuando un agente falla, reescriben el prompt.
Cuando vuelve a fallar, agregan más instrucciones.
Antes de empezar:
Luego cambian de modelo, agregan más herramientas, aumentan la ventana de contexto y esperan que la siguiente ejecución se comporte de manera diferente.
Pero muchos fallos de los agentes no son fallos de razonamiento.
Son fallos del entorno.
El agente no sabía qué archivos eran importantes.
Usó la herramienta correcta en el lugar equivocado.
Perdió las decisiones tomadas en la sesión anterior.
Afirmó éxito sin ejecutar las verificaciones.
Repitió una acción después de un fallo parcial.
Tenía permiso para hacer algo que debería haber requerido aprobación.
El modelo no era necesariamente el problema. El sistema alrededor del modelo estaba incompleto.
Ese sistema es el arnés.
Y diseñarlo se está convirtiendo en una disciplina de ingeniería propia.
La Ingeniería de Arnés es la práctica de construir el entorno que convierte la inteligencia del modelo en trabajo confiable.
Un prompt cambia un intento.
Un arnés cambia cada intento.
Esta guía explica cómo construir uno.
1. El Modelo No Es el Agente
Un modelo puede razonar, generar, comparar y elegir.
Pero un agente también debe interactuar con un entorno real.
Necesita:
- entender la tarea
- encontrar el contexto relevante
- seleccionar y usar herramientas
- preservar el estado
- respetar los permisos
- inspeccionar el resultado
- recuperarse de fallos
- demostrar que el trabajo está completo
El modelo es el motor de razonamiento dentro de ese sistema.
El arnés es todo lo que hace operativo el razonamiento.
1solicitud del usuario2 |3 v4+-----------------------------+5| ARNÉS |6| contrato | contexto | política|7| herramientas | estado | verificaciones |8| trazas | recuperación |9+-----------------------------+10 |11 v12 modelo13 |14 v15entorno real
Un modelo potente dentro de un arnés débil sigue siendo un agente débil.
Puede producir respuestas individuales impresionantes, pero se comportará de manera inconsistente en tareas largas, entornos cambiantes y fallos parciales.
El objetivo de la ingeniería de arnés no es eliminar la incertidumbre del modelo.
Es contener esa incertidumbre dentro de un sistema que pueda observar, verificar y recuperarse.
2. Empieza con un Contrato de Tarea
La mayoría de las tareas de los agentes comienzan como una intención vaga:
Mejorar el flujo de incorporación.
Esa frase puede ser suficiente para una conversación.
No es suficiente para una ejecución autónoma.
Antes de que el agente actúe, el arnés debe convertir la solicitud en un contrato de tarea.
Un contrato útil responde cinco preguntas:
- ¿Qué resultado debe existir?
- ¿Qué está dentro del alcance?
- ¿Qué no debe cambiar?
- ¿Qué evidencia demuestra la finalización?
- ¿Qué acciones requieren aprobación humana?
1objetivo: reducir la deserción en la incorporación23alcance:4 - flujo de registro5 - análisis de incorporación67restricciones:8 - no cambiar la autenticación9 - preservar el comportamiento móvil existente1011aceptación:12 - pruebas pasan13 - se emite el evento de análisis14 - capturas de pantalla cubren escritorio y móvil1516aprobación_requerida:17 - despliegue en producción18 - migración de base de datos
Esto cambia la pregunta del agente de:
¿Qué debería hacer después?
a:
¿Qué acción mueve el entorno hacia el resultado contratado?
Sin un contrato, el agente optimiza para una actividad plausible.
Con un contrato, puede optimizar para una finalización verificada.
3. Dale al Agente un Mapa, No un Manual
Volcar todo el repositorio, la documentación y el historial de la conversación en el contexto no es una buena ingeniería de contexto.
Es una inundación de contexto.
El arnés debe proporcionar primero un mapa pequeño, luego permitir que el agente recupere los detalles cuando sean relevantes.
1MAPA DEL PROYECTO23reglas del producto -> docs/producto/4arquitectura -> docs/arquitectura.md5frontend -> apps/web/6backend -> servicios/api/7pruebas -> tests/8comandos -> docs/comandos.md9reglas de lanzamiento -> docs/lanzamiento.md
Esto es divulgación progresiva:
1tarea2 -> mapa del proyecto3 -> subsistema relevante4 -> archivos exactos5 -> instrucciones locales
El contexto debe expandirse porque la tarea lo requiere, no porque la información exista.
Un buen compilador de contexto decide:
- qué se necesita siempre
- qué se puede recuperar después
- qué se ha vuelto obsoleto
- qué se puede resumir
- qué debe permanecer textual
El objetivo no es el máximo contexto.
Es la máxima señal por token.
4. Construye una Puerta de Enlace de Herramientas, No un Montón de Herramientas
Darle veinte herramientas a un agente no lo hace capaz.
Le da al agente veinte formas de cometer un error.
Cada herramienta debe tener un contrato claro:
1HERRAMIENTA: editar_archivo23entradas:4 ruta5 parche67precondiciones:8 la ruta existe9 la ruta está dentro del espacio de trabajo permitido1011evidencia de éxito:12 parche aplicado13 diff resultante devuelto1415comportamiento en fallo:16 sin sobrescritura parcial17 error estructurado devuelto1819clase de riesgo:20 reversible
El arnés debe controlar cómo se exponen y utilizan las herramientas.
Puede:
- ocultar herramientas irrelevantes
- validar argumentos
- restringir rutas y dominios
- adjuntar tiempos de espera
- hacer que los reintentos sean idempotentes
- normalizar las salidas
- requerir confirmación para acciones riesgosas
- devolver evidencia, no solo "éxito"
Esto crea una separación importante:
1el modelo decide la intención2la puerta de enlace valida la acción3la herramienta cambia el entorno4el sensor observa el resultado
El modelo puede proponer una acción.
La puerta de enlace de herramientas decide si esa acción es lo suficientemente válida para ejecutarse.
5. Separa el Cerebro, las Manos y el Historial
Muchos agentes frágiles mezclan todo en una transcripción cada vez más grande.
El razonamiento, las llamadas a herramientas, los archivos, las decisiones, los errores y las observaciones antiguas compiten por la misma ventana de contexto.
Un sistema más robusto separa tres responsabilidades:
1CEREBRO2planea, razona, elige34MANOS5ejecutan herramientas dentro de un entorno controlado67HISTORIAL8almacena hechos duraderos, decisiones y estado de ejecución
El modelo no necesita cada evento en bruto en el contexto activo.
Necesita el estado actual correcto.
El entorno aislado no necesita entender el objetivo completo.
Necesita ejecutar de forma segura una acción limitada.
El registro de la sesión no necesita razonar.
Necesita preservar lo que sucedió después de que el contexto actual desaparezca.
Esta separación facilita reanudar, inspeccionar y reparar agentes de larga duración.
También te permite reemplazar una parte sin reconstruir todo el sistema.
6. La Memoria Debe Convertirse en Estado Duradero
El historial de la conversación no es una memoria confiable.
Es un flujo de eventos.
La memoria útil debe convertirse en estado explícito.
Como mínimo, preserva cuatro categorías:
1HECHOS2información estable descubierta sobre el entorno34DECISIONES5elecciones tomadas y la razón detrás de ellas67PROGRESO8trabajo completado, activo, bloqueado y restante910LECCIONES11fallos que deberían cambiar el comportamiento futuro
Por ejemplo:
1hechos:2 - la validación del pago está en servicios/pedidos34decisiones:5 - reutilizar el pipeline de validación existente6 - razón: evita una segunda fuente de verdad78progreso:9 completado:10 - agregó regla del lado del servidor11 restante:12 - actualizar prueba de integración1314lecciones:15 - el comando de prueba local requiere TEST_DB_URL
Esto es mucho más útil que reproducir cincuenta páginas de transcripción y esperar que el modelo note la línea importante.
Almacena el historial en bruto para fines de auditoría.
Compila el estado duradero para la ejecución.
7. La Finalización Requiere Evidencia
Que un agente diga "listo" no es evidencia de que la tarea esté completa.
Es solo otra salida del modelo.
La finalización debe decidirse mediante cambios observables en el entorno.
1afirmación evidencia2--------------------------------------------------3"el error está corregido" la prueba que fallaba ahora pasa4"la página funciona" el flujo del navegador se completó5"la migración es segura" la ejecución en seco y el rollback pasan6"el informe es correcto" los valores coinciden con los datos fuente7"la tarea está completa" cada verificación de aceptación pasa
El arnés debe ejecutar primero las verificaciones deterministas más baratas.
1sintaxis2 -> tipos3 -> pruebas enfocadas4 -> pruebas de integración5 -> revisión visual o semántica6 -> aprobación humana
No uses otro modelo donde un compilador, esquema, suma de verificación, consulta o prueba pueda responder la pregunta.
Usa modelos para la ambigüedad.
Usa código para la infraestructura.
Un modelo puede proponer que la tarea está completa.
Solo el entorno puede demostrarlo.
8. La Verificación Debe Atacar el Resultado
Los trabajadores y los evaluadores no deben compartir el mismo objetivo.
El trabajador intenta crear la solución más sólida.
El evaluador intenta encontrar la razón por la que debería ser rechazada.
1trabajador2 -> produce un candidato34verificador5 -> verifica el contrato6 -> busca casos faltantes7 -> prueba afirmaciones no respaldadas8 -> intenta romper el resultado910sobrevive11 -> aceptar1213falla14 -> devolver evidencia específica
Esta asimetría es importante.
Si le pides al mismo agente, en el mismo contexto, que "verifique su trabajo", a menudo preserva las suposiciones que crearon el error.
Una etapa de verificación útil debe tener:
- una rúbrica de rechazo explícita
- acceso al artefacto producido
- acceso al contrato de aceptación
- herramientas independientes o contexto nuevo cuando sea necesario
- permiso para rechazar sin reparar
La verificación no es una segunda opinión.
Es un intento de refutación.
9. El Modelo Propone, la Política Autoriza
Algunas reglas nunca deben depender de si el modelo las recuerda.
1nunca publicar sin aprobación2nunca exponer un secreto3nunca escribir fuera del espacio de trabajo4nunca exceder el límite de gasto5nunca marcar pruebas como aprobadas a menos que se hayan ejecutado
Estas no son sugerencias de prompt.
Son políticas.
El diseño más seguro mantiene la política fuera del bucle de razonamiento.
1RIESGO BAJO2leer archivos, buscar, inspeccionar3-> automático45CAMBIO REVERSIBLE6editar espacio de trabajo, ejecutar pruebas7-> automático con traza89EFECTO EXTERNO10enviar mensaje, desplegar, comprar11-> aprobación explícita1213IRREVERSIBLE O SENSIBLE14eliminar datos, rotar credenciales, publicar globalmente15-> barrera fuerte o prohibido
Cuanto más fuerte sea la consecuencia, más dura será la barrera.
La autonomía no es la ausencia de control.
Es la capacidad de operar libremente dentro de un límite claramente definido.
10. La Recuperación Debe Apuntar a la Clase de Falla
La estrategia de recuperación más común es:
Algo falló. Inténtalo de nuevo.
Eso no es recuperación.
Es repetición.
El arnés debe clasificar el fallo antes de seleccionar la siguiente acción.
1tiempo de espera de la herramienta2-> reintentar con retroceso34argumentos inválidos5-> reparar la llamada a la herramienta67contexto faltante8-> recuperar la fuente específica910prueba fallida11-> inspeccionar el comportamiento fallido1213permiso denegado14-> solicitar aprobación o elegir una ruta segura1516requisitos contradictorios17-> escalar a un humano1819fallo repetido sin cambios20-> detener el bucle
Un reintento debe cambiar al menos una condición relevante.
De lo contrario, el sistema está pagando para reproducir el mismo fallo.
Un bucle de agente acotado se ve así:
1observar2 -> decidir3 -> actuar4 -> medir5 -> aceptar6 -> reparar7 -> escalar8 -> detener
Cada bucle necesita un presupuesto:
- intentos máximos
- tiempo máximo
- gasto máximo
- alcance destructivo máximo
- condición de escalamiento
Los agentes confiables saben cómo continuar.
También saben cuándo continuar ya no es racional.
11. Las Instrucciones Deben Convertirse en Infraestructura
Las instrucciones del agente son útiles cuando explican la realidad local.
Pero las instrucciones por sí solas son una aplicación débil.
Si una regla importa repetidamente, muévela hacia abajo en la pila.
1"usa el formateador"2-> ejecutar el formateador automáticamente34"no importes a través de capas"5-> agregar prueba de arquitectura67"incluye un rollback de migración"8-> requerir archivo de rollback en CI910"no modifiques archivos generados"11-> bloquear escrituras en rutas generadas1213"cita cada afirmación externa"14-> validar la cobertura de citas
Esto crea una escalera de instrucciones:
1explicación2 -> lista de verificación3 -> plantilla4 -> verificación automatizada5 -> política aplicada
Mueve el conocimiento importante lo más abajo posible en esa escalera.
El prompt debe explicar el juicio.
El arnés debe hacer cumplir los invariantes.
12. Observa la Ejecución, No Solo la Respuesta Final
Un artefacto final limpio puede ocultar un proceso terrible.
El agente puede haber:
- accedido a los datos incorrectos
- ignorado un comando fallido
- reintentado una acción externa dos veces
- consumido diez veces el presupuesto esperado
- llegado a la respuesta correcta por la razón equivocada
Necesitas trazas que hagan que la ejecución sea reconstruible.
109:14 contrato creado209:15 fuente de contexto cargada: arquitectura.md309:17 archivo editado: checkout.ts409:18 prueba enfocada falló: cupón duplicado509:21 implementación reparada609:22 prueba enfocada pasó709:24 prueba de integración pasó809:25 despliegue externo bloqueado: se requiere aprobación
Una traza útil registra:
- transiciones de estado
- fuentes de contexto
- entradas y salidas de herramientas
- cambios en el entorno
- resultados de verificación
- razones de reintento
- decisiones de aprobación
- costo y latencia
El objetivo no es la vigilancia.
El objetivo es la reparación local.
Cuando una ejecución falla en el paso 18, deberías poder reiniciar desde un punto de control confiable en lugar de reproducir toda la tarea.
13. Cada Ejecución Necesita un Recibo de Cambios
Las transcripciones largas de los agentes son difíciles de revisar.
Al final de una ejecución, el arnés debe compilar un pequeño recibo de cambios.
1OBJETIVO2Corregir la aplicación de cupones duplicados durante el pago.34CAMBIADO5- lógica de validación del pago6- prueba de regresión enfocada78VERIFICADO9- lint pasó10- pruebas unitarias pasaron11- prueba de integración del pago pasó1213NO VERIFICADO14- proveedor de pago en producción1516DECISIONES17- preservó el orden de prioridad de cupones existente1819RIESGOS20- el cliente móvil heredado no estaba disponible localmente2122APROBACIÓN NECESARIA23- desplegar en staging
El recibo no es un resumen de lo que dijo el modelo.
Es un resumen de lo que el sistema puede demostrar.
Esto les da a los humanos una superficie de revisión compacta y le da a la próxima sesión del agente un punto de partida confiable.
La mejor transferencia no es "aquí está la conversación".
Es "aquí está el estado, la evidencia y el riesgo no resuelto".
14. Cada Falla Debe Mejorar el Arnés
Los equipos más débiles corrigen la salida fallida.
Los equipos más fuertes también corrigen el sistema que lo permitió.
Después de un fallo, pregúntate:
1¿El contrato de la tarea era ambiguo?2¿El contexto importante era invisible?3¿Se expuso la herramienta incorrecta?4¿Faltaba una precondición?5¿El resultado no era verificable?6¿La política se dejó dentro del prompt?7¿La recuperación era demasiado amplia?8¿La traza era insuficiente?
Luego convierte la lección en una mejora reutilizable.
1fallo2 -> diagnóstico3 -> nuevo sensor, regla, mapa, prueba o contrato de herramienta4 -> las ejecuciones futuras mejoran automáticamente
Este es el volante del arnés.
El sistema se vuelve más confiable porque los fallos dejan infraestructura atrás.
Una respuesta corregida ayuda a una ejecución.
Un arnés corregido ayuda a cada ejecución futura.
15. Los Arnés También se Deterioran
Más arnés no siempre es mejor.
Los modelos mejoran. Las herramientas mejoran. Las tareas cambian. Las salvaguardas antiguas pueden convertirse en fricción innecesaria.
Una solución alternativa creada para el modelo de ayer puede impedir que el modelo de hoy use una mejor estrategia.
Esto crea deterioro del arnés:
1limitación del modelo antiguo2 -> solución alternativa del arnés3 -> el modelo mejora4 -> la solución alternativa permanece5 -> el sistema se vuelve más lento o menos capaz
Trata los componentes del arnés como código de producción.
Mide si todavía proporcionan valor.
Para cada enrutador, evaluador, capa de memoria y regla de reintento, pregúntate:
- ¿Qué fallo previene esto?
- ¿Con qué frecuencia ocurre ese fallo todavía?
- ¿Qué latencia y complejidad agrega esto?
- ¿Se puede lograr el mismo resultado ahora de manera más simple?
- ¿Qué pasa si lo eliminamos?
El mejor arnés no es el más grande.
Es el sistema más pequeño que cierra de manera confiable la brecha entre la intención y la evidencia.
Construye para eliminar.
16. El Arnés Mínimo Viable
No necesitas una plataforma de orquestación para empezar.
Construye el arnés en capas.
Nivel 1: Una tarea acotada
- objetivo
- alcance
- restricciones
- verificaciones de aceptación
Nivel 2: Un entorno legible
- mapa del proyecto
- comandos
- instrucciones locales
- dependencias conocidas
Nivel 3: Acciones controladas
- herramientas tipadas
- validación de argumentos
- límites de ruta y permiso
- resultados estructurados
Nivel 4: Ejecución duradera
- estado de ejecución explícito
- puntos de control
- decisiones
- lecciones
Nivel 5: Evidencia
- verificaciones deterministas
- verificación adversarial
- recibo de cambios
Nivel 6: Recuperación y aprendizaje
- clasificación de fallos
- reintentos acotados
- escalamiento
- actualizaciones del arnés a partir de fallos recurrentes
Construye la capa más pequeña que elimine el fallo que realmente tienes.
No empieces con una arquitectura multiagente porque un solo prompt ocasionalmente necesita aclaración.
La complejidad debe ganarse mediante fallos observados.
17. Una Especificación de Arnés Reutilizable
Antes de darle a un agente una autonomía significativa, define esto:
1ESPECIFICACIÓN DEL ARNÉS DEL AGENTE231. CONTRATO4 objetivo:5 alcance:6 restricciones:7 evidencia de aceptación:892. CONTEXTO10 mapa siempre cargado:11 fuentes de recuperación:12 instrucciones locales:13 reglas de actualización:14153. HERRAMIENTAS16 herramientas permitidas:17 precondiciones:18 efectos secundarios:19 evidencia de éxito:20 política de tiempo de espera y reintento:21224. ESTADO23 hechos:24 decisiones:25 progreso:26 lecciones:27 formato del punto de control:28295. POLÍTICA30 acciones automáticas:31 acciones que requieren aprobación:32 acciones prohibidas:33 límites de presupuesto:34356. VERIFICACIÓN36 verificaciones deterministas:37 verificaciones adversariales:38 regla de aceptación:39407. RECUPERACIÓN41 clases de fallo:42 límites de reintento:43 condiciones de escalamiento:44 rollback seguro:45468. OBSERVABILIDAD47 eventos de traza:48 métricas:49 recibo de cambios final:
Si estos campos no están definidos, el agente no es autónomo.
Está improvisando.
18. Mide el Sistema en el Nivel Correcto
El recuento de tokens no es la métrica final.
Tampoco lo es el número de tareas intentadas.
La unidad útil es el trabajo aceptado.
Una métrica práctica es:
1salidas aceptadas2------------------------------3minutos de revisión humana + costo de ejecución
También rastrea:
- tasa de aceptación en el primer intento
- tasa de recuperación después de un fallo de herramienta
- tasa de fallos repetidos
- intervenciones humanas por tarea
- afirmaciones de finalización no respaldadas
- tiempo desde la solicitud hasta el resultado verificado
- sobrecarga del arnés por componente
Esto evita una ilusión común:
Un agente puede parecer muy productivo mientras crea un trabajo de revisión costoso.
El objetivo no es más actividad del agente.
Son más resultados confiables por unidad de atención humana.
19. Cuando No Necesitas un Arnés Pesado
No cada llamada al modelo necesita un sistema operativo.
Usa un prompt simple cuando:
- la tarea es corta
- la salida es fácil de inspeccionar
- el fallo es barato
- no ocurre ningún efecto secundario externo
- el usuario permanece en el bucle
Agrega un arnés cuando:
- el trabajo abarca múltiples herramientas o sesiones
- el entorno puede cambiar
- las acciones tienen consecuencias reales
- la finalización es difícil de juzgar manualmente
- el mismo fallo aparece repetidamente
- la revisión humana se convierte en el cuello de botella
El propósito de un arnés no es hacer que una demo se vea sofisticada.
Es hacer que el trabajo real sea confiable.
El Cambio Real
La primera generación de productos de IA se construyó alrededor de prompts.
La próxima generación se está construyendo alrededor de entornos.
La pregunta ya no es solo:
¿Cómo hacemos que el modelo responda mejor?
Es:
¿Cómo construimos un sistema donde las buenas acciones sean fáciles, las acciones peligrosas estén controladas, los fallos sean visibles y la finalización sea demostrable?
Ese es el cambio de la ingeniería de prompts a la ingeniería de arnés.
El modelo proporciona inteligencia.
El arnés proporciona estructura.
Juntos producen una ejecución confiable.
Si tu agente sigue desmoronándose, deja de agregar adjetivos al prompt.
Construye el entorno que necesita para tener éxito.
Si Llegaste Hasta Aquí
Guarda esta guía como favorito.
Envía este artículo a alguien que todavía esté tratando de arreglar cada fallo de agente con un prompt más largo.
