Harness Engineering: the 9 pieces, built and measured
Llevaba meses intentando explicar por qué dos equipos con el mismo modelo obtienen resultados opuestos. El marco que me faltaba: no compites por el modelo, compites por el harness. No es una idea mía: es la conclusión que se repite en el trabajo público de OpenAI, Anthropic y LangChain sobre cómo se construyen sistemas con modelos.
Esta pieza es ese marco, con las fuentes al lado y el orden en el que yo lo construiría.
Modelo y harness: la división que ordena todo
El modelo es el motor: decide. El harness es el coche: todo lo que convierte esas decisiones en trabajo terminado. Cuando algo falla, la primera pregunta no es "¿qué modelo usas?" sino "¿qué le falta al harness?".
Anthropic lo dice así: los agentes "son simplemente LLMs usando tools basados en el feedback del entorno, en un loop". - Source: Building effective agents - Anthropic Lo que rodea a ese loop es el harness, y tiene 9 piezas: 6 trabajan para el modelo, 3 trabajan para ti.
Las 6 piezas del modelo
1. Tools (diseño de herramientas). El contrato entre el modelo y tu código. Anthropic cuenta que, construyendo su agente para SWE-bench, gastaron más tiempo optimizando las tools que el prompt: el modelo fallaba con rutas relativas de archivo hasta que las hicieron obligatoriamente absolutas. - Source: Building effective agents - Anthropic
2. Loop (el ciclo). Decidir → ejecutar → observar → repetir, con condición de parada. El ToolLoopAgent del AI SDK lo implementa por ti: maneja el loop, el contexto y las condiciones de parada, y expone control explícito con stopWhen y prepareStep. - Source: Agents: overview - Vercel AI SDK
3. Memoria. Lo que sobrevive entre pasos y conversaciones. ADK lo separa en tres capas: sesión (conversación actual), estado (variables de la app) y memoria (largo plazo). - Source: Agent context - Google ADK
4. Contexto. Qué ve el modelo en cada llamada y qué se recorta. ADK lo plantea sin ambigüedad: "a diferencia de herramientas que solo pegan cadenas hasta que la ventana se desborda, ADK gestiona tu contexto... tratamos el contexto como código fuente". - Source: Agent Development Kit (ADK) - Google
5. Entorno. Dónde actúa: sistema de archivos, terminal, sandbox. Sin aislamiento, un error del agente es un error en tu máquina.
6. Objetivo y verificación. La pieza que casi todos saltan. Anthropic: es crucial que el agente obtenga "ground truth" del entorno en cada paso (resultados de tools, ejecución de código) para evaluar su progreso. Si no hay verificación, el agente no tiene forma de saber que terminó. - Source: Building effective agents - Anthropic
Las 3 piezas para ti
7. Permisos y guardrails. Qué puede hacer el agente sin preguntarte. El AI SDK ya trae aprobaciones de tools basadas en políticas; y del lado de los clasificadores existe el patrón de evaluar la acción antes de ejecutarla, con un modelo de decisión que responde si esa llamada concreta es riesgosa. - Source: Introducing System One models and Jev - TypeSafe AI
8. Observabilidad. La traza de cada paso: prompt, tool, resultado, costo, latencia. ADK trae logging, métricas y trazas como parte del framework. Sin esto, "falló el modelo" es una hipótesis, no un diagnóstico. - Source: Observability - Google ADK
9. Evals. Cómo sabes si el cambio de ayer mejoró o empeoró. ADK incluye evaluación con criterios, simulación de usuario y métricas propias; el AI SDK también documenta evaluación. Es la pieza que convierte "creo que va mejor" en un número. → Evals: los 3 tipos
El orden en el que yo lo construiría
- Objetivo + verificación (antes que nada: ¿cómo sabrás que funcionó?).
- Tools (el contrato; documéntalas como API pública).
- Loop (con condición de parada desde el día uno).
- Contexto (qué ve y qué se recorta).
- Evals (para no avanzar a ciegas).
- Observabilidad (para poder depurar).
- Permisos (cuando el agente toca algo real).
- Entorno/sandbox (cuando ejecuta código).
- Memoria (cuando se repite el trabajo o hace falta continuidad).
Es el orden inverso al de la emoción: casi todos empezamos por memoria y frameworks, y dejamos verificación y evals para el final. Es exactamente al revés.
Qué se rompe cuando falta cada pieza
| Falta | Síntoma que vas a ver |
|---|---|
| Objetivo/verificación | "Casi funciona": el agente no sabe cuándo terminar |
| Tools | El modelo improvisa y se equivoca en parámetros |
| Loop | Un prompt largo que a veces acierta |
| Contexto | Olvida lo del paso 3; gasta tokens de más |
| Evals | Cada cambio es una opinión; las regresiones vuelven |
| Observabilidad | No sabes por qué falló; culpas al modelo |
| Permisos | Un día el agente hace algo que no debía |
| Sandbox | Un error del agente se vuelve un error tuyo |
| Memoria | Empieza de cero cada vez |
La columna de la derecha es el motivo por el que esta pieza importa más que elegir el modelo de moda.
Lo que haría esta semana
- Elige un caso con verificación clara (tests, validaciones, resultado comprobable). Ahí es donde un agente se puede medir.
- Diseña las tools primero y pruébalas a mano antes de dárselas al modelo.
- Escribe la condición de parada (máximo de pasos y de gasto) antes de la primera corrida.
- Guarda trazas desde el día uno y revisa la primera corrida completa, paso por paso.
- Escribe 10 evals con casos reales, incluso si son manuales al principio.
Si quieres el mapa completo, el desglose de las 9 piezas vive en la guía AI Engineering y en Qué es un agente, de verdad.
¿Cuál de las 9 piezas te falta hoy? La mayoría de los equipos que veo tienen loop y tools, y cero verificación. Cuéntame en los comentarios cuál es la tuya.