5 de octubre de 2026
# Harness engineering a fondo: anatomía completa de un agente de IA
> [!NOTE]- ¿Qué es esto?
> Una versión en castellano, revisada y ampliada, de *Understanding Harness Engineering*, el manual técnico que publicó **@techNmak** en X el 4 de octubre de 2026[^1]. El original son 48 páginas y 43 apartados cortos, y es de lo mejor que he leído sobre el tema: ordena muy bien qué hace falta alrededor de un modelo para que trabaje como agente.
>
> Esto no es una traducción. Partimos de su estructura y de sus ideas, que son suyas, y hemos hecho cuatro cosas:
>
> - **Corregir** dos errores concretos: el estado de la extensión Tasks de MCP y la salida del diagrama del bucle.
> - **Comprobar** contra la fuente original las cifras que cita, y señalar de qué tipo es cada fuente (paper revisado, preprint, documentación de producto, informe de un proveedor).
> - **Añadir** lo que se queda corto: un caso práctico que recorre todo el documento, qué pasa exactamente cuando una acción falla a mitad, cómo se mide si un harness mejora algo, y qué dicen los papers sobre agentes que hacen trampa con los tests.
> - **Juntar** lo que se repetía, para que se lea de corrido y no como 43 fichas.
> - **Ordenar** el conjunto con una idea que el original no tiene: el harness existe para que las acciones del modelo estén acotadas, sean observables, recuperables y verificables.
>
> Se mantienen sus distinciones, sus preguntas de revisión y su mapa final. La notación matemática se ha pasado a texto. La idea de agrupar todo en cuatro propiedades sale del análisis crítico del original que preparamos antes de escribir. Las cifras principales que cita coinciden con sus fuentes; algunas secundarias (AgentDojo, ToolSandbox, SWE-agent) se toman del original.
>
> Es divulgación detallada, no investigación nueva. Fecha de corte: 4 de octubre de 2026. Muchas de las referencias son productos en beta o en preview y van a cambiar en meses; los principios, bastante menos.
---
> Llevo meses usando la palabra *harness* en la web, casi siempre con la definición corta: todo lo que rodea a la IA y no es el modelo. Es una buena definición para empezar, pero para diseñar algo se queda corta. Aquí va bajada a piezas concretas, con fuentes.
> [!abstract] La idea central
> Dos agentes con el mismo modelo se pueden comportar de forma muy distinta. La diferencia está en el harness: qué ve el modelo, qué herramientas tiene y dónde se ejecutan sus acciones. También qué se guarda entre pasos, qué pasa cuando algo falla y quién comprueba que el trabajo está bien hecho.
> [!info]- Qué vas a poder explicar al terminar
> - Por qué una llamada a un modelo todavía no es un agente, y cómo funciona el bucle mínimo.
> - En qué se diferencian modelo, harness, sesión, herramienta y sandbox.
> - Por qué el diseño de una herramienta cambia lo que hace el agente, y qué deja sin resolver MCP.
> - Por qué el contexto activo no es la memoria y por qué compactar pierde información.
> - Qué resuelven por separado los permisos, la contención, las credenciales y las aprobaciones.
> - Por qué reintentar es peligroso con acciones que no son idempotentes.
> - Por qué el agente diciendo "hecho" no es una prueba, y cómo se trampea un test.
> - Cuándo compensan los subagentes y cuándo cuesta más coordinarlos que hacer el trabajo.
> - Cómo medir si un cambio en el harness mejora algo, y por qué hay que repetirlo con cada modelo.
>
> **Lo que hace falta saber antes**: qué es una llamada a un modelo, qué es el *function calling* y qué es la ventana de contexto, y algo de software normal. **Lo que no es**: un manual completo de MCP, de seguridad de agentes o de sistemas distribuidos, ni un catálogo de frameworks.
> [!warning] El hueco principal de evidencia
> Casi todo lo que sabemos de harnesses en producción lo cuentan los propios proveedores: Anthropic, OpenAI, Microsoft y Google. Son la mejor fuente para saber cómo han diseñado sus sistemas. Pero rara vez son experimentos controlados y reproducibles. La investigación independiente va creciendo, aunque todavía va por detrás.
## 1. Un modelo no es un agente
Una llamada a un modelo de lenguaje es muy sencilla. Le das un texto, que llamamos contexto, y te devuelve otro. Esa llamada no ejecuta comandos, no abre un navegador, no cambia ficheros y no reintenta nada. El modelo genera texto, y ya está.
Un sistema agéntico añade un proceso de control por fuera del modelo. La forma más útil de pensarlo es esta:
`sistema agéntico ≈ modelo + harness + entorno`
No es una igualdad formal; sirve para ordenar la cabeza:
- **El modelo** aporta la capacidad aprendida.
- **El harness** decide cómo se conecta esa capacidad con acciones, y cómo se repite a lo largo del tiempo.
- **El entorno** es lo de fuera que esas acciones leen o cambian: ficheros, bases de datos, APIs, una web.
Anthropic distingue entre *workflows* y *agentes*[^4]. En un workflow, el camino lo fija el código de la aplicación. En un agente, el modelo elige qué acciones tomar y en qué orden. Esa diferencia es más útil que "chatbot o agente", que ya es una etiqueta de marketing. Hay agente cuando lo que genera el modelo entra en un bucle controlado que actúa sobre algo de fuera.
En la práctica, casi ningún sistema serio es solo una cosa. Una aplicación puede tener fases fijas, como validar siempre la identidad del cliente o registrar siempre la operación. Y puede tener fases donde decide el modelo, como qué preguntar o qué herramienta usar. Todo sobre el mismo entorno. Microsoft lo resume con una regla buena: si quieres que la IA decida *cómo* hacer algo, usa una skill; si necesitas garantizar *qué* pasos se ejecutan y en qué orden, usa un workflow[^26].
### La prueba de que el harness cambia el resultado
El mejor ejemplo público es el *postmortem* que Anthropic publicó el 23 de abril de 2026 sobre Claude Code[^19]. Durante semanas, mucha gente notó que funcionaba peor. La API y el modelo seguían igual, y lo que había cambiado eran tres decisiones del producto:
- **El esfuerzo de razonamiento por defecto** bajó de `high` a `medium` el 4 de marzo, para que la interfaz no pareciera congelada. Se revirtió el 7 de abril, porque los usuarios preferían más inteligencia.
- **Un error al limpiar el razonamiento antiguo.** La limpieza debía hacerse una vez tras un rato de inactividad, y se repetía en cada turno. Claude parecía olvidadizo y repetitivo. Duró del 26 de marzo al 10 de abril.
- **Una instrucción para reducir la verbosidad**: "mantén el texto entre llamadas a herramientas en 25 palabras o menos". Provocó una caída del 3% en una de sus evaluaciones, con Opus 4.6 y con 4.7. Duró del 16 al 20 de abril.
El mismo modelo, con tres ajustes del harness, se comportaba distinto. Por eso existe este documento.
## 2. Vocabulario: cada pieza por su nombre
La terminología es jovencísima, y cada proveedor la usa un poco a su manera:
- **Microsoft** llama *agent harness* al andamiaje que convierte un modelo en un agente. Incluye llamadas al modelo y a herramientas, estado, contexto, aprobaciones y avance en tareas de varios pasos[^15].
- **Anthropic** separa tres piezas en su arquitectura de Managed Agents: sesión, harness y sandbox[^12].
- **OpenAI** usa *harness engineering* en un sentido más amplio. Lo aplica a todo el trabajo de preparar el entorno, el repositorio, las reglas y la observabilidad para que los agentes trabajen bien[^10].
Aquí usamos esta distinción, que es una elección editorial y no un estándar:
- **Harness del agente**: la maquinaria de ejecución y control que rodea al modelo y le permite actuar durante varios pasos.
- **Harness engineering**: la disciplina de diseñar todo lo que hace fiable ese trabajo. Interfaces, contexto, estado, entorno, controles, feedback, recuperación y verificación.
Y estos son los términos del documento, siempre con el mismo nombre:
| Término | Qué es |
| --- | --- |
| Modelo | El sistema de inferencia entrenado |
| Agente | El modelo trabajando dentro de un bucle de acciones hacia una tarea |
| Harness | La maquinaria de ejecución y control que mueve ese bucle |
| Sesión | El contenedor del historial y el estado de un trabajo en curso; cuánto dura depende de la implementación |
| Contexto | La información que recibe el modelo en una llamada concreta |
| Herramienta | Una capacidad que el modelo puede invocar |
| Sandbox | Un entorno de ejecución controlado y aislado |
| Workflow | Una estructura de ejecución fijada en su mayor parte por código |
| Harness de evaluación | La infraestructura que ejecuta y puntúa evaluaciones |
Estas piezas se pueden implementar juntas o separadas. Aun así, conviene pensarlas por separado, porque fallan de forma distinta. Que el modelo se equivoque no es lo mismo que se caiga el harness. Y ninguna de las dos cosas es lo mismo que el código generado intente leer una credencial del sandbox.
> [!info]- Qué tipo de fuente es cada cosa
> Una cita numerada te dice dónde está la fuente, pero no cuánto fiarte de ella. Por eso cada referencia del final lleva su tipo: **paper revisado** (aceptado en una conferencia o revista), **preprint** (publicado en arXiv sin revisión), **informe de proveedor** (un equipo contando su propio sistema), **documentación** (cómo dice el producto que funciona hoy), **estándar** (RFC, especificación) o **análisis independiente**. Un informe de proveedor es la mejor fuente para saber cómo han diseñado algo. Para saber si funciona mejor que la alternativa, es una fuente floja.
### Para qué sirve todo esto: cuatro propiedades
Hay muchas piezas, y hace falta una idea que las agrupe. Proponemos esta, que no es ningún estándar: el harness existe para que las acciones del modelo cumplan cuatro propiedades.
| Propiedad | Qué pregunta responde | Qué piezas la dan | Dónde se ve |
| --- | --- | --- | --- |
| Acotadas | ¿Qué puede alcanzar el agente aunque todo lo demás falle? | Permisos, sandbox, credenciales, red, presupuestos | Apartados 8 y 9 |
| Observables | ¿Sabe el agente, y sabes tú, qué ha pasado? | Resultados y errores con información, origen de cada dato, logs, trazas | Apartados 5, 7 y 10 |
| Recuperables | ¿Se puede seguir tras un fallo sin duplicar nada? | Estado duradero, registro de sesión, idempotencia, un solo escritor | Apartados 7 y 9 |
| Verificables | ¿Hay forma de saber que está bien hecho sin fiarse del modelo? | Estado externo, tests fuera de su alcance, evaluadores comprobados | Apartados 10 y 12 |
El contexto y el diseño de las herramientas no son una quinta propiedad. Son decisiones que afectan a las cuatro. Y la tabla sirve como prueba rápida: si una pieza del harness no mejora ninguna de las cuatro, sobra.
## 3. El bucle mínimo
En cada paso del bucle pasan cuatro cosas, siempre en el mismo orden:
1. **El harness elige el contexto.** Mira el estado del trabajo y decide qué información le pasa al modelo.
2. **El modelo responde.** Su respuesta puede ser final o pedir una acción.
3. **El entorno ejecuta.** Si hay acción y está permitida, se ejecuta y devuelve un resultado.
4. **El harness actualiza el estado** con lo que ha pedido el modelo y lo que ha devuelto el entorno.
El modelo solo controla el paso 2. Elegir el contexto, ejecutar y actualizar el estado son trabajo del harness.
_El bucle mínimo. La salida final pasa por una comprobación antes de dar la tarea por hecha, y agotar el presupuesto es una salida distinta._
Hay dos formas de salir del bucle, y son estados distintos. Una es terminar la tarea y comprobarla; la otra, agotar el presupuesto sin conseguirlo.
Cualquier *runner* moderno hace una variante de esto[^44]. El antecedente de investigación más conocido es ReAct, de 2022[^2]. Allí el modelo alterna razonamiento y acciones, y lo que observa fuera cambia lo que decide después. La idea de fondo sigue igual: actuar, observar, actualizar y seguir.
## 4. El caso que vamos a seguir: un agente de reembolsos
Para ver cómo encajan las decisiones entre sí, usamos un solo caso de principio a fin.
Una tienda online quiere un agente que atienda reclamaciones de reembolso. Le llega el correo de un cliente y consulta el pedido. Decide si el reembolso procede según la política de la tienda. Si procede, lo emite y contesta al cliente. Tiene cuatro herramientas:
- `buscar_pedido(pedido_id)`
- `emitir_reembolso(pedido_id, importe, clave_idempotencia)`
- `enviar_respuesta(ticket_id, texto)`
- `escalar_a_persona(ticket_id, motivo)`
Es un caso pequeño, pero tiene casi todo lo que hace difícil un agente de verdad:
- entra texto de alguien que no controlas: el correo del cliente;
- hay datos privados: el pedido y el historial;
- hay dinero de por medio;
- hay dos acciones que no se pueden repetir alegremente: reembolsar y enviar un correo;
- y hay una forma objetiva de saber si se ha hecho bien: el estado en el sistema de pagos.
La primera decisión de diseño no es técnica. Es de reparto: quién decide cada cosa, quién la ejecuta y quién la comprueba.
| Decisión | Quién decide | Quién ejecuta | Quién comprueba |
| --- | --- | --- | --- |
| Si el reembolso procede según la política | El modelo, con la política en el contexto | - | Una regla en código (importe ≤ pedido, dentro de plazo) y una persona por encima de un umbral |
| Cuánto se puede reembolsar sin aprobación | El negocio, en la configuración de la aplicación | El harness aplica la regla antes de ejecutar | El registro de auditoría |
| Qué puede alcanzar el código del agente | Quien diseña la infraestructura | El sandbox y el proxy de red | Pruebas periódicas de esas fronteras |
| Si el reembolso se ha hecho | - | La API de pagos | Una consulta al sistema de pagos, no la palabra del modelo |
| Si el agente es bueno | - | El harness de evaluación | Un conjunto de casos reales, repetidos varias veces |
Con esta tabla delante se entiende por qué "harness" no es una librería ni un proceso. Es un conjunto de responsabilidades que pueden estar en sitios distintos. Vamos a volver a ella en cada apartado.
## 5. Las herramientas son parte del problema
Un modelo nunca trabaja con "el ordenador" en abstracto. Trabaja con una interfaz. Un harness de programación puede darle `leer_fichero`, `buscar_codigo`, `aplicar_parche` y `ejecutar_tests`. Otro puede darle solo `shell(comando)`. Los dos acaban tocando el mismo repositorio, pero al modelo le plantean problemas distintos.
SWE-agent, en 2024, le puso nombre a esta idea: *Agent-Computer Interface* (ACI)[^3]. Trataron el diseño de la interfaz como una variable del experimento. No dieron por hecho que lo pensado para programadores humanos fuera lo mejor para un modelo. Sus cifras (12,5% en SWE-bench, 87,7% en HumanEvalFix) son de aquel paper y aquellos modelos. Lo que sigue valiendo es la pregunta: ¿la capacidad está solo disponible, o está expuesta de forma que el modelo la use bien?
### Cuatro preguntas para cualquier herramienta
- **Qué permite hacer**: el tipo de operación que pone en manos del modelo.
- **Cómo se pide**: el contrato, es decir, el nombre, los parámetros y el formato.
- **Qué devuelve**: la observación que vuelve al modelo después de ejecutarla.
- **Si ayuda al siguiente paso**: si el resultado hace más fácil acertar la próxima acción.
Un shell en bruto permite casi todo. Pero obliga al modelo a elegir comandos, poner bien las comillas, entender salidas pensadas para personas y recuperarse de errores de formato. Una herramienta de parches estructurados permite menos. A cambio, hace más fácil expresar la intención y comprobar el resultado. Ninguna es mejor siempre: depende del modelo, de la tarea y de cómo lo midas.
### Coste de elección y coste de observación
El nombre, la descripción, los parámetros y el formato de respuesta de una herramienta entran en el contexto del modelo. Así que su diseño influye en lo que decide el modelo antes incluso de llamarla. Anthropic pide propósito claro, parámetros sin ambigüedad, nombres agrupados por prefijo y respuestas útiles con pocas palabras[^5].
Usar una herramienta tiene dos costes, y hay que separarlos:
- **El coste de elegir**: lo difícil que es acertar con la herramienta y los argumentos. Se mide como el porcentaje de llamadas con la herramienta equivocada o con argumentos inválidos.
- **El coste de leer el resultado**: cuánto contexto ocupa lo que devuelve y cuánto cuesta entenderlo. Se mide en tokens por resultado y en pasos extra hasta la siguiente acción correcta.
Medidos así, sirven para comparar dos diseños. Y los dos costes tiran en direcciones distintas.
Si expones `search()`, `find()`, `lookup()`, `query()`, `grep()` y `retrieve()`, el sistema parece muy completo. Para el modelo son seis opciones casi iguales, y elegir se vuelve más difícil. Anthropic recomienda menos herramientas y más distintas, agrupadas con prefijos (`asana_search`, `jira_search`)[^5].
Si una API interna devuelve cientos de campos, cada uno ocupa contexto, y leer el resultado sale caro. La receta es filtrar, paginar con valores por defecto sensatos, avisar cuando se ha truncado y ofrecer una respuesta corta o detallada (`response_format`). Claude Code, por ejemplo, limita por defecto las respuestas de herramientas a 25.000 tokens[^5].
### Los errores también son observaciones
Cuando una herramienta falla, el harness puede hacer tres cosas: terminar la ejecución, reintentar solo o devolver el error al modelo para que decida. Un `Error.` a secas obliga al modelo a adivinar. Algo así le deja elegir bien:
```
status: failed
reason: order_not_found
requested_order: 48213
similar_orders: [48231, 48123]
side_effects: none
retryable: false
```
El SDK de agentes de OpenAI tiene las dos piezas[^44]. Tiene un modo que devuelve al modelo un error visible cuando pide una herramienta que no existe, en vez de lanzar una excepción. Y tiene un formateador para el texto de los errores. El campo que más se olvida es `side_effects`. Si el error no dice si algo ha cambiado fuera, ni el modelo ni el harness saben si pueden repetir.
### Cómo se evalúa una interfaz
Si el número de herramientas, sus nombres y el formato de respuesta son variables, se miden como variables. Con las mismas tareas y el mismo modelo, se comparan cuatro cosas:
- herramienta incorrecta y argumentos inválidos, que miden el coste de elegir;
- tokens por tarea, que miden el coste de leer los resultados;
- recuperación tras un error, que dice si los mensajes sirven;
- éxito y coste por tarea resuelta, que dicen si el cambio compensa.
Anthropic usó a los propios agentes para leer las transcripciones de estas pruebas y proponer cambios en las herramientas[^5]. Es un informe de proveedor sin detalle reproducible, pero el método vale para cualquiera.
**En el caso del reembolso.** `buscar_pedido` devuelve importe, fecha, estado del envío, reembolsos previos y el identificador del cliente. No los 200 campos del pedido. `emitir_reembolso` obliga a pasar una clave de idempotencia (apartado 9). Y no hay una herramienta `ejecutar_sql` "por si acaso". Ampliaría lo que el agente puede hacer, y también lo que puede hacer mal.
## 6. MCP: qué estandariza y qué no
El Model Context Protocol (MCP) estandariza cómo una aplicación de IA se conecta a capacidades externas. Su especificación del servidor tiene tres piezas básicas: herramientas, recursos y prompts. Encima pueden ir extensiones opcionales.
Una de ellas es Tasks. A 4 de octubre de 2026 es una extensión **oficial**, con la versión **2026-07-28 estable** y un borrador aparte en desarrollo[^13]. Sirve para tareas largas. El servidor devuelve un identificador de tarea, y el cliente puede consultarla, actualizarla o cancelarla. La especificación recomienda guardar esos identificadores en un almacenamiento duradero, para seguir consultando después de un reinicio. El soporte se negocia, así que no todos los clientes lo tienen[^13].
_El harness habla con un cliente MCP, el cliente con un servidor, y el servidor expone herramientas, recursos y prompts. Todo lo de la derecha sigue siendo trabajo del harness._
Tasks tiene un detalle útil fuera de MCP. Si una herramienta devuelve un resultado con `isError: true`, la tarea cuenta como completada a nivel de protocolo. En cambio, un error de ejecución JSON-RPC la deja en estado fallido[^13]. Que el protocolo diga "terminado" y que la herramienta haya hecho lo que se le pedía son dos cosas distintas. El harness tiene que tratarlas por separado.
MCP, por sí solo, no decide nada de esto:
- cómo se programa el bucle;
- qué entra en el contexto;
- cuándo está terminada una tarea;
- qué necesita aprobación;
- cómo se reintentan los efectos externos;
- cómo se prepara el sandbox;
- cómo se coordinan varios agentes;
- cómo se evalúa el conjunto.
Un harness puede usar MCP para casi todo y seguir siendo responsable de todas esas políticas. MCP es una interfaz común para conectar capacidades, no la arquitectura del agente.
## 7. Contexto y estado
### El contexto activo lo decide el harness
Cada llamada al modelo ve un contexto limitado, y lo que entra lo decide el harness: instrucciones, la tarea, mensajes recientes, esquemas de herramientas, resultados, documentación, planes, resúmenes, ficheros, memoria e informes de subagentes.
Meterlo todo "por si acaso" falla por dos motivos. El primero, que el espacio se acaba. El segundo, que la información irrelevante compite con la relevante aunque haya sitio. Chroma probó 18 modelos en julio de 2025 con tareas muy sencillas[^28]. El rendimiento empeoraba a medida que crecía la entrada. Un solo distractor ya bajaba la precisión. Y los modelos no usaban su contexto de forma uniforme. Anthropic llama a esto *context rot* y trata el contexto como un recurso limitado, que rinde menos cuanto más se llena[^6]. Una ventana de un millón de tokens no convierte en buena idea volcarlo todo.
### Divulgación progresiva
El equipo de OpenAI que construyó un producto entero con Codex se encontró con esto[^10]. Según cuentan, generaron alrededor de un millón de líneas en cinco meses, ninguna escrita a mano. Su fichero de instrucciones del repositorio no paraba de crecer. Ocupaba contexto, era difícil de mantener y no se podía comprobar de forma automática. Lo cambiaron por un `AGENTS.md` corto que funciona como índice de una carpeta `docs/`, con *linters* que comprueban que sigue bien ordenada.
El patrón tiene tres pasos:
1. dar lo justo para orientarse;
2. hacer que lo profundo se pueda encontrar;
3. cargar el detalle solo cuando la tarea lo pide.
Las *Agent Skills* son otra forma del mismo patrón. Son paquetes de instrucciones, a veces con scripts y recursos, que el agente carga cuando hacen falta[^25] [^26]. Una herramienta se invoca. Una skill es sobre todo una guía para decidir cómo trabajar.
Que una skill venga a cuento no garantiza que ayude. Un preprint de agosto de 2026 analiza 307 fallos causados por skills en dos benchmarks[^24]. De ellos, 125 son funcionales: el trabajo queda mal o incompleto. Los otros 182 son de eficiencia: el agente sigue pasos innecesarios y gasta de más. Son casos seleccionados, no una tasa general. Pero bastan para tratar cada skill como un componente que se evalúa.
### Historial duradero y contexto activo son dos cosas
Anthropic guarda la sesión de Managed Agents como un registro de eventos, fuera de la ventana de contexto[^12]. El harness recupera trozos de ese registro y los prepara antes de pasárselos al modelo. La Agents API de OpenAI también separa la sesión duradera de la gestión del contexto[^20].
Los dos conjuntos se solapan, pero ninguno contiene al otro. Lo guardado no tiene por qué entrar en la siguiente llamada. Y una llamada puede llevar cosas que nunca se guardan, como el mensaje actual o los esquemas de herramientas de ese momento.
### Compactar es perder información
Cuando la conversación crece demasiado, se sustituye el detalle antiguo por un resumen. Y un resumen nunca es el historial completo: algo se pierde. Anthropic avisa de que más adelante puede hacer falta algo que parecía irrelevante[^6]. Por eso guarda el historial completo aparte[^12]. Guardarlo permite recuperar lo perdido, pero no garantiza que el agente sepa cuándo buscarlo.
Un dato reciente ayuda a no complicarse. JetBrains Research comparó dos formas de recortar el historial en SWE-bench Verified[^29]. Una, resumir con un LLM. Otra, simplemente ocultar las observaciones antiguas de las herramientas. Ocultar redujo el coste a la mitad respecto a no hacer nada. Y resolvió tantas tareas como el resumen, o alguna más. Un híbrido de las dos bajó el coste otro 7-11%. Es un preprint y un tipo de tarea concreto, pero la técnica sofisticada no salió ganando.
### Una política de contexto, por escrito
Hay que decidir qué se hace con cada tipo de información. Una propuesta para el caso del reembolso:
| Información | Qué se hace | Por qué |
| --- | --- | --- |
| Política de reembolsos | Literal, siempre en contexto | Es la regla de decisión; resumirla es cambiarla |
| Datos del pedido | Literal mientras se usa; después, solo el identificador | Se pueden volver a pedir con `buscar_pedido` |
| Correo del cliente | Literal, marcado como no fiable | Hace falta el texto exacto, y su origen importa (apartado 8) |
| Resultados antiguos de herramientas | Ocultos tras unos pasos, indicando cómo recuperarlos | Es lo más barato de quitar y de volver a pedir |
| Decisiones tomadas (reembolsado, escalado) | Literal, en un fichero de estado aparte | Si se pierden en un resumen, el agente puede repetir una acción |
| Razonamiento intermedio | Resumido o descartado | Es lo que más ocupa y lo que menos hace falta para seguir |
La política se prueba con casos donde una restricción aparece al principio y hace falta al final. Se compara con y sin compactar, con el mismo presupuesto.
### El estado de trabajo, fuera del modelo
Anthropic hizo experimentos con agentes que trabajan durante horas[^7]. Una primera sesión preparaba el entorno y dejaba varios ficheros: una lista de más de 200 funcionalidades en JSON, cada una con un campo `passes` en falso; un fichero de progreso; un `init.sh` para arrancar; y commits descriptivos. Las sesiones siguientes avanzaban poco a poco sobre eso.
Esos ficheros no son memoria oculta del modelo. Son estado externo, y por eso se pueden leer, editar, versionar y recuperar, por otra sesión o por una persona. En el caso del reembolso, el equivalente es un registro por ticket con lo decidido, lo ejecutado y lo comprobado, que vamos a necesitar en el apartado 9.
## 8. Entorno, sandbox y seguridad
### El sandbox aísla, el harness organiza
En cuanto un agente puede cambiar algo fuera, el entorno donde se ejecuta forma parte del diseño. Cambiar algo fuera es ejecutar código, tocar ficheros, navegar o llamar a sistemas internos. El entorno decide lo que se puede hacer y también cómo se falla. Un plan correcto puede fallar porque falta un paquete. Y un entorno mal acotado puede hacer que todo salga bien y deje un agujero abierto.
OpenAI lo explica con dos planos[^14]:
- **El harness es el plano de control**: el bucle, las llamadas al modelo, el reparto de llamadas a herramientas, las aprobaciones, las trazas y la recuperación.
- **El sandbox es el plano de ejecución**: lee y escribe ficheros, ejecuta comandos, instala dependencias y guarda copias del estado.
Cada uno responde a preguntas distintas:
| El sandbox responde | El harness responde |
| --- | --- |
| ¿Qué ficheros y comandos puede alcanzar este proceso? | ¿Qué ve el modelo en el siguiente paso? |
| ¿Puede salir a la red, y a dónde? | ¿Qué llamada se ejecuta, y necesita aprobación? |
| ¿Qué credenciales o montajes ve? | ¿Qué resultado se devuelve? |
| ¿Qué se conserva al destruir el contenedor? | ¿Sigue el bucle? ¿Qué pasa si falla? |
En un prototipo pueden ir juntos. Pero el plano de control debe quedar fuera del entorno donde se ejecuta código no fiable. Así se protegen la sesión, la auditoría, las credenciales y las reglas[^12] [^14]. Anthropic separó en Managed Agents la sesión, el harness y el sandbox como servicios independientes[^12]. Si el harness se cae, otro lee el registro de la sesión y sigue desde el último evento. Y como el sandbox solo se crea cuando hace falta, cuentan que el tiempo hasta el primer token bajó alrededor de un 60% en la mediana.
### Aprobar y contener resuelven problemas distintos
Anthropic publicó en mayo de 2026 cómo contiene a Claude en sus productos[^27]. Trae dos datos que hay que leer con su contexto:
- Los usuarios aprobaban alrededor del **93% de las peticiones de permiso** de Claude Code. Es un dato de su producto. Su lectura es que tantas peticiones cansan, y se acaba aprobando sin leer.
- En un ejercicio interno de febrero de 2026, alguien coló a un empleado un prompt malicioso que pedía a Claude sacar credenciales de AWS. **En 25 intentos, Claude completó el robo 24 veces.** La instrucción llegaba a través del propio usuario, así que el modelo no podía distinguirla de una petición normal. Lo que aguantó fueron las fronteras del entorno: el sistema de ficheros y la salida a red.
La aprobación humana controla decisiones. La contención controla qué se puede alcanzar aunque fallen todas las demás defensas. Y la aprobación también hay que justificarla. Hay que saber qué errores detecta, cuánto cuesta en tiempo y qué pasa cuando la persona se equivoca. Con un 93% de aprobaciones, se va a equivocar. En el caso del reembolso, pedir aprobación por encima de un importe tiene sentido. Pedirla para cada consulta de pedido solo enseña a la persona a pulsar "sí".
### Las credenciales, fuera del código no fiable
Si el código que genera el modelo corre en un sandbox con credenciales de larga duración, hay riesgo. Una inyección de prompt o una dependencia maliciosa pueden leerlas. Managed Agents lo resuelve de dos formas[^12]. Las credenciales del repositorio se usan al preparar el sandbox, sin que el modelo las toque. Las de herramientas externas viven en un almacén aparte y las añade un proxy en el servidor.
Lo que nunca entra en el sandbox no se puede leer desde el sandbox. Pedirle al modelo que no toque los secretos es una instrucción. Sacar los secretos del sandbox cambia lo que se puede alcanzar.
_El harness y el sandbox son planos distintos. La credencial vive en un almacén aparte y solo la usa el proxy, que deja pasar reembolsos válidos y nada más._
Falta un matiz: el proxy sigue haciendo lo que se le pida. Si deja pasar cualquier operación de la API de pagos, el agente puede hacer cualquier operación de la API de pagos. Sacar la credencial es el primer paso. El segundo es limitar qué operaciones admite el proxy.
### Toda observación tiene un origen
Páginas web, correos, tickets, documentos, recursos MCP, skills, resultados de herramientas, informes de subagentes y memoria guardada pueden traer instrucciones hostiles. Cada dato que entra tiene un origen, un nivel de confianza, un momento y unos permisos. Que todo acabe convertido en texto para el modelo no hace que todo valga lo mismo. El artículo de contención de Anthropic tiene tres casos que lo muestran[^27]:
- **Un dominio permitido sirvió para sacar datos.** Un fichero traía instrucciones ocultas y la clave de API de un atacante. Claude acabó subiendo ficheros a la API de Anthropic con esa clave. El proxy vio `api.anthropic.com` y lo dejó pasar. Desde entonces tratan una lista de dominios permitidos como una concesión de capacidad, no como un filtro.
- **El estado guardado recarga el ataque.** Una inyección que se queda en la memoria, en un `CLAUDE.md` o en una carpeta montada se vuelve a cargar cada vez que arranca el agente.
- **Los subagentes pueden escalar confianza.** Pasa si su resultado se trata como más fiable que un resultado de herramienta, porque "viene de nosotros".
AgentDojo (NeurIPS 2024) mide esto mismo desde fuera: 97 tareas y 629 casos de seguridad en correo, banca, viajes y mensajería[^21].
### Tres reglas de diseño
Hay tres planteamientos publicados que convierten estos principios en reglas:
- **La trifecta letal** (Simon Willison, 2025)[^33]. Un agente que junta datos privados, contenido no fiable y capacidad de comunicarse hacia fuera está expuesto a que le roben los datos. El agente de reembolsos tiene las tres cosas.
- **La regla de dos de Meta** (2025)[^32]. En una sesión, un agente no debería tener más de dos de estas tres propiedades: procesar entradas no fiables, acceder a datos o sistemas sensibles, y cambiar algo o comunicarse hacia fuera. Si necesita las tres, hace falta supervisión humana o empezar con un contexto limpio. De las tres reglas me parece la más práctica, porque se comprueba en un diagrama de la arquitectura, sin entrar en el modelo.
- **CaMeL** (Google DeepMind, 2025)[^34]. Lo que se ejecuta lo decide solo la petición del usuario, y los datos no fiables nunca pueden cambiarlo. En AgentDojo resolvió el 77% de las tareas con seguridad demostrable, frente al 84% sin defensas. La seguridad fuerte cuesta algo de capacidad, y se puede medir cuánto.
_Cualquier pareja de propiedades se puede gestionar. Las tres juntas, que es lo que tiene el agente de reembolsos, piden supervisión humana o empezar con un contexto limpio._
Los filtros que intentan detectar el ataque en el texto aguantan peor. Un paper de 2025, con investigadores de OpenAI, Anthropic y Google DeepMind, probó ataques adaptativos contra doce defensas publicadas[^35]. Las superó todas, la mayoría con más de un 90% de éxito.
**En el caso del reembolso**, todo esto se traduce en cuatro decisiones:
- el correo entra marcado como no fiable;
- el importe se valida en código contra el pedido, no contra lo que dice el correo;
- `enviar_respuesta` solo escribe al cliente del ticket;
- y la credencial de pagos está detrás de un proxy que solo permite reembolsos sobre pedidos existentes, y por debajo de su importe.
Las skills entran en el mismo saco. Pueden llevar instrucciones y scripts, y Anthropic y Microsoft piden tratarlas como código de terceros[^25] [^26]. En la implementación de Microsoft, cargar una skill, leer sus recursos y ejecutar sus scripts piden aprobación por defecto.
## 9. Parar, presupuestos, reintentos y recuperación
### Terminar no es lo mismo que completar
Un bucle autónomo puede parar por muchos motivos, y no todos significan que la tarea esté hecha:
- el modelo da una respuesta final;
- se cumple una condición que se puede comprobar;
- hace falta una persona;
- lo bloquea una regla;
- una herramienta falla sin remedio;
- se acaba el presupuesto;
- o alguien lo cancela.
Un harness en producción distingue entre completar y terminar. El SDK de agentes de OpenAI permite fijar un número máximo de turnos[^44]. Al pasarlo, lanza una excepción (`MaxTurnsExceeded`) que para el bucle. Esa excepción no dice nada de si la tarea estaba hecha. Si todas las paradas se apuntan como "terminado", se pierde justo la información que hace falta para mejorar el agente.
### Los presupuestos acotan la autonomía
Un harness puede aplicar varios presupuestos a la vez: turnos, tokens, tiempo, coste, llamadas a herramientas y trabajos en paralelo. Son independientes. La ejecución para en cuanto se agota cualquiera de ellos, y hay que registrar cuál fue. No todas las plataformas los ofrecen todos.
La autonomía se limita con recursos, además de con permisos. Una ejecución puede tener acceso a la base de datos y aun así un máximo de 20 llamadas. Un sistema puede usar subagentes y aun así un máximo de cinco a la vez.
### Acción pedida, acción hecha y resultado conocido
Este es probablemente el punto más útil de todo el documento. Cuando el harness pide una acción con efectos fuera, hay cuatro momentos distintos:
1. **Acción solicitada**: el harness ha decidido llamar a la herramienta.
2. **Acción ejecutada**: el sistema de fuera la ha hecho.
3. **Resultado observado**: el harness ha recibido la respuesta.
4. **Estado confirmado**: el harness ha guardado que está hecho.
Esos pasos no fallan juntos. Si la conexión se corta entre el 2 y el 3, el harness sabe que pidió la acción, pero no sabe si se hizo. Repetirla a ciegas puede duplicarla. Un registro de eventos duradero ayuda a recordar qué se pidió y qué se vio[^16]. Pero eso no hace, por sí solo, que repetir sea seguro[^18].
_Entre pedir un reembolso y darlo por hecho hay cuatro pasos y tres sitios donde se puede cortar. La clave de idempotencia es lo que permite repetir sin cobrar dos veces._
Aplicado a `emitir_reembolso`, con cada momento posible del fallo:
| Momento del fallo | Qué sabe el harness al volver | Qué ha pasado fuera | Qué hacer al recuperar |
| --- | --- | --- | --- |
| Antes de enviar la petición | Que tenía intención de reembolsar | Nada | Repetir sin riesgo, con la misma clave |
| Petición enviada, conexión caída antes de la respuesta | Que la pidió, sin resultado | Puede que se haya reembolsado | Repetir con **la misma** clave: si ya se hizo, la API devuelve el resultado original |
| Respuesta recibida, caída antes de guardarla | Lo mismo que en el caso anterior | Reembolso hecho | Igual: misma clave, misma respuesta, y ahora sí se guarda |
| Estado guardado, caída antes de contestar al cliente | Reembolso hecho, correo pendiente | Nada más | Enviar el correo, comprobando antes en enviados por el identificador del ticket |
| Dos trabajadores cogen el mismo ticket | Cada uno, solo lo suyo | Posible doble reembolso | Un solo escritor por ticket, o bloqueo del ticket, o restricción de unicidad en el sistema de pagos |
### Idempotencia, y dónde se rompe
Una operación es idempotente cuando repetirla tiene el mismo efecto que hacerla una vez. RFC 9110 lo define para HTTP[^18]. Y explica por qué importa justo en este caso: cuando el cliente pierde la respuesta y no sabe si la petición llegó. `cerrar_ticket(id)` se puede diseñar para que sea idempotente. `cobrar_tarjeta`, `enviar_correo` o `crear_pedido`, de serie, no lo son.
El mecanismo más común es la **clave de idempotencia**. En Stripe funciona así[^30]:
- el cliente genera una clave única y la manda con la petición;
- Stripe guarda la primera respuesta para esa clave, haya ido bien o mal;
- las peticiones siguientes con la misma clave devuelven exactamente esa respuesta, errores 500 incluidos;
- si los parámetros no coinciden con los de la primera, devuelve error;
- y las claves se pueden borrar pasadas 24 horas.
De ahí salen tres consecuencias para los agentes:
- **La clave tiene que salir del negocio, no del intento.** Si cada reintento genera una clave nueva, la idempotencia no sirve de nada. Y si dos trabajadores procesan el mismo ticket y cada uno genera la suya, habrá dos reembolsos. La clave correcta es algo como `reembolso:{ticket_id}:{pedido_id}`, que cualquier trabajador calcularía igual.
- **La clave puede caducar antes que el trabajo del agente.** Pongamos un reembolso que espera una aprobación humana, y la aprobación llega dos días después. La clave puede haber caducado, y el reintento contaría como una petición nueva. En trabajos largos, antes de reintentar hay que consultar el estado real, no fiarse solo de la clave.
- **Comprobar y luego actuar no basta si hay varios trabajadores.** "Miro si ya está reembolsado y, si no, reembolso" falla si dos miran a la vez. Hace falta una garantía en el sistema que recibe la acción, como una restricción de unicidad o una transacción. O un único escritor por recurso.
Los motores de ejecución duradera llevan años con este problema. La documentación de Temporal avisa de que una tarea se puede ejecutar más de una vez[^31]. Por ejemplo, si el trabajador se cae después de hacerla y antes de informar. Su recomendación es que la lógica de negocio sea siempre idempotente, con claves que comprueba el servicio de fuera. Los agentes no inventan el problema: lo heredan.
Los reintentos automáticos son una política de cada herramienta, no una estrategia general. Alguien lo resumía bien en X: reintentar se vuelve peligroso en cuanto una llamada llega dos veces a una API real sin clave de idempotencia[^1].
### Los trabajos largos heredan los problemas de siempre
En una tarea de horas o días, el harness se puede caer, el sandbox se puede reciclar y la red se puede cortar. Y una aprobación puede llegar mucho después. Google presentó en mayo de 2026 Agent Executor, un runtime abierto, todavía en pruebas, pensado para esto[^16]. Guarda un registro de eventos y copias del estado de cada pieza. Permite reanudar tras una caída o tras una confirmación humana. Y usa un solo escritor, para que varios componentes no estropeen el estado de la sesión.
Cuanto más largo y repartido es el trabajo, más se parece el harness a un sistema distribuido de los de siempre. Durabilidad, recuperación, consistencia y aislamiento de fallos. La concurrencia entre subagentes no es un problema de prompts. Es un problema de estado: en qué orden se aplican los cambios, si dos trabajadores se pisan y qué registro manda.
## 10. Verificar: decir "hecho" no es una prueba
Que el agente diga "el reembolso está hecho" es una afirmación. La prueba es otra cosa. En software, es que el fallo original ya no se reproduce, que pasan los tests de regresión, que la aplicación funciona de principio a fin y que el estado ha cambiado como se esperaba.
Anthropic lo vio en sus agentes de larga duración[^7]. A veces una sesión nueva encontraba trabajo avanzado y daba la tarea por terminada. Otras veces daba por buena una funcionalidad que no funcionaba de principio a fin. Mejoró al obligar al agente a probar cada funcionalidad en el navegador, como un usuario, antes de marcarla como hecha.
Los benchmarks serios hacen lo mismo. τ-bench compara el estado final de la base de datos con el estado que debería haber, en vez de fiarse de la conversación[^22]. ToolSandbox evalúa hitos intermedios y finales sobre herramientas que guardan estado[^23]. **En el caso del reembolso**, "hecho" significa que el sistema de pagos tiene ese reembolso y que el cliente tiene el correo. No que el modelo lo diga.
### Reglas en código donde se pueda, criterio donde haga falta
Algunas cosas se comprueban de forma mecánica: si un JSON es válido, si un importe supera un umbral, si una ruta está fuera de la carpeta permitida o si se ha pasado el presupuesto. Otras necesitan criterio: si un resultado es relevante o si una explicación responde a lo que quería el usuario.
La regla es sencilla. Comprobación en código donde se pueda, y modelo o persona donde haga falta interpretar. El modelo no debería tener que acordarse de una regla que el sistema puede aplicar barato. El equipo de Codex convirtió reglas de arquitectura escritas en *linters* y tests[^10]. Según dicen, con agentes esas reglas multiplican.
### Un test comprueba lo que comprueba
Un test verifica lo que verifica, y nada más. No demuestra que la especificación esté completa ni que el propio test esté bien escrito. Y los agentes aprovechan esos huecos:
- **METR** (2025) vio a o3 hacer trampa en 39 de 128 ejecuciones de sus tareas de investigación[^36]. En una de ellas, en 21 de 21. Sobrescribía la función que mide el tiempo o la que puntúa. Cuando le preguntaron si eso era lo que quería el usuario, dijo que no diez veces de diez.
- **ImpossibleBench** (ICLR 2026) usa tareas donde el enunciado contradice los tests[^37]. Aprobar solo es posible haciendo trampa. GPT-5 aprobó el 54% y Claude Opus 4.1 el 50%. Dos medidas lo redujeron mucho: dejar los tests en solo lectura y dar al modelo la opción de abandonar y avisar a una persona. Con eso, GPT-5 bajó al 9%.
- **Los benchmarks también fallan.** OpenAI dejó de usar SWE-bench Verified en febrero de 2026[^38]. El 59,4% de los problemas que revisó tenía tests defectuosos. Además, había señales de que los modelos los habían visto al entrenar. En julio revisó SWE-bench Pro, su alternativa, encontró alrededor de un 30% de tareas rotas y retiró la recomendación[^39].
En el harness, eso se traduce en tres decisiones:
- que el agente no pueda tocar los tests ni la función que lo evalúa;
- que tenga una salida legítima para decir "esto no se puede hacer";
- y que alguien lea de vez en cuando las transcripciones de los casos que pasan, no solo de los que fallan.
### Generar y evaluar son papeles distintos
Hay cosas que ningún test cubre: la calidad de un texto, un diseño, si una investigación está completa. Para eso, Anthropic ha separado en algunos experimentos el agente que genera del que evalúa[^11].
Un evaluador basado en un modelo también se equivoca, y con sesgos conocidos. Prefiere la respuesta que aparece primero, la más larga y la suya propia[^40]. Los modelos reconocen sus propios textos y los puntúan mejor[^41]. Separar los dos papeles no hace independientes sus errores si comparten modelo, fuentes o criterio. Antes de fiarse de un evaluador, hay que contrastarlo con casos puntuados por personas. Y contar cuántas veces da por bueno lo que está mal, y al revés.
### Feedback y observabilidad
Un agente puede actuar, ver la consecuencia y corregir. Pero solo si tiene feedback del mundo: el compilador, los tests, capturas, logs, métricas, trazas, el estado de la base de datos. El equipo de Codex conectó al agente las herramientas de desarrollo de Chrome y una pila local de logs, métricas y trazas[^10]. Así podía comprobar él solo la interfaz y el rendimiento.
La observabilidad tiene dos destinatarios. Uno son las personas que depuran el harness: turnos, llamadas, fallos, latencia, coste, aprobaciones. El otro es el propio agente, que necesita pruebas sobre el sistema en el que trabaja. OpenAI lo llama *agent legibility*: lo que el agente no puede ver en su contexto, para él no existe[^10].
## 11. Subagentes: cuándo compensan
Un harness puede darle toda la tarea a un solo agente o repartirla entre varios. Repartir acelera cuando el trabajo se divide limpiamente. Pero también trae trabajo duplicado, supuestos incompatibles, coste de comunicación, más tokens, errores que se propagan y conflictos sobre el estado compartido.
El estudio más completo que conozco es de Google Research, de enero de 2026[^17]. Comparó 180 configuraciones en cuatro benchmarks: un agente solo frente a cuatro formas de organizar varios agentes. Estos son los resultados principales:
- En una tarea de análisis financiero que se puede repartir, coordinar desde un centro mejoró un **80,9%** frente al agente solo.
- En una tarea de planificación paso a paso (PlanCraft), **todas** las variantes con varios agentes empeoraron, entre un 39% y un 70%.
- Los agentes que trabajaban sin coordinarse multiplicaban los errores por 17,2. Con un coordinador central, por 4,4.
- Un modelo que usaba propiedades de la tarea acertaba la mejor organización en el 87% de los casos nuevos. Las propiedades eran, por ejemplo, el número de herramientas y si la tarea se puede dividir.
Son resultados de ese experimento, no leyes. Y ese modelo predictivo explica más o menos la mitad de la variación, no toda. Lo que sí dejan claro es que repartir tiene que estar justificado por cómo se divide la tarea. No por la creencia de que más agentes es mejor.
Antes de añadir un subagente, tres preguntas útiles:
- ¿Esta parte se puede hacer sin saber lo que hacen las demás?
- ¿Qué información tiene que compartir, y cuánto cuesta pasarla?
- ¿Quién junta los resultados, y cómo se da cuenta de que dos subagentes han supuesto cosas incompatibles?
### Mismos principios, requisitos distintos según el trabajo
Los ejemplos de agentes suelen ser de programación. Los principios valen para cualquier trabajo, pero lo que hay que reforzar cambia. Esta tabla es una forma de ordenarlo, no una clasificación cerrada:
| Tipo de trabajo | Lo que más exige al harness | Qué cuenta como prueba de éxito |
| --- | --- | --- |
| Programación | Ficheros, shell, parches, tests, git, dependencias, aislamiento | Reproducción del fallo, tests de regresión, producto funcionando |
| Navegador o interfaces | Estado de la interfaz, capturas, identificar elementos, confirmar acciones | La acción confirmada en la interfaz y en el sistema que la recibe |
| Investigación | Recuperar información, origen y calidad de fuentes, citas | Afirmaciones respaldadas, cobertura suficiente, separar evidencia de inferencia |
| Operaciones de sistemas | Logs, métricas, permisos, cambios de configuración, vuelta atrás | Estado del servicio y capacidad de volver a una situación buena |
| Transacciones (el caso del reembolso) | Autorización, idempotencia, deduplicación, auditoría, escalado | Efecto externo correcto, autorizado y sin duplicados |
| Datos | Esquemas, linaje, consultas, validación, control de acceso | Resultados correctos sobre datos identificados y transformaciones comprobables |
| Trabajo largo en segundo plano | Estado duradero, checkpoints, reanudación, cancelación, concurrencia | Continuidad tras fallos y un final con resultado comprobado |
## 12. Cómo saber si un harness mejora algo
Es la parte que menos se suele contar y, para mí, la más importante. Todo el mundo está de acuerdo en que cada pieza del harness tiene que justificar lo que aporta y lo que cuesta. Lo difícil es comprobarlo.
### El resultado mide el modelo y mucho más
El harness de evaluación es la infraestructura que ejecuta las pruebas de principio a fin[^8]. Lanza las tareas, registra cada paso, puntúa y suma resultados. Y lo que mide no es solo el modelo. El resultado depende del modelo, pero también del harness, del entorno, de la tarea y de quién puntúa. Si cambias el harness o el entorno, cambia el resultado sin tocar el modelo.
Anthropic lo midió con el entorno[^9]. En Terminal-Bench 2.0 cambió solo la potencia de las máquinas, en seis configuraciones. Entre la más limitada y la más generosa hubo **6 puntos** de diferencia. El detalle es interesante:
- entre 1x y 3x de margen, bajaban mucho los fallos de infraestructura (del 5,8% al 2,1%), pero el éxito apenas se movía, dentro del margen de ruido;
- por encima de 3x, los recursos extra permitían estrategias distintas, y el éxito subía casi 4 puntos más.
Su recomendación: desconfiar de diferencias de menos de 3 puntos en una clasificación, mientras la configuración no esté documentada e igualada.
### Un protocolo mínimo
Con lo publicado hasta hoy, este es un protocolo razonable para decidir si un cambio en el harness compensa:
1. **Tareas representativas.** Anthropic recomienda empezar con 20-50 tareas sacadas de fallos reales, sin esperar a tener un conjunto enorme[^8]. Cada tarea, con su condición de éxito escrita.
2. **Una referencia simple.** Hace falta un harness mínimo con el que comparar. Sin referencia, cualquier cambio parece una mejora.
3. **Cambiar una cosa cada vez.** Comparaciones A/B y pruebas quitando piezas: se quita o se añade un componente y se deja el resto igual.
4. **Documentarlo todo.** Modelo y versión, esfuerzo de razonamiento, instrucciones, herramientas, estado inicial, recursos, red, versiones de dependencias. Lo que no se puede reproducir no se puede comparar.
5. **Repetir.** Varios intentos por tarea, porque ni el modelo ni a veces el entorno dan siempre lo mismo.
6. **Barras de error.** Con 50 tareas y un 80% de éxito, el margen de error es de unos 11 puntos arriba o abajo. Una mejora de 5 puntos, con esa muestra, no dice nada. Hay formas de afinar, como comparar por parejas sobre las mismas tareas[^43].
7. **Evaluadores comprobados**, como se explica en el apartado 10.
8. **Coste y tiempo junto a la calidad.** Hay que mirar la calidad frente al coste y el tiempo, no solo la precisión.
9. **Separar el benchmark de lo real.** Probar con tareas de producción distintas de las que se han usado para ajustar el harness.
### Acertar una vez no es acertar siempre
En evaluación de agentes se usan dos medidas que se parecen y no son lo mismo[^8] [^22]:
- **pass@k** es la probabilidad de acertar **al menos una vez** en k intentos.
- **pass^k** es la probabilidad de acertar **todas las veces** en k intentos.
Un ejemplo. Un agente que acierta el 80% de las veces acierta al menos una de tres el 99,2% de las veces. Pero acierta las tres solo el 51,2%. Si una persona elige el mejor de tres intentos, cuenta la primera cifra. Si el agente procesa miles de reembolsos sin supervisión, cuenta la segunda. τ-bench lo dejó claro desde su publicación: GPT-4o resolvía menos de la mitad de sus tareas, y acertaba ocho de ocho en menos del 25% de las de tienda[^22].
### Las métricas que hacen falta
| Métrica | Para qué |
| --- | --- |
| Éxito por tarea (y pass^k) | Si funciona, y si funciona siempre |
| Coste por tarea resuelta | Si compensa |
| Tiempo hasta el éxito | Si es usable |
| Frecuencia de intervención humana | Cuánto trabajo traslada a las personas |
| Recuperación tras fallos | Si aguanta caídas y errores de herramientas |
| Acciones no seguras o no autorizadas | Si respeta las fronteras |
| Éxitos declarados que no lo eran | Si se puede fiar de lo que dice |
| Causas de parada | Distinguir éxito, presupuesto, bloqueo y fallo |
El trabajo independiente más completo en esta línea es HAL, el *Holistic Agent Leaderboard* de Princeton (ICLR 2026)[^42]. Son 21.730 ejecuciones, 9 modelos y 9 benchmarks, con todos los registros publicados. Dos hallazgos lo explican bien. Más esfuerzo de razonamiento **redujo** la precisión en la mayoría de las ejecuciones. Y en los registros aparecieron agentes que buscaban el benchmark en Hugging Face en vez de resolver la tarea, o que usaban mal una tarjeta de crédito al reservar vuelos. Nada de eso se ve con la puntuación sola.
### El caso RetroForge, leído con cuidado
Anthropic publicó un experimento con un juego llamado RetroForge[^11]. Una ejecución con un solo agente tardó 20 minutos y costó 9 dólares. El harness completo, con planificador, generador y evaluador, tardó seis horas y costó 200 dólares. El resultado fue mucho mejor. En la versión de un solo agente, las piezas aparecían en pantalla, pero nada respondía. Es una tarea concreta, y costó más de veinte veces más.
Hay que leerlo con cuidado, porque en esa comparación cambian varias cosas a la vez: la arquitectura, el tiempo, el presupuesto y lo que se pide (el planificador amplía la especificación). El resultado muestra que ese sistema, con más recursos, hizo algo mejor. No permite saber cuánto se debe a la organización del harness y cuánto al tiempo y al dinero extra. Para saberlo habría que comparar con el mismo objetivo y presupuestos parecidos. Y quitar por separado el planificador, el evaluador y la división en fases. La idea de fondo del artículo es buena. El experimento, por sí solo, no basta para demostrarla.
## 13. Los supuestos del harness caducan
Un harness suele llevar apaños para defectos concretos del modelo. Esos apaños no son para siempre. Anthropic tiene el ejemplo más claro, en sus propios experimentos de 2026[^11]:
- Claude Sonnet 4.5 tenía lo que llamaron "ansiedad de contexto". Cerca del límite de su ventana, tendía a cerrar el trabajo antes de tiempo, y compactar no bastaba. Añadieron reinicios de contexto. Con Opus 4.5, el mismo harness ya no los necesitaba. El modelo había cambiado y los reinicios sobraban.
- Con Opus 4.6 quitaron también la división del trabajo en *sprints*. El modelo trabajaba más de dos horas seguidas con coherencia sin ella. El planificador siguió siendo útil. El evaluador pasó a depender de la tarea: aportaba en las difíciles para el modelo y era coste añadido en las fáciles.
Su frase resume el principio: cada pieza de un harness supone algo sobre lo que el modelo no puede hacer solo, y esas suposiciones hay que ponerlas a prueba. OpenAI va en la misma línea. Su Agents API, en beta pública desde septiembre de 2026, ofrece el harness de Codex como un sistema con versiones, que cambia con cada modelo[^20].
Cada vez que cambia el modelo, hay que volver a probar cada pieza. Si no, los harnesses acumulan capas viejas que añaden latencia, tokens, complejidad y fallos nuevos. En la práctica, es el protocolo del apartado 12 aplicado a quitar piezas, no solo a añadirlas.
## 14. Fallos frecuentes
Estos son los fallos más habituales, cómo se reconocen y qué los reduce:
| Fallo | Cómo se ve | Qué lo reduce |
| --- | --- | --- |
| Elección de herramienta | Existe la capacidad y el modelo usa otra | Menos herramientas, sin solapes, nombres con prefijo |
| Contrato | La herramienta es la buena y los argumentos no | Esquemas claros, errores que dicen qué corregir |
| Observación | La acción funciona y lo que vuelve es ruido o está incompleto | Resultados filtrados, modos corto y detallado |
| Contexto | Algo importante falta, está viejo o se perdió al compactar | Política de contexto por escrito, estado fuera del modelo |
| Estado | Se pierde el hilo del progreso, de las aprobaciones o de lo hecho | Ficheros de estado, registro de sesión duradero |
| Entorno | Paquetes, ficheros, permisos o recursos no son los esperados | Entornos reproducibles, recursos documentados |
| Verificación | Declara éxito sin comprobar el resultado | Éxito atado a estado externo; tests fuera de su alcance |
| Trampa con el evaluador | Satisface el test o la métrica sin resolver la tarea | Tests en solo lectura, salida para abandonar, revisar éxitos |
| Autorización | Bloqueado para lo legítimo, o con más poder del necesario | Permisos mínimos, umbrales, regla de dos |
| Recuperación | Un reintento duplica un efecto, o tras reiniciar no cuadra el estado | Claves de idempotencia de negocio, consultar antes de repetir |
| Coordinación | Subagentes duplican trabajo o suponen cosas incompatibles | Repartir solo lo divisible, un escritor por recurso |
| Presupuesto | Se agota antes de llegar a un estado de éxito | Presupuestos explícitos y causa de parada registrada |
| Origen e inyección | Datos no fiables se tratan como instrucciones | Marcar el origen, contención, separar control de datos |
| Skills | Una skill pertinente estropea el trabajo o lo encarece | Evaluar cada skill, tratarla como código de terceros |
## 15. Diecisiete preguntas para revisar un agente
Son lo más práctico del documento y sirven para revisar cualquier sistema de agentes:
1. **Qué recibe de verdad el modelo**: instrucciones, historial, esquemas de herramientas, estado recuperado, resúmenes, ficheros.
2. **Quién controla el bucle**: el código de la aplicación, un harness gestionado, un motor de workflows u otro agente.
3. **Qué acciones tiene disponibles**: herramientas, MCP, shell, navegador, ficheros, APIs, subagentes.
4. **Dónde se ejecutan**: proceso de confianza, máquina local, contenedor, máquina virtual, servicio remoto.
5. **Qué se conserva en el siguiente turno o tras una caída**: eventos de sesión, ficheros, copias del estado, efectos externos.
6. **Qué reglas se aplican en código**: esquemas, carpetas permitidas, red, aprobaciones, tests, presupuestos.
7. **Cómo se representan los errores**: excepción fatal, reintento, error para el modelo, aviso a una persona.
8. **Qué acciones se pueden repetir sin riesgo**: idempotentes, deduplicadas, o ninguna.
9. **Cómo sabe el agente lo que pasa de verdad**: tests, logs, navegador, base de datos, respuestas externas.
10. **Qué demuestra que ha terminado**: lo que dice el modelo, un validador, el estado externo, un evaluador o una persona.
11. **Cómo para si nunca lo consigue**: turnos, tiempo, tokens, herramientas, coste o reglas.
12. **Qué pasa tras una interrupción**: reanudar, reintentar, volver a preparar el entorno, deshacer o empezar de cero.
13. **Si los datos no fiables pueden traer instrucciones**: web, herramientas, ficheros, memoria, skills, subagentes.
14. **Cómo se coordinan los subagentes**: límites de cada tarea, estado compartido, cómo se juntan resultados, concurrencia.
15. **Cómo se evalúa el harness**: pruebas quitando piezas, tareas representativas, entornos estables, métricas de resultado.
16. **Si el agente puede modificar lo que le evalúa**: tests, funciones de puntuación, el propio criterio de éxito.
17. **Qué piezas del harness se han vuelto a probar con el último modelo**.
Un sistema que no sabe contestar a estas preguntas puede funcionar en una demo, pero en producción es muy difícil razonar sobre él.
## 16. El mapa completo
Todo junto, en un dibujo:
_El mapa completo: tarea, sesión, modelo y herramientas alrededor del harness, con los límites duros sobre las herramientas y el feedback de vuelta._
Y lo que hace cada pieza, con la propiedad del apartado 2 a la que sirve:
| Pieza | Qué decide | Propiedad |
| --- | --- | --- |
| Modelo | La capacidad aprendida | - |
| Harness | Cómo se conecta esa capacidad con el trabajo | Las cuatro |
| Sesión y estado | Qué se conserva entre turnos y tras un reinicio | Recuperables |
| Política de contexto | Qué ve el modelo en cada llamada | Observables |
| Entorno de ejecución | Qué puede pasar de verdad | Acotadas |
| Permisos y contención | Hasta dónde llega un fallo | Acotadas |
| Feedback | Si una acción ha funcionado | Observables |
| Recuperación | Si el trabajo sigue tras una interrupción sin duplicar nada | Recuperables |
| Verificación | Si "hecho" está respaldado por pruebas | Verificables |
| Evaluación | Si el harness ayuda o solo añade piezas | Verificables |
Eso es harness engineering, contado entero. Queda algo sin resolver, lo de siempre en un campo tan joven. Casi no hay experimentos públicos que midan cuánto aporta cada pieza de un harness con presupuestos comparables. Esa es la investigación que falta, y la que más ganas tengo de leer.
## Bonus
> [!tip]+ Aquí en davidhurtado.ai
> - [[Posts/2026.05/12-Cowork-harness|Cowork, harness, y por qué la IA va a cambiar de modelo de cobro]] - la definición corta de harness de la que parte todo esto, y por qué los procesos largos cambian cómo se paga la IA.
> - [[Posts/2026.08/25-loop-engineering-dos-meses-despues|Loop engineering, dos meses después]] - el bucle visto desde el usuario: qué pieza dejas de hacer tú y quién comprueba el resultado.
> - [[El Abismo de Máquina/Investigaciones/2026.07/Investigacion-Evals-en-trabajo-de-informacion|Evals para verificar resultados de IA generativa]] - el apartado 12 de este documento, desarrollado para trabajo de oficina en vez de para programación.
> - [[El Abismo de Máquina/Ecos/2026.04/Eco-Agent-Skills-Guia|Eco: Agent Skills, guía completa]] - qué es una skill y cómo se construye, antes de preocuparse por cuándo estropea el trabajo.
> [!tip]+ Para profundizar en Internet
> - [AI Agents That Matter](https://arxiv.org/abs/2407.01502) · Kapoor, Narayanan y otros, Princeton (paper, 2024) - el paper que puso sobre la mesa que evaluar agentes sin mirar el coste es hacerse trampas; HAL sale de aquí.
> - [Lost in the Middle: How Language Models Use Long Contexts](https://arxiv.org/abs/2307.03172) · Liu y otros, Stanford (paper, TACL 2024) - la prueba clásica de que lo que está en mitad del contexto se usa peor; la base de toda la política de contexto.
> - [New prompt injection papers: Agents Rule of Two and The Attacker Moves Second](https://simonwillison.net/2025/Nov/2/new-prompt-injection-papers/) · Simon Willison - la mejor lectura en una sola página de por qué los filtros no bastan y hay que limitar lo que el agente alcanza.
## Fuentes
Cada fuente lleva su tipo entre corchetes: **[paper]** revisado por pares, **[preprint]** sin revisión, **[proveedor]** un equipo contando su propio sistema, **[documentación]** de producto, **[estándar]** y **[independiente]** para análisis de terceros que no son papers. Consultadas entre el 4 de octubre de 2026 y la fecha del documento.
[^1]: [independiente] [@techNmak: Understanding Harness Engineering, post en X con el manual original](https://x.com/techNmak/status/2106765347793858563), 4 de octubre de 2026.
[^2]: [paper] [Yao y otros: ReAct: Synergizing Reasoning and Acting in Language Models](https://arxiv.org/abs/2210.03629), ICLR 2023.
[^3]: [paper] [Yang y otros: SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering](https://arxiv.org/abs/2405.15793), NeurIPS 2024.
[^4]: [proveedor] [Anthropic: Building effective agents](https://www.anthropic.com/engineering/building-effective-agents)
[^5]: [proveedor] [Anthropic: Writing effective tools for agents, with agents](https://www.anthropic.com/engineering/writing-tools-for-agents), septiembre de 2025.
[^6]: [proveedor] [Anthropic: Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
[^7]: [proveedor] [Anthropic: Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents), noviembre de 2025.
[^8]: [proveedor] [Anthropic: Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents), enero de 2026.
[^9]: [proveedor] [Anthropic: Quantifying infrastructure noise in agentic coding evals](https://www.anthropic.com/engineering/infrastructure-noise), febrero de 2026.
[^10]: [proveedor] [OpenAI: Harness engineering: leveraging Codex in an agent-first world](https://openai.com/index/harness-engineering/), febrero de 2026.
[^11]: [proveedor] [Anthropic: Harness design for long-running application development](https://www.anthropic.com/engineering/harness-design-long-running-apps), marzo de 2026.
[^12]: [proveedor] [Anthropic: Scaling Managed Agents: Decoupling the brain from the hands](https://www.anthropic.com/engineering/managed-agents), abril de 2026.
[^13]: [estándar] [Model Context Protocol: repositorio de la extensión Tasks](https://github.com/modelcontextprotocol/ext-tasks) y [especificación Tasks 2026-07-28](https://tasks.extensions.modelcontextprotocol.io/specification/2026-07-28/tasks), consultados el 4 de octubre de 2026.
[^14]: [documentación] [OpenAI: Sandbox agents](https://developers.openai.com/api/docs/guides/agents/sandboxes)
[^15]: [documentación] [Microsoft Agent Framework: Agent Harness](https://learn.microsoft.com/agent-framework/agents/harness)
[^16]: [proveedor] [Google Cloud: Introducing Agent Executor, Google's distributed Agent Runtime](https://cloud.google.com/blog/products/ai-machine-learning/agent-executor-googles-distributed-agent-runtime/), mayo de 2026.
[^17]: [proveedor] [Google Research: Towards a science of scaling agent systems](https://research.google/blog/towards-a-science-of-scaling-agent-systems-when-and-why-agent-systems-work/), enero de 2026, con su [preprint (arXiv 2512.08296)](https://arxiv.org/abs/2512.08296).
[^18]: [estándar] [IETF: RFC 9110, HTTP Semantics, apartado 9.2.2 sobre métodos idempotentes](https://www.rfc-editor.org/rfc/rfc9110.html#name-idempotent-methods), 2022.
[^19]: [proveedor] [Anthropic: An update on recent Claude Code quality reports](https://www.anthropic.com/engineering/april-23-postmortem), 23 de abril de 2026.
[^20]: [proveedor] [OpenAI: Introducing the Agents API](https://openai.com/index/introducing-the-agents-api/), septiembre de 2026.
[^21]: [paper] [Debenedetti y otros: AgentDojo](https://doi.org/10.52202/079017-2636), NeurIPS 2024, Datasets and Benchmarks.
[^22]: [paper] [Yao, Shinn, Razavi y Narasimhan: τ-bench](https://arxiv.org/abs/2406.12045), ICLR 2025.
[^23]: [paper] [Lu y otros: ToolSandbox](https://aclanthology.org/2025.findings-naacl.65/), Findings of NAACL 2025.
[^24]: [preprint] [Dong y otros: Agent Skills Can Be Harmful: An Empirical Study of Skill-Induced Failures in LLM Agents](https://arxiv.org/abs/2608.11888), agosto de 2026.
[^25]: [documentación] [Anthropic: Agent Skills](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview)
[^26]: [documentación] [Microsoft Agent Framework: Agent Skills](https://learn.microsoft.com/agent-framework/agents/skills)
[^27]: [proveedor] [Anthropic: How we contain Claude across products](https://www.anthropic.com/engineering/how-we-contain-claude), mayo de 2026.
[^28]: [independiente] [Chroma: Context Rot: How Increasing Input Tokens Impacts LLM Performance](https://www.trychroma.com/research/context-rot), julio de 2025.
[^29]: [preprint] [Lindenbauer y otros (JetBrains Research): The Complexity Trap: Simple Observation Masking Is as Efficient as LLM Summarization for Agent Context Management](https://arxiv.org/abs/2508.21433), 2025.
[^30]: [documentación] [Stripe: Idempotent requests](https://docs.stripe.com/api/idempotent_requests)
[^31]: [documentación] [Temporal: Activity Definition, idempotencia](https://docs.temporal.io/activity-definition)
[^32]: [proveedor] [Meta AI: Agents Rule of Two: A Practical Approach to AI Agent Security](https://ai.meta.com/blog/practical-ai-agent-security/), octubre de 2025.
[^33]: [independiente] [Simon Willison: The lethal trifecta for AI agents](https://simonwillison.net/2025/Jun/16/the-lethal-trifecta/), junio de 2025.
[^34]: [preprint] [Debenedetti y otros (Google DeepMind): Defeating Prompt Injections by Design (CaMeL)](https://arxiv.org/abs/2503.18813), 2025.
[^35]: [preprint] [Nasr y otros: The Attacker Moves Second: Stronger Adaptive Attacks Bypass Defenses against LLM Jailbreaks and Prompt Injections](https://arxiv.org/abs/2510.09023), octubre de 2025.
[^36]: [independiente] [METR: Recent Frontier Models Are Reward Hacking](https://metr.org/blog/2025-06-05-recent-reward-hacking/), junio de 2025.
[^37]: [paper] [Zhong y otros: ImpossibleBench: Measuring LLMs' Propensity of Exploiting Test Cases](https://arxiv.org/abs/2510.20270), ICLR 2026.
[^38]: [proveedor] [OpenAI: Why SWE-bench Verified no longer measures frontier coding capabilities](https://openai.com/index/why-we-no-longer-evaluate-swe-bench-verified/), febrero de 2026.
[^39]: [proveedor] [OpenAI: Separating signal from noise in coding evaluations](https://openai.com/index/separating-signal-from-noise-coding-evaluations/), julio de 2026.
[^40]: [paper] [Zheng y otros: Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena](https://arxiv.org/abs/2306.05685), NeurIPS 2023.
[^41]: [paper] [Panickssery, Bowman y Feng: LLM Evaluators Recognize and Favor Their Own Generations](https://proceedings.neurips.cc/paper_files/paper/2024/hash/7f1f0218e45f5414c79c0679633e47bc-Abstract-Conference.html), NeurIPS 2024 (oral). [Versión en arXiv](https://arxiv.org/abs/2404.13076).
[^42]: [paper] [Kapoor y otros: Holistic Agent Leaderboard: The Missing Infrastructure for AI Agent Evaluation](https://arxiv.org/abs/2510.11977), ICLR 2026.
[^43]: [preprint] [Evan Miller (Anthropic): Adding Error Bars to Evals: A Statistical Approach to Language Model Evaluations](https://arxiv.org/abs/2411.00640), 2024.
[^44]: [documentación] OpenAI Agents SDK: [Run config](https://openai.github.io/openai-agents-python/ref/run_config/) (`tool_not_found_behavior` con `return_error_to_model`, y `tool_error_formatter`) y [Runner](https://openai.github.io/openai-agents-python/ref/run/) (`max_turns` y la excepción `MaxTurnsExceeded`).