Agent Harness

Qué problema resuelve

Un modelo puede proponer una acción, pero esa propuesta no prepara un workspace, ejecuta una herramienta ni decide cómo devolver su resultado a la siguiente inferencia. Entre inferencia y trabajo efectivo hacen falta mecanismos de ejecución. Agent Harness es la capa de runtime y coordinación que sostiene la ejecución de un agente basado en modelos y media su interacción con contexto, herramientas, estado, políticas y entorno. Es la definición de trabajo del Atlas para una responsabilidad del sistema, no un estándar formal compartido por toda la industria.

El problema aparece cuando una tarea necesita continuidad. Investigar una validación de checkout exige interpretar el encargo, inspeccionar código, ejecutar una comprobación, incorporar su resultado y decidir si continuar. Encadenar respuestas manualmente puede resolver un caso; sostener esa interacción requiere asociar solicitudes con resultados, conservar el alcance y manejar fallos. El harness aporta maquinaria para hacerlo sin atribuir al modelo capacidades que realmente pertenecen a otros componentes.

La palabra tiene uso suficientemente consistente para estudiar esa responsabilidad, aunque sus fronteras comerciales varían. OpenAI presenta el harness de Codex como ejecución alrededor del modelo; Anthropic describe el agentic harness al explicar herramientas y contexto de Claude Code. Son usos actuales, no definiciones idénticas. El Atlas conserva una abstracción portable y trata funciones concretas, APIs y empaquetado como decisiones de implementación.

Modelo, agente y harness

El modelo realiza inferencia. agents define el sistema que utiliza esa capacidad para observar, seleccionar acciones y avanzar hacia un objetivo acotado. El harness proporciona mecanismos que sostienen ese comportamiento. Son unidades de análisis diferentes: una explicación del agente se concentra en qué decisiones se delegan; una explicación del harness pregunta cómo se ejecutan y controlan las interacciones necesarias.

Cambiar el harness puede cambiar resultados aun conservando el modelo. El contexto disponible, el catálogo de herramientas, el tratamiento de errores, los límites de continuidad y las políticas influyen en qué puede observar y hacer el sistema. No se sigue que el harness determine toda la calidad: una inferencia equivocada o un objetivo mal expresado siguen importando. La comparación útil examina el conjunto y sus fronteras, sin adjudicar todo éxito o fallo al modelo.

Un producto puede incluir interfaz, modelos, lógica de agente, harness, servicios y uno o varios entornos. Llamar harness a todo el producto puede ser una abreviatura comercial, pero oculta responsabilidades. Una experiencia CLI no es el concepto, ni un IDE define dónde se ejecutan sus comandos. La misma función de runtime puede aparecer en una aplicación de soporte, un sistema de análisis o un coding-agent.

Responsabilidades posibles

Un harness puede invocar modelos, preparar contexto e instrucciones, sostener el loop, registrar herramientas, despachar llamadas y recoger resultados. También puede mantener estado de ejecución, mediar políticas, solicitar autorizaciones, aplicar límites y relacionarse con el entorno. Retries, checkpoints, trazas o delegación son capacidades posibles; no constituyen una lista obligatoria para merecer el nombre.

La separación importa al evaluar una necesidad. Un agente que consulta una API y responde puede funcionar con poca maquinaria. Una investigación larga puede necesitar recuperar continuidad después de una interrupción. Agregar memoria persistente, múltiples agentes o un sistema de plugins porque aparecen en un framework introduce costos sin demostrar utilidad. El diseño empieza por lo que la tarea necesita sostener y por las consecuencias de un fallo.

Las responsabilidades pueden distribuirse entre procesos y servicios. Una aplicación puede mantener las decisiones de autorización mientras otro componente ejecuta herramientas. También puede existir un runtime integrado. La arquitectura de Agents API distingue harness, entorno y aplicación. Esa división ilustra una realización; no obliga a reproducir sus límites físicos en todos los sistemas ni convierte una responsabilidad conceptual en un servicio independiente.

El loop y la ejecución efectiva

Una interacción simplificada recibe una observación, solicita inferencia, interpreta una salida, comprueba si una acción puede ejecutarse y devuelve su resultado al proceso. Una salida del modelo puede ser respuesta final, petición de herramienta o necesidad de aclaración. El harness tiene que distinguir esas situaciones de una ejecución realmente completada. Un texto que afirma haber corrido tests no equivale a un resultado de proceso.

La correlación entre solicitud y resultado es parte del problema. Si el agente pidió inspeccionar un archivo y recibe la salida de otra operación, puede razonar de forma coherente sobre evidencia equivocada. Si una herramienta devuelve contenido parcial, el runtime debe conservar esa condición en lugar de presentarlo como una observación completa. La interfaz del modelo no elimina estas responsabilidades de integración.

Continuar también tiene condiciones. Un loop puede detenerse por respuesta final, interrupción, tiempo, cantidad de pasos, fallo o frontera de política. Alcanzar un límite no demuestra haber cumplido el objetivo. El harness puede comunicar la razón operativa de detención; la aceptación del resultado necesita criterios y evidencia de la tarea. Incorporar más iteraciones no corrige automáticamente una hipótesis errónea.

Contexto, herramientas y estado

El contexto disponible puede reunir encargo, instrucciones, fragmentos de archivos y observaciones recientes. El harness ayuda a ensamblarlo y entregarlo a la inferencia, sin garantizar que toda selección sea pertinente. context-engineering-for-software-development estudia esa estrategia en desarrollo y persistent-instructions la guía reutilizable que puede cargar el runtime. Una entrada técnicamente disponible puede ser obsoleta, innecesaria o no confiable; información y autoridad siguen siendo distintas.

Una herramienta expone una capacidad; el harness organiza su disponibilidad e invocación y maneja resultados. Registrar una función de escritura no significa que cualquier escritura esté autorizada. Tampoco toda salida debe convertirse en instrucción: un README o un resultado de búsqueda puede contener texto ajeno al encargo. La mediación efectiva depende además de permisos y de las restricciones que rijan la ejecución.

Agent State and Sessions

Agent State describe la condición operativa de la ejecución: trabajo activo, observaciones recibidas, solicitudes pendientes, resultados y causa de detención. No todo estado interno se entrega al modelo; parte puede representarse después como contexto. Una lista visible que marca una tarea como activa no demuestra que exista un proceso en ejecución ni sustituye el estado efectivo de las herramientas.

Una sesión delimita continuidad e identidad de interacciones y estado bajo el contrato del runtime. Puede relacionar varios turnos con una tarea o conservar decisiones pendientes. No se impone una correspondencia universal entre sesión, conversación, agente y proceso. Reiniciar un cliente no determina por sí solo que desapareció la sesión, y conservar mensajes no garantiza que el runtime pueda reanudar una operación.

agent-memory retiene información para decisiones futuras y puede solaparse con el estado sin ser sinónimo. agent-checkpoints-and-recovery captura estado restorable; agent-tracing relaciona eventos observables. Una sesión puede existir sin persistencia duradera y un checkpoint puede necesitar revalidar recursos y autoridad al restaurarse. El objeto Session de un protocolo conserva su contrato particular, sin definir toda la continuidad general del agente. Estos temas permanecen agrupados o enlazados, sin un formato de estado obligatorio.

Entorno, permisos y sandbox

agent-execution-environment describe los recursos y el contexto concreto donde se observan o producen acciones. El harness puede ejecutarse cerca de ese entorno o comunicarse con un ejecutor remoto. No hay obligación de que inferencia, coordinación y comandos compartan máquina. Para entender el sistema conviene localizar cada acción y cada control, en vez de deducirlo del lugar donde aparece la interfaz.

agent-permissions-and-approval-boundaries separa autoridad de acción y autorización adicional en un punto. El harness puede aplicar reglas o mediar una aprobación, pero el modelo no concede permisos por solicitar una herramienta. Si una operación requiere autorización, la ejecución debe conservar ese estado y su alcance; una explicación posterior no sustituye la decisión que debía anteceder al efecto.

agent-sandboxing limita recursos y consecuencias mediante restricciones técnicas. Puede rodear la ejecución de comandos mientras otra parte del harness conserva control confiable fuera de esa frontera. La distinción de control y compute en los sandbox agents de OpenAI muestra esa posibilidad. La arquitectura debe examinarse por sus garantías concretas, sin asumir que un harness trae sandbox o que ambos son equivalentes.

Una vista conceptual

flowchart TB
  G[Objetivo y alcance] --> A[Sistema agente]
  A --> H[Harness: mecanismos de ejecución]
  H <-->|Acciones y observaciones| E[Entorno de ejecución]

La figura separa responsabilidades para leer el Atlas; no prescribe una arquitectura universal ni componentes obligatorios. El agente es el sistema orientado al objetivo, no otro nombre del harness. El harness invoca el modelo y media herramientas; permisos, aprobación y sandbox conservan sus responsabilidades distintas. Las flechas no fijan procesos, redes ni ubicación de controles. Un entorno puede alojar parte del runtime y una herramienta remota puede operar en otra infraestructura con autorización propia.

Workflow, orchestrator, framework y protocolo

workflows-vs-agents estudia quién determina el siguiente paso. Un workflow describe una estructura de control; un harness proporciona maquinaria para ejecutar interacciones. Un workflow puede invocar un agente mediante un harness, y ese runtime puede ejecutar pasos predefinidos. Tener un harness no obliga a delegar toda decisión al modelo ni convierte automáticamente el proceso en autónomo.

agentic-workflow-patterns compara secuencia, rutas, concurrencia, delegación y refinamiento. Un orchestrator coordina trabajo; puede ser parte de un harness, pero no agota sus funciones. Un agente sencillo puede necesitar contexto, herramientas y límites sin descomponer tareas entre workers. A la inversa, una coordinación entre componentes convencionales no necesita describirse como un harness de agentes.

Framework y SDK son tecnologías para implementar o integrar capacidades. Pueden proporcionar un loop, interfaces de herramientas o gestión de estado; también pueden dejar parte de esas tareas a la aplicación. MCP es un protocolo de interoperabilidad que un harness puede integrar, no el runtime completo. UI, CLI y servicios de producto agregan otras responsabilidades. Ningún nombre de paquete sustituye identificar qué componente ejecuta, autoriza o conserva estado.

Ejemplo: investigar un bug de Commerce

Una persona encarga investigar un rechazo de importes en Payments UI, preservar el contrato de cobros y reportar evidencia. El harness puede cargar instrucciones aplicables, preparar contexto e invocar el modelo. El sistema agente decide buscar la validación; el runtime despacha lecturas y relaciona sus resultados con la tarea. El contenido leído informa la investigación sin adquirir autoridad para ampliar el encargo.

La siguiente acción propuesta es ejecutar un test. El harness media la política correspondiente y envía la operación al entorno permitido. Allí pueden faltar dependencias o fallar la red: el resultado se devuelve como evidencia de esa condición, no como prueba de que la validación es correcta o incorrecta. El agente puede adaptar la investigación con lo observado.

Si el siguiente paso propone borrar datos o desplegar, aparece una decisión distinta de continuar leyendo. La autoridad existente y la aprobación requerida deben comprobarse antes de actuar. Al terminar, el sistema comunica cambios, evidencia y límites. El ejemplo separa decisiones orientadas al objetivo de la maquinaria que las sostiene; no introduce un workflow obligatorio ni promete que todas sus acciones serán correctas.

Solicitudes, errores y efectos

Despachar una operación no garantiza recibir un resultado inequívoco. Una llamada puede interrumpirse después de que el sistema externo aceptó el efecto y antes de que llegue la confirmación. El harness necesita conservar la diferencia entre «rechazada», «no ejecutada» y «resultado desconocido». Presentar todas como un fallo equivalente puede llevar al agente a repetir una mutación que ya ocurrió, aunque la integración funcione normalmente en los casos exitosos.

Un retry puede ser adecuado para ciertas lecturas y peligroso para una acción que genera efectos adicionales al repetirse. idempotency conserva ese fundamento; el runtime no lo crea por envolver una herramienta. En Commerce, reintentar obtener el resultado de un test no tiene las mismas consecuencias que emitir otra solicitud de cobro. La decisión necesita semántica de la operación, no solamente una política genérica de «seguir intentando».

También hay un contrato de observación. El código de salida, el timeout, la salida truncada y el destino efectivo pueden ser relevantes para interpretar lo ocurrido. El harness puede hacer disponible esa evidencia y limitar la continuación; no debe inventar una confirmación para mantener el flujo. Si el estado externo sigue incierto, detenerse o pedir intervención puede ser más útil que sostener una narrativa de progreso. Esta frontera conecta integración y seguridad sin desarrollar aquí un motor de recuperación ni exigir garantías de ejecución exactamente una vez.

Límites y relaciones en el Atlas

Un harness puede alojar clientes de MCP, exponer interacción mediante ACP o sostener un sistema que participe en A2A. Cada protocolo conserva su contrato de comunicación; ninguno define el runtime completo ni es obligatorio para cualquier harness.

Un harness puede implementar discovery de agent-skills, carga de agent-profiles y agent-extension-packages, ejecución de lifecycle-hooks o emisión de development-context-and-execution-records. Esas capacidades dependen de la implementación: el runtime no equivale a ninguno de sus artefactos ni necesita ofrecerlos todos.

Un harness puede perder continuidad, despachar mal una herramienta, alimentar contexto obsoleto o aplicar una política distinta de la esperada. También puede sostener un loop improductivo de forma técnicamente impecable. El control de ejecución ayuda a delimitar y observar el trabajo, pero no demuestra corrección semántica. Una traza o un estado final exitoso requieren interpretación respecto del objetivo real.

agent-evaluation considera esas condiciones al evaluar el sistema, sin atribuir todo resultado al modelo. coding-agent-failure-modes-and-recovery aplica la distinción al trabajo de desarrollo: un fallo de herramienta no equivale automáticamente a fracaso de la tarea y una invocación exitosa no demuestra cumplimiento del encargo.

La maquinaria tiene costos: integración, contratos entre herramientas, compatibilidad de entornos y mantenimiento de políticas. Una API uniforme puede ocultar diferencias relevantes de autorización o efectos. La respuesta no es agregar todos los mecanismos posibles, sino hacer explícitas las responsabilidades necesarias y comprobar sus límites. Un cambio de modelo no repara por sí solo un fallo de integración del runtime.

Este canonical conserva el concepto general de harness. Agents define al sistema; Environment ubica recursos; Permissions/Approval delimita autoridad; Sandboxing estudia restricción técnica. ai-assisted-software-engineering ofrece una navegación de desarrollo sobre esos conceptos generales. Estado y sesiones permanecen agrupados aquí; memoria, checkpoints y tracing conservan sus canónicos propios, sin convertirse en requisitos universales de todo runtime.

Fuentes

Fuentes primarias consultadas el 2026-10-25. La definición de trabajo, el diagrama, las comparaciones y Commerce son síntesis editorial del Atlas. Los usos de harness varían entre proveedores y no establecen un estándar formal único.

• OpenAI: Codex as a platform, uso explícito del término y separación respecto de superficies de producto.
• Anthropic: How Claude Code works, loop, herramientas y contexto alrededor del modelo.
• OpenAI: Agents API architecture, una realización de harness, aplicación y entorno.
• OpenAI: Sandbox agents, posible separación entre control de ejecución y compute.