La mayoría de la gente intenta mejorar los agentes de IA en la capa equivocada.
Cuando un agente falla, reescriben el prompt.
Cuando vuelve a fallar, añaden más instrucciones.
Antes de empezar:
Luego cambian de modelo, añaden más herramientas, amplían 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.
Reclamó éxito sin ejecutar las comprobaciones.
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 fiable.
Un prompt cambia un intento.
Un arnés cambia todos los intentos.
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 | comprobaciones |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 lo es 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 a cinco preguntas:
- ¿Qué resultado debe existir?
- ¿Qué está dentro del alcance?
- ¿Qué no debe cambiar?
- ¿Qué evidencia prueba la finalización?
- ¿Qué acciones requieren aprobación humana?
1objetivo: reducir el abandono 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 - evento de análisis se emite14 - 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, el conjunto de 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, y 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 a un agente veinte herramientas no lo hace capaz.
Le da al agente veinte maneras 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 arriesgadas
- 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 que crece sin parar.
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:
1CEREBRO2planifica, 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 sandbox no necesita entender el objetivo completo.
Necesita ejecutar de forma segura una acción acotada.
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 fiable.
Es un flujo de eventos.
La memoria útil debe convertirse en un 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 - añadida 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 esperando que el modelo note la línea importante.
Almacena el historial en bruto para 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 por 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 simulación y el rollback pasan6"el informe es correcto" los valores coinciden con los datos fuente7"la tarea está completa" cada comprobación de aceptación pasa
El arnés debe ejecutar primero las comprobaciones 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 fontanería.
Un modelo puede proponer que la tarea está completa.
Solo el entorno puede probarlo.
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 candidato34verificador5 -> comprueba 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 "vuelva a verificar 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 pasadas 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-> puerta dura o prohibido
Cuanto más fuerte sea la consecuencia, más dura será la puerta.
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 Fallo
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 herramienta2-> reintentar con retroceso34argumentos inválidos5-> reparar la llamada a la herramienta67contexto faltante8-> recuperar fuente específica910prueba fallida11-> inspeccionar comportamiento fallido1213permiso denegado14-> solicitar aprobación o elegir ruta segura1516requisitos contradictorios17-> escalar a 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:
- máximo de intentos
- tiempo máximo
- gasto máximo
- alcance destructivo máximo
- condición de escalado
Los agentes fiables 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 formateador automáticamente34"no importes entre capas"5-> añadir 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 cobertura de citas
Esto crea una escalera de instrucciones:
1explicación2 -> lista de verificación3 -> plantilla4 -> comprobación automatizada5 -> política aplicada
Mueve el conocimiento importante tan abajo en esa escalera como sea práctico.
El prompt debe explicar el juicio.
El arnés debe aplicar 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 equivocados
- 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 la ejecución 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: aprobación requerida
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 fiable en lugar de reproducir toda la tarea.
13. Cada Ejecución Necesita un Recibo de Cambios
Las transcripciones largas de 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 de pago6- prueba de regresión enfocada78VERIFICADO9- lint pasó10- pruebas unitarias pasaron11- prueba de integración de pago pasó1213NO VERIFICADO14- proveedor de pagos en producción1516DECISIONES17- preservado 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 probar.
Esto le da a los humanos una superficie de revisión compacta y a la próxima sesión del agente un punto de partida fiable.
La mejor transferencia no es "aquí está la conversación".
Es "aquí está el estado, la evidencia y el riesgo no resuelto".
14. Cada Fallo 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¿Era ambiguo el contrato de la tarea?2¿Era invisible el contexto importante?3¿Se expuso la herramienta equivocada?4¿Faltaba una precondición?5¿Era el resultado no verificable?6¿Se dejó la política dentro del prompt?7¿Era la recuperación demasiado amplia?8¿Era la traza 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 de inercia del arnés.
El sistema se vuelve más fiable porque los fallos dejan infraestructura detrás.
Una respuesta corregida ayuda a una ejecución.
Un arnés corregido ayuda a todas las ejecuciones futuras.
15. Los Arnses 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 estrategia mejor.
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 añadido.
Para cada enrutador, evaluador, capa de memoria y regla de reintento, pregúntate:
- ¿Qué fallo previene esto?
- ¿Con qué frecuencia ocurre todavía ese fallo?
- ¿Qué latencia y complejidad añade esto?
- ¿Se puede lograr el mismo resultado ahora de forma 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 forma fiable 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 por capas.
Nivel 1: Una tarea acotada
- objetivo
- alcance
- restricciones
- comprobaciones 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
- comprobaciones deterministas
- verificación adversarial
- recibo de cambios
Nivel 6: Recuperación y aprendizaje
- clasificación de fallos
- reintentos acotados
- escalado
- 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 multi-agente porque un prompt único 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 comprobaciones deterministas:37 comprobaciones adversariales:38 regla de aceptación:39407. RECUPERACIÓN41 clases de fallo:42 límites de reintento:43 condiciones de escalado: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 previene una ilusión común:
Un agente puede parecer muy productivo mientras crea un costoso trabajo de revisión.
El objetivo no es más actividad del agente.
Son más resultados fiables por unidad de atención humana.
19. Cuándo No Necesitas un Arnés Pesado
No todas las llamadas al modelo necesitan 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
Añade 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 parezca sofisticada.
Es hacer que el trabajo real sea fiable.
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 fiable.
Si tu agente sigue desmoronándose, deja de añadir adjetivos al prompt.
Construye el entorno que necesita para tener éxito.
Si Has Llegado Hasta Aquí
Guarda esta guía como favorito.
Envía este artículo a alguien que todavía esté intentando arreglar cada fallo de agente con un prompt más largo.
