Cómo crear agentes de IA en 2026 (Curso completo)

aquí está la verdad que nadie les dice a los constructores de IA.

la mayoría de ellos están construyendo demos

todo lo que necesitas para construir es

un agente de IA a nivel de producción

TLDR; si no quieres leerlo, dale este enlace a tu agente y hazle preguntas: ➡️https://github.com/codejunkie99/agentic-harness

aquí está el tweet que lo inició todo

el problema es que la mayoría de los ingenieros de IA no tienen una idea clara de qué construir realmente cuando deciden ponerse serios con los agentes.

algunos recurren a LangChain porque las demos multi-agente se ven limpias en YouTube, y pasan las siguientes dos semanas peleando con la interoperabilidad de Python y desajustes en el runtime asíncrono antes de desechar todo el proyecto.

algunos intentan construir una capa de orquestación personalizada desde cero: un bucle, un almacén de sesiones, un ensamblador de contexto, y nunca terminan el agente real porque la infraestructura se comió el cronograma.

otros copian el ejemplo del webhook hola-mundo, obtienen una respuesta JSON, asumen que entienden el sistema, y envían algo que se rompe la primera vez que una sesión supera los diez minutos, un sandbox remoto se cae a mitad de la tarea, o la ventana de contexto se llena sin compactación configurada.

el resultado suele ser el mismo: mucha tubería, ningún agente en producción, y ningún modelo mental de cómo se ve realmente un runtime de agente en producción.

si tu objetivo es construir y enviar agentes reales en 2026, no necesitas aprender seis frameworks.

necesitas entender un runtime lo suficientemente profundo como para ser dueño de un agente de producción desde el handler hasta el despliegue.

eso significa aprender cómo:

• cablear la arquitectura de tres capas para que tu lógica de handler sobreviva a cambios de proveedor y de objetivo sin tocar el código del agente
• usar sesiones y tareas correctamente para que los trabajos largos no contaminen su propio contexto
• escribir roles y habilidades que moldeen el comportamiento del modelo sin recompilar nada
• configurar la compactación para que las sesiones que duran dos horas no empiecen a alucinar a la hora uno
• apuntar HttpSessionEnv a sandboxes remotos para que el binario se ejecute localmente mientras la ejecución corre en Linux
• elegir el objetivo de compilación correcto: nativo, node o Cloudflare, sin reescribir ninguna lógica del agente entre ellos
• generar conectores en lugar de escribir adaptadores a mano, y entender por qué esa distinción importa bajo carga real

esta guía es un recorrido técnico completo construido a partir del código base real de agentic-harness, seis semanas construyendo y rompiendo agentes reales con él, y los modos de fallo que más tiempo costaron depurar.

el artículo tiene más de 4.000 PALABRAS y se basa directamente en el repositorio y la documentación, no en resúmenes de segunda mano ni ejemplos a nivel de demo.

pero su valor real es que cada sección tiene un fragmento de código funcional, una explicación clara de por qué se tomó la decisión, y el modo de fallo exacto que encontrarás si te lo saltas.

de esa manera, para cuando termines de leer, podrás ser dueño de un agente de producción de extremo a extremo, desde el primer handler hasta el sandbox y el trabajo de CI que lo ejecuta sin supervisión.

construir este entendimiento tomó más de 6 SEMANAS de trabajo diario con el código base, la mayor parte depurando cosas que parecían correctas antes de romperse en condiciones reales.

ahora entremos en materia. ⬇️

La Forma del Proyecto

dos crates. un binario. cada objetivo de ejecución es una elección de configuración, no una reescritura.

• el SDK es una librería que incorporas a cualquier proyecto de Rust. el CLI lo envuelve. tu agente es un binario de Rust que comienza con use agentic_harness::prelude::*.
• cargo build es todo el pipeline. sin bundler. sin paso de transpilación. sin runtime de lenguaje en la máquina de destino. un ejecutable autocontenido más un manifest.json.

la restricción de diseño que lo impulsó todo: el mismo binario del agente debería ejecutarse en tu laptop en modo interactivo, en un trabajo de GitHub Actions clonando un repositorio nuevo, contra un sandbox remoto de E2B sobre HTTP, y en el límite de un Worker de Cloudflare sin cambiar una sola línea de lógica del agente entre ellos.

cada decisión en este código base existe para honrar esa restricción.

Las 3 capas y por qué existe cada una

el modelo mental son tres anillos concéntricos. saber dónde está cada límite te ahorrará más tiempo de depuración que cualquier otra cosa en esta guía.

tu código Rust es el anillo exterior.

• escribes handlers. los handlers reciben un AgentContext. llaman a sesiones. las sesiones llaman al modelo, leen archivos, escriben archivos, ejecutan comandos de shell, lanzan tareas, se conectan a servidores MCP.
• nunca tocas un cliente HTTP directamente. nunca parseas una respuesta del modelo directamente. el SDK maneja ambos.

el harness es el anillo medio.

• gestiona el registro de agentes, enruta la identidad por ruta URL, maneja la persistencia de sesiones entre llamadas, la compactación de contexto cuando las sesiones crecen, el descubrimiento de roles y habilidades, la precedencia de selección de modelo, y el trait ModelClient neutral al proveedor.
• eso te permite intercambiar Anthropic por OpenAI por una instancia local de Ollama sin tocar el código del handler.
• el harness es lo que hace que tu lógica de agente sea reutilizable entre proveedores y objetivos.
• también es donde se manejan todas las cosas que se rompen en producción: estado de sesión, desbordamiento de contexto, fallos de proveedor, ordenamiento de solicitudes concurrentes.

los objetivos de ejecución son el anillo interior.

• sistema de archivos local. checkout de CI. HttpSessionEnv apuntando a Daytona o E2B. límite de Worker de Cloudflare.
• al harness no le importa cuál estés usando. a tus handlers tampoco. llaman a session.shell() y session.write() y el harness traduce eso a lo que necesite el objetivo subyacente.
• esta separación es el punto central. cuando E2B lanza una nueva versión de la API, actualizas el conector, no la lógica de tu agente.
• cuando Anthropic lanza claude-opus-4-7, actualizas runtime.json, no tus handlers. el anillo exterior se mantiene limpio porque el anillo medio absorbe todo el cambio.

configuración del runtime: el archivo que controla la capa del modelo

antes de escribir un solo handler, necesitas runtime.json en tu espacio de trabajo.

coloca esto en .agentic-harness/config.json o en la raíz del espacio de trabajo como agentic-harness.json. load_workspace_context() lo recoge automáticamente.

la selección del modelo en tiempo de ejecución sigue esta precedencia:

1. PromptOptions::model(...): anulación por llamada
2. los metadatos del modelo del rol seleccionado: valor predeterminado por rol
3. defaultModel de la configuración del runtime: valor predeterminado del espacio de trabajo

lo que hay que entender: el ID del modelo debe estar registrado antes de poder usarlo. openaiCompatibleModels es la lista que el harness usa para conectar el cliente integrado de chat-completions. si tu modelo no está en esa lista, obtienes un error limpio al inicio en lugar de un fallo confuso a mitad de la sesión.

para gateways compatibles con OpenAI, la configuración se ve igual. apunta baseUrl a tu gateway:

• nunca escribas una clave API literal en runtime.json. usa apiKeyEnv y mantén la clave real en tu entorno.
• el harness lee la variable de entorno en el momento de la solicitud, no al inicio, lo que significa que puedes rotar claves sin reiniciar el servidor.

la identidad del agente es una ruta URL, nunca una búsqueda en un registro

esta fue la primera decisión de diseño que me sorprendió. ahora creo que es la correcta.

no hay un sistema de ID de agente. no hay clave de registro. no hay UUID que generes tú mismo. la identidad de tu agente es POST /agents/<nombre>/<id>.

• el harness maneja toda la contabilidad del estado de la sesión detrás de esa URL.
• la razón por la que esto funciona: cada llamante en cada sistema ya sabe cómo construir un ID significativo a partir del contexto. un número de PR. un ID de ejecución. una marca de tiempo combinada con un nombre de tarea. un identificador de usuario.
• no necesitas un endpoint de creación de sesión. no necesitas almacenar IDs de sesión por separado. la URL es la sesión.

el handler del agente en el lado de Rust llama a ctx.id() para obtener el ID que haya proporcionado el llamante:

sesiones: el contexto de ejecución con estado

una sesión es más que un hilo de conversación. es el contexto de ejecución completo para una invocación de agente.

contiene:

• historial de mensajes con el modelo
• acceso a archivos del espacio de trabajo (leer, escribir, editar, grep, glob, stat, readdir)
• ejecución de shell con control de cwd y env
• registros de herramientas (servidores MCP, herramientas personalizadas)
• el rol asignado y su superposición de prompt del sistema
• el presupuesto de compactación y el watermark del historial

obtienes una sesión llamando a ctx.session_with_id() con cualquier ID que tenga sentido:

• las sesiones persisten entre llamadas HTTP cuando usas el mismo ID. llama al mismo endpoint del agente tres veces con el mismo ID de sesión, el modelo ve las tres interacciones como una conversación continua.
• el historial se acumula automáticamente. no lo gestionas tú.
• esto es lo que hace posibles los flujos de trabajo de múltiples pasos sin gestionar el estado tú mismo. sigues llamando a session.prompt() y el harness maneja todo lo demás.

cuando necesitas pasar grandes cantidades de contexto junto con un prompt, lee el archivo y dale formato en línea:

la sesión gestiona el conteo de tokens para que no desbordes accidentalmente la ventana de contexto a mitad de la conversación. cuando estás cerca del presupuesto, se activa la compactación. más sobre eso en una sección posterior.

tareas: sesiones hijas enfocadas que mantienen limpia la sesión padre

• este es el primitivo que desearía haber entendido desde el primer día. es la diferencia entre agentes que se mantienen coherentes en trabajos largos y agentes que empiezan a alucinar a mitad de camino.
• una tarea es una sesión hija de un solo uso. historial nuevo. espacio de trabajo compartido. devuelve un resultado al padre. el historial del padre nunca ve ninguno de los razonamientos intermedios de la tarea.

• la tarea de investigación se ejecuta de forma aislada. toda su cadena de razonamiento.
• cada observación intermedia que el modelo hizo sobre el código, cada "espera, déjame revisar este archivo también", se queda dentro de la tarea.
• la sesión padre recibe un resumen limpio. eso es todo lo que ve.por qué esto importa en la práctica: cuando ejecutas análisis exploratorio directamente dentro de una sesión de larga duración, el historial se llena con llamadas a herramientas intermedias, respuestas parciales y razonamiento del modelo sobre cosas que ya no son relevantes.
• el modelo se ancla en ese ruido cuando no debería. la compactación eventualmente se activa y pierde contexto que realmente necesitabas. las tareas son la solución quirúrgica.

la regla: si el subproblema tiene un entregable claro y no necesita el historial de conversación del padre para completarse, conviértelo en una tarea. el umbral para "convertirlo en una tarea" es más bajo de lo que piensas.

para análisis paralelo en un código base: el patrón cartógrafo, distribuye tareas y recoge resultados:

cada tarea está limpia. cada tarea está enfocada exactamente en un directorio. la sesión padre recoge los resultados y escribe el documento final.

si tienes 12 módulos, ejecutas 12 tareas enfocadas, cada una comenzando con cero equipaje de las demás.

roles y habilidades: moldeando el comportamiento sin recompilar

1. los roles viven en .agentic-harness/roles/. las habilidades viven en .agents/skills/. ambos se descubren automáticamente cuando el harness se inicia.
2. los roles son superposiciones de prompt del sistema con alcance a una llamada. se aplican en el momento de la llamada y se descartan después. no persisten en el historial de mensajes. no se acumulan entre llamadas.

la cadena de precedencia: rol de llamada > rol de sesión > rol de agente > sin rol.

• el frontmatter del modelo es opcional pero útil. te permite enrutar roles específicos a modelos específicos.
• tu rol de explicador se ejecuta en claude-sonnet-4-6 por velocidad y costo. tu auditor de seguridad se ejecuta en claude-opus-4-7 por profundidad. configuras esto una vez en el archivo de rol y nunca más piensas en ello.
• las habilidades son archivos descriptores de comportamiento que el modelo lee al inicio de una sesión.
• son archivos markdown en .agents/skills/. el harness los encuentra automáticamente. no los registras en ningún lado.

el uso práctico: una biblioteca de habilidades junto a tu código base describe cómo trabajas. formato de mensajes de commit, librerías preferidas, convenciones de nomenclatura de migraciones, patrones de diseño de API, requisitos de prueba.

el modelo lee esto antes de cada sesión. editas el markdown. el comportamiento se actualiza en la siguiente ejecución. sin recompilar.

el modelo lee esto. escribe commits que coinciden con tu convención. no se lo recuerdas cada sesión. mantienes un archivo.

el bucle del agente de codificación en detalle completo

el bucle del agente de codificación es el caso de uso principal para el que se construyó el CLI. también es donde más cosas pueden salir mal si lo configuras incorrectamente.

el comando completo con todas las opciones que importan:

qué hace cada bandera y por qué importa:

1. --workspace . establece la raíz. todas las operaciones de archivo están en un sandbox aquí. el agente no puede leer ni escribir fuera de esta ruta, aplicado a nivel del harness, no confiando en que el modelo se autolimite.
2. --llm auto selecciona el modelo de defaultModel en tu configuración de runtime. usa --llm anthropic/claude-opus-4-7 para tareas complejas que necesitan razonamiento profundo, o --llm anthropic/claude-sonnet-4-6 para iteración más rápida.
3. --deny-path es un bloqueo duro. coincide con prefijo, así que --deny-path config/ cubre todo lo que está debajo de config/. audita tu espacio de trabajo antes de la primera ejecución y enumera cada ruta que contenga secretos o configuración de producción, no solo .env.
4. --approve-dependencies permite modificaciones de Cargo.toml sin un paso de aprobación humana. omite esto si quieres revisar cada nueva crate antes de que se agregue.
5. --commit prepara automáticamente todos los cambios y los confirma al final de una ejecución exitosa con el mensaje que proporciones. sin esta bandera, los cambios llegan como modificaciones sin preparar para que las revises.
6. --pr abre una solicitud de extracción a partir del commit. requiere un estado limpio de git antes de la ejecución y una rama real, no un HEAD separado.

el bucle en sí: Inspeccionar → Resumir → LLM + Herramientas → Editar + Probar → Commit · PR.

• inspeccionar: lee la estructura del espacio de trabajo, carga habilidades y roles, identifica los archivos más probablemente relevantes para el prompt.
• escribe su entendimiento en coding-brief.md antes de tocar cualquier código.
• resumir: el modelo se compromete con un plan. puedes leer .agentic-harness/runs/<id>/coding-brief.md a mitad de la ejecución para ver lo que decidió.
• si el resumen parece incorrecto, mata la ejecución. es más barato reiniciar con un prompt más claro que dejar que el agente ejecute un plan malo.
• LLM + herramientas: el bucle de editar y probar. el modelo hace cambios, ejecuta el conjunto de pruebas, lee la salida, hace más cambios. itera hasta que las pruebas pasen, se alcance el límite de iteración, o decida que la tarea está completa.

commit · PR: prepara, confirma, empuja, abre el PR con el diff adjunto.

cada ejecución escribe seis artefactos en .agentic-harness/runs/<id>/:

1. coding-brief.md: el plan al que el agente se comprometió antes de escribir cualquier código
2. summary.md: relato legible por humanos de lo que se hizo, lo que se intentó y por qué
3. run.json: metadatos estructurados: modelo usado, duración total, conteos de tokens de entrada/salida, número de iteraciones, estado de salida final
4. events.jsonl: cada llamada a herramienta individual en orden con entradas y salidas completas, para depurar lo que salió mal
5. diff.patch: el diff completo de todos los cambios de archivos
6. checks.json: resultados finales de pruebas y lint que determinaron éxito o fracaso

Consejos para Recordar

• trata estos como registros estructurados, no como salida efímera. confirmo los artefactos de ejecución en el repositorio para cualquier tarea que necesite poder reproducir.
• solo el run.json (2KB) te dice el modelo, los costos de tokens y si tuvo éxito. el events.jsonl te dice exactamente lo que hizo el agente y en qué orden cuando necesitas depurar una mala ejecución.

para CI, el patrón es:

HttpSessionEnv: ejecutando el binario localmente, ejecutando remotamente

• esta es la capacidad que más tardé en entender completamente. ahora la uso en casi todas las tareas que tocan infraestructura.
• el binario del agente se ejecuta en tu máquina o en CI. las operaciones de sistema de archivos y shell se ejecutan dentro de un sandbox remoto.
• el agente no sabe ni le importa en qué entorno está.

usa agentic_harness::HttpSessionEnv;

el protocolo de cable es JSON sobre HTTP. cada operación:

1. exec
2. read
3. write
4. edit
5. grep
6. glob
7. stat
8. readdir
9. mkdir
10. rm tiene una forma de solicitud/respuesta definida.

cualquier sandbox que implemente este protocolo funciona como un objetivo HttpSessionEnv.

para conectar un sandbox con nombre:

los conectores integrados manejan la autenticación y el boilerplate del ciclo de vida para Vercel Sandbox, Daytona y E2B:

• el caso de uso concreto para el que más uso esto: reproducir fallos de CI en un entorno Linux limpio.
• el agente clona el repositorio en el hash de commit exacto que falla, ejecuta el comando de prueba exacto que falla, lee la salida completa, diagnostica el fallo y escribe un informe.
• leo el informe. nunca toqué mi máquina local. el sandbox se descarta cuando termina la sesión.

la cuestión de rendimiento de la que nadie te advierte: cada llamada de shell a través de HttpSessionEnv es un viaje de ida y vuelta de red. los bucles ajustados (editar, probar, verificar salida, editar) acumulan latencia rápidamente.

un bucle de 40 iteraciones que toma 5 segundos localmente toma varios minutos contra un sandbox remoto si cada iteración hace tres llamadas de shell separadas.

la solución: agrupar el trabajo de shell en scripts.

una llamada por iteración en lugar de tres. escribe el script una vez, ejecútalo repetidamente. la diferencia de latencia en un bucle de 40 iteraciones es real.

objetivos de compilación: mismo código base, tres formas de despliegue

nativo es el predeterminado. un binario. un manifest. nada más en la máquina de destino. se ejecuta en cualquier lugar que pueda ejecutar un binario nativo de Linux.

node es para plataformas de hosting que requieren un punto de entrada Node. la compilación genera server.mjs que inicia el binario nativo de Rust como un proceso hijo y proxy HTTP hacia él. la lógica del agente sigue ejecutándose como Rust. la capa Node es un shim HTTP de 30 líneas.

Cloudflare es para despliegue en el borde.

• la compilación genera un archivo de límite de Worker y enlaza un adaptador de aplicación compatible con Worker.
• los handlers se compilan a WASM a través de la ABI JSON de WASM.
• los enlaces de Durable Object manejan la persistencia de sesiones a través de Cloudflare KV.

la restricción importante sobre Cloudflare: los Workers no admiten comandos de shell de larga duración. no tienen un sistema de archivos real.

no admiten cargo ni ninguna herramienta de compilación. --target cloudflare es para manejo de webhooks, metadatos de ruta, pequeños endpoints de control y enrutamiento de Durable Object, no para trabajo de codificación.

para cualquier cosa que necesite ejecutar cargo test, delega a un proceso nativo o sandbox remoto.

la matriz de decisión práctica:

• enviar un agente como una API a la que otros servicios llaman → nativo detrás de nginx o una plataforma gestionada
• alojar en Railway, Render o una plataforma que espera Node → node
• ingesta de webhooks, enrutamiento ligero, gestión de estado de Durable Object → cloudflare
• todo lo demás → nativo

salida guiada por esquema: structs de Rust tipados a partir de respuestas del modelo

pedirle al modelo que devuelva JSON y esperar que lo haga es la mitad de la solución.

que el harness extraiga, valide y deserialice en tu struct de Rust es la solución completa.

el modelo puede devolver prosa de razonamiento junto con la carga útil tipada en la misma respuesta. el harness extrae el bloque de resultado entre

• los marcadores ---RESULT_START--- y ---RESULT_END---. obtienes un struct de Rust. seguridad de tipos en tiempo de compilación desde la salida del modelo hasta tu lógica de handler.
• el esquema hace dos cosas: le dice al modelo qué forma producir, y le da al harness algo contra lo que validar antes de la deserialización.
• si el modelo devuelve algo que no coincide con el esquema, obtienes PromptError::SchemaValidationFailed en lugar de un pánico tres sitios de llamada después cuando accedes a un campo faltante.

herramientas MCP: alcanzando fuera del sandbox

cuando el agente necesita capacidades más allá de archivo y shell, connect_mcp es la escotilla de escape.

el agente obtiene el conjunto completo de herramientas del servidor MCP. no hay definiciones de herramientas que escribir. las descripciones vienen del servidor. el modelo decide cuándo llamar a qué herramienta basándose en esas descripciones.

puedes conectar múltiples servidores MCP a una sesión:

• el modelo llama a las herramientas basándose en sus descripciones. una descripción vaga como "buscar en sentry" se llama de manera inconsistente.
• una descripción que dice "llama a esto antes de responder cualquier pregunta sobre errores, incidentes o problemas de producción" se llama de manera confiable.
• si controlas el servidor MCP, escribe descripciones prescriptivas: dile al modelo cuándo llamar, no solo qué devuelve.

conectores: generando adaptadores en lugar de escribirlos

en lugar de escribir código de adaptador a mano contra una API desconocida, pasa una receta de conector a tu agente de codificación:

• la receta del conector es una descripción estructurada de la API del sandbox y el contrato SessionEnv que debe satisfacer.
• el agente de codificación la lee, escribe el módulo adaptador de Rust, maneja la autenticación, envuelve el ciclo de vida del proveedor y lo expone como un HttpSessionEnv.
• revisas el diff. lo fusionas. el adaptador vive en tu proyecto. ahora es tu código.

conecté Daytona usando esto en unos 20 minutos, incluido el ciclo de revisión completo. el agente acertó el formato del encabezado de autenticación en el primer intento.

escribir el adaptador desde cero contra la documentación de Daytona habría tomado la mayor parte de una tarde y al menos dos suposiciones incorrectas sobre el flujo del token de actualización.

una vez que se genera el conector:

compactación automática: manejando sesiones largas sin perder contexto

las sesiones de larga duración acumulan historial.

eventualmente desbordan la ventana de contexto del modelo.

el harness maneja esto automáticamente, pero necesitas configurarlo correctamente o perderás contexto exactamente en el momento equivocado.

context_window_tokens es el presupuesto total para la sesión.

• reserve_tokens es lo que reservas para la respuesta del modelo. el límite efectivo para el historial es context_window_tokens - reserve_tokens.
• keep_recent_messages es el número de mensajes al final que siempre se preservan textualmente independientemente de la compactación.

cuando el historial excede el presupuesto, el harness le pide al modelo que resuma todo entre el prompt del sistema y la cola mantenida.

ese resumen reemplaza la sección media. los mensajes de la cola permanecen intactos. la sesión compactada es más pequeña y la siguiente llamada cabe dentro del presupuesto.

la compensación es real: los resúmenes pierden precisión. una decisión específica tomada hace 50 mensajes: "elegimos authlib porque es la única librería con soporte PKCE que funciona con el modelo de middleware de axum" podría sobrevivir como "elegimos authlib para autenticación" en el resumen.

si esa precisión es crítica para decisiones posteriores en la sesión, guárdala explícitamente:

• escribe las decisiones en archivos. los archivos sobreviven a la compactación. el modelo puede leerlos bajo demanda. el historial no necesita cargar con todo si el espacio de trabajo lo hace.
• ejecuta agentic-harness doctor para ver la ventana de contexto real reportada de tu modelo. establece context_window_tokens al 80-90% de ese valor.
• el contador de tokens no es perfectamente preciso del lado del modelo, y una sola lectura de un archivo grande puede empujarte por encima si estás sentado al 99%.

Qué vigilar

1. contaminación del historial de sesión

• problema: el análisis exploratorio dentro de una sesión larga envenena los prompts posteriores con ruido de la fase de exploración
• solución: usa tareas. el historial de la tarea nunca toca al padre. el umbral para "convertirlo en una tarea" es más bajo de lo que piensas

1. sorpresas de precedencia de roles

• problema: un rol a nivel de llamada sombrea el rol de sesión. el modelo se comporta de manera diferente a la esperada y no sabes por qué
• solución: el rol de sesión establece la identidad. el rol de llamada enfoca el alcance. se superponen: el rol de llamada añade, no debería cancelar

1. brechas de --deny-path

• problema: niegas .env. tus secretos también viven en .env.local y config/staging.yaml. el agente lee uno de ellos
• solución: niega prefijos, no nombres de archivo. --deny-path config/ cubre todo lo que está debajo

1. HEAD separado en CI

• problema: el agente edita, las pruebas pasan, el commit falla porque no hay una rama a la que confirmar
• solución: git checkout -b agent-run-$RUN_ID antes de invocar el harness

1. latencia de HttpSessionEnv en bucles ajustados

• problema: 40 iteraciones con tres llamadas de shell cada una son minutos de latencia de red pura
• solución: escribe agent-check.sh que haga todo en una invocación. una llamada por iteración

1. subestimación del presupuesto de contexto

• problema: la compactación se activa a mitad de la tarea. el modelo pierde su plan y empieza a improvisar a partir del resumen
• solución: ejecuta agentic-harness doctor para obtener la ventana real. establece el presupuesto al 80-90% de eso

1. configuración del runtime cargada después del registro del handler

• problema: un handler se ejecuta antes de load_workspace_context(). no hay modelo registrado. el error no se parece en nada a un problema de configuración
• solución: siempre llama a load_workspace_context() en app() antes de conectar cualquier agente

1. --llm cambiando automáticamente entre ejecuciones

• problema: defaultModel se actualiza. dos ejecuciones con seis meses de diferencia no son comparables. no puedes reproducir la primera
• solución: fija el modelo en runtime.json para todo lo que necesite reproducibilidad

1. eliminar artefactos de ejecución

• problema: limpias runs/ en una regla de gitignore. tres semanas después necesitas reproducir una regresión y todo ha desaparecido
• solución: haz commit de los artefactos de ejecución para cualquier tarea que necesites reproducir. run.json pesa 2KB. consérvalo

cosas que haría diferente

1. ejecutar la guía de agentic-harness antes de tocar nada.
2. escribir pruebas a nivel de sesión antes de escribir la lógica del handler.
3. usar tareas para todo lo que tenga un sub-entregable.
4. fijar el modelo desde la primera ejecución seria.
5. almacenar decisiones en archivos, no en el historial de la sesión.
6. agrupar operaciones de shell desde el principio al usar sandboxes remotos.

la conclusión

la mayoría de los frameworks de agentes son envoltorios alrededor de una llamada API. esto es un runtime.

un envoltorio resuelve "hacer que el modelo responda". un runtime resuelve "enviar un agente a producción y mantenerlo funcionando después de que el modelo cambie, después de que el sandbox cambie, después de que el código base cambie, después de que la sesión se ejecute durante dos horas y desborde la ventana de contexto".

la arquitectura de 3 capas

1. tu código
2. el harness
3. el objetivo de ejecución

es lo que hace posible eso. tú escribes handlers. el harness absorbe toda la complejidad operativa. el objetivo de ejecución es una elección de configuración.

las cosas que no cambian: lógica del handler, estructura de la sesión, patrones de tareas, definiciones de roles, archivos de habilidades. las cosas que cambian: modelos, proveedores, vendedores de sandbox, destinos de despliegue.

la arquitectura está diseñada para que las cosas que cambian nunca toquen las que no.

esa es la apuesta. es la apuesta correcta.

espero que hayas disfrutado leyendo esto y explorando cómo construyo para agentes y en general ❣️

Descargos de responsabilidad

Este artículo fue investigado y escrito por el autor, editado por Minimax-M2.7. La miniatura fue tomada de Pinterest.

Harrison Chase "la memoria debería ser abierta" —

[https://x.com/hwchase17/status/2046308913939919232Harrison](https://x.com/hwchase17/status/2046308913939919232Harrison)

Chase: "Tu Harness, Tu Memoria" —

[https://www.langchain.com/blog/your-harness-your-memory](https://www.langchain.com/blog/your-harness-your-memory)

Vivek Trivedi: "La Anatomía de un Harness de Agente" —

[https://www.langchain.com/blog/the-anatomy-of-an-agent-harness](https://www.langchain.com/blog/the-anatomy-of-an-agent-harness)