AI agent harness: cómo diseñar un runtime fiable

Un AI agent harness es el bucle de control de software que llama repetidamente al modelo, compone el contexto, enruta tool calls, conserva el estado y decide cuándo un run debe continuar, detenerse, recuperarse o pasar a una persona. El modelo propone el siguiente paso, pero el harness controla el execution loop y el entorno. Aquí viven deadlines, límites de pasos, permisos, sandbox, retries, checkpoints, tracing y la verificación del resultado terminal.

No use el término como etiqueta de moda para un único system prompt o wrapper de SDK. Prompt engineering ajusta instrucciones; context engineering selecciona información para una llamada concreta; un planner propone una ruta; un framework aporta abstracciones; el harness conecta esas piezas con un runtime contract real. Un producto puede ofrecer un harness gestionado y otro primitives para construir uno propio, pero la marca del modelo no determina la fiabilidad del sistema completo.

• Modelo → propone una respuesta o tool call dentro del contexto visible.
• Harness → gestiona loop, estado, tools, budgets, aislamiento y recovery.
• Application policy → define autoridad, approvals y resultados permitidos.
• Entorno → ejecuta comandos y almacena artefactos autoritativos.

Un baseline de producción necesita cinco contratos separados. La session es un registro append-only de eventos con correlation ID. El loop construye el input, llama al modelo, valida la respuesta y aplica la stop policy. El tool gateway publica una allowlist estrecha y vuelve a validar argumentos y permisos. El sandbox aísla filesystem, procesos y destinos de red. El state store guarda task status, referencias a artefactos, approvals y postconditions independientemente del transcript de chat.

Esta separación permite sustituir componentes. El modelo o prompt puede actualizarse sin migrar el task state autoritativo; el sandbox puede endurecerse sin reescribir el planner; una implementación de tool puede revertirse conservando el trace. Anthropic describe session, harness y sandbox como partes distintas de sistemas de managed agents, mientras OpenAI describe un model-native harness junto con sandbox execution. Son descripciones arquitectónicas de primera parte, no una prueba de superioridad universal de un proveedor.

• Session log: model calls, tool requests, resultados, approvals y motivo terminal.
• Task state: planned, running, blocked, awaiting-approval, completed o failed.
• Artifact store: outputs versionados, checksums, provenance y owner.
• Sandbox policy: mounts, secrets, network egress, límites de recursos y cleanup.
• Control plane: budgets, kill switch, concurrency, resume y reconciliation.

Un agente de larga duración atraviesa context windows, reinicios y esperas de approval. La compaction ayuda a encajar el historial, pero no sustituye un estado duradero. Un checkpoint debe contener la versión de la tarea, acceptance criteria completados, artefactos verificados, riesgos abiertos, approvals pendientes, las últimas postconditions autoritativas y un siguiente paso concreto. Una nueva session empieza verificando entorno y estado, no confiando en un resumen optimista del modelo anterior.

En su investigación sobre harnesses de larga duración, Anthropic utilizó una feature list, un progress artifact, control de versiones y una comprobación end-to-end básica antes del siguiente cambio. El principio transferible no es el nombre del archivo, sino el handoff protocol: el trabajo se divide en slices terminables, el estado se confirma con una prueba y el siguiente worker recibe un paquete corto y verificable. En soporte o research, ese paquete puede ser case state, evidence ledger y una acción pendiente en lugar de un commit de git.

Un harness no debe entregar al modelo un catálogo universal de tools y esperar que un prompt preserve los límites. En cada paso, el tool gateway verifica actor, tenant, resource, action, parameters, risk tier, versión del approval y expiración. Las operaciones read, draft y write usan credenciales distintas. Una acción relevante recibe idempotency key, preflight preview y postcondition esperada; un timeout tras la llamada conduce a reconciliation en vez de a un retry ciego.

El sandbox reduce el blast radius, pero por sí solo no crea autorización de negocio. Un proceso puede estar aislado y aun así tener un token peligroso o egress permitido hacia una API de producción. La autoridad efectiva es la intersección de sandbox policy, credential scope, tool contract, application rules y un approval vigente. Prompt injection, una dependencia comprometida o un error del modelo no deben poder ampliar esa intersección mediante instrucciones de texto.

• Permiso desconocido o approval obsoleto → fail closed.
• Resultado desconocido de un write call → reconcile antes de retry.
• Nuevo destino o scope → decisión de autorización independiente.
• Kill switch → bloquea nuevas acciones y conserva forensic evidence y recovery path.

Las golden tasks deben evaluar outcome y trajectory. Los graders deterministas verifican schema, filesystem diff, API postcondition, budget y eventos prohibidos. Un model grader puede valorar la calidad de un artefacto abierto, pero no sustituye la comprobación de permisos ni del side effect real. Human review sigue siendo necesario para utilidad ambigua y riesgo material. Una violación crítica de policy no debe diluirse por un buen estilo de redacción.

La failure suite debe cubrir agotamiento de contexto, checkpoint corrupto, duplicate delivery, tool response perdida, partial commit, credencial revocada, stale branch, dependencia no disponible, prompt injection en contenido recuperado y un agente que declara completion antes de superar el acceptance test. Compare no solo task success, sino verified progress por run, tool calls innecesarios, recovery success, reviewer minutes, wall-clock time y cost per accepted outcome sobre el mismo corpus. Los experimentos publicados por un vendor no son su baseline.

Empiece con una tarea read-only y acotada que ya tenga un baseline de workflow determinista. Añada un model loop, dos o tres tools diferenciados, estados terminales explícitos, task state fuera del transcript y un trace completo. Después introduzca un restart fixture, un corrupted-state fixture y un canary sobre un segmento pequeño. Añada planner-generator-evaluator multi-agent, loops autónomos largos o write authority solo cuando el harness más simple falle de forma demostrable en task slices registrados.

Un harness codifica supuestos sobre las debilidades del modelo actual, por lo que cada workaround necesita owner, eval y review date. Tras actualizar modelo o tool, haga una ablation: ¿sigue necesitando planner separado, context reset forzado, demasiados critique loops o un prompt grande? El rollback restaura un paquete compatible de loop policy, versiones de tools y checkpoint schema; los writes activos se reconcilian primero. El mejor harness no es el mayor, sino el circuito mínimo que demuestra que completa sus tareas dentro de los límites definidos.

• Define → outcome, authority, environment y terminal states.
• Instrument → session events, state transitions, budgets y artifacts.
• Evaluate → success, policy, recovery, efficiency y human acceptance.
• Canary → read-only, bounded concurrency, kill switch y on-call owner.
• Simplify → elimine periódicamente scaffolding que ya no aporta una mejora medible.