🪜 Las cinco capas

La primera capa es la que todos conocen: el prompt, el texto que escribes para pedirle algo al modelo. También es la capa donde la mayoría de las personas se atasca: cuando el agente hace algo mal, la reacción es «déjame reescribir el prompt». A veces funciona. La mayoría de las veces, solo aplaza el problema.

Mejorar el prompt tiene rendimiento decreciente rápido: las primeras mejoras (ser específico, dar un ejemplo, pedir un formato de salida) resuelven muchas cosas. Después de cierto punto, agregar más instrucciones al prompt deja de cambiar el resultado. Eso es una señal — no de que hayas escrito mal, sino de que el problema cambió de lugar.

Qué observar: la línea punteada sube sin romperse: cada escalón está encima del anterior, no en su lugar. El brillo queda solo en el último escalón, "grafo", que es el horizonte de este módulo. Recuerda el orden: es ahí donde vas a diagnosticar en qué punto está realmente atascado un agente que no funciona.

La segunda capa es el contexto: todo lo que el agente «ve» en el momento de actuar: archivos abiertos, historial de la conversación, documentación adjunta, salida de una herramienta que acaba de ejecutar. El prompt es lo que le pides; el contexto es lo que sabe mientras responde. Son cosas distintas, y confundirlas es el error más común después del prompt.

Todo modelo tiene una ventana de contexto limitada. Cuando se llena de cosas irrelevantes — logs detallados, archivos que nadie necesita, historial repetido — el modelo empieza a "olvidar" lo que importa, aunque la instrucción original fuera perfecta. Un contexto incorrecto perjudica un buen prompt; ningún prompt es lo suficientemente bueno para compensar una ventana de contexto contaminada.

La tercera capa es el harness: la infraestructura que rodea al modelo. Qué herramientas tiene (leer archivos, ejecutar comandos, llamar a una API), con qué permisos, cómo se captura la salida de cada herramienta y se devuelve al modelo, qué ocurre cuando falla una herramienta (reintento — volver a intentarlo automáticamente), y cuánto presupuesto de tokens tiene para gastar toda la tarea.

El prompt dice qué; harness dice con qué. Un agente con un prompt perfecto y un harness deficiente (sin acceso al archivo correcto, sin permiso para ejecutar el comando que resolvería el problema) se queda atascado de todos modos — y ninguna reescritura del prompt lo destraba, porque el problema nunca estuvo en el texto.

La cuarta capa es el loop: cuántas veces lo intenta el agente y cómo sabe que terminó. Esa es toda la Ruta 2 condensada: descubrir, planificar, actuar, verificar, detenerse. Es la capa en la que dejas de escribir prompts y empiezas a diseñar ciclo: ya no se trata de qué pedir en una sola llamada, sino de cómo se comporta el sistema a lo largo de varias.

Un agente puede tener un prompt excelente, contexto limpio y un harness bien montado y aun así fallar — porque nadie diseñó la condición de parada, o porque el verificador (lo que decide si el resultado es bueno) está ausente o es débil. En ese punto, más prompt no ayuda: lo que falta es diseñar el loop.

La quinta capa solo tiene sentido después de las otras cuatro: cuántos bucles tienes y cómo se conectan. Aquí, un grafo es literalmente varios bucles (o nodos sin ningún bucle) conectados por aristas — el investigador se lo envía al escritor, el escritor se lo envía al revisor, y el revisor puede devolverlo al escritor. Cada uno de estos es un nodo; toda la red es el grafo.

Subir a esta capa sin dominar las cuatro de abajo multiplica el problema en vez de resolverlo. Si un bucle individual ya no tiene una condición de parada clara, poner tres de esos bucles en un grafo no crea tres problemas — crea un problema combinatorio, porque ahora cada bucle mal diseñado puede contaminar a los vecinos.

El harness de UN loop cabe en un script: entrada del prompt, ventana de contexto, presupuesto de tokens, lógica de reintentos, captura de salida. Lo escribes en una tarde. El harness de un GRAFO hace todo esto y más: enrutamiento de mensajes entre nodos, aislamiento de fallas de un nodo (si un nodo falla, no puede derribar todo el grafo), consistencia del estado entre nodos (lo que un nodo sabe debe coincidir con lo que espera el siguiente), creación dinámica de nodos (el grafo decide en tiempo de ejecución que necesita un nodo más), y observabilidad del grafo entero.

Observabilidad, aquí, es la capacidad de responder: qué nodos se ejecutaron, en qué orden y con qué latencia (tiempo de ejecución). En un script de un solo bucle, esa pregunta es trivial — se ejecutó una vez, se ejecutó de nuevo, se detuvo. En un grafo con nodos paralelos y enrutamiento condicional, sin instrumentación simplemente no sabes qué pasó. Es exactamente por eso que los frameworks de orquestación (herramientas que coordinan varios agentes/nodos) ganan terreno cuando la conversación pasa de bucle a grafo: resuelven este conjunto de problemas de runtime distribuido — un sistema en el que varias partes se ejecutan de forma coordinada y cada una puede fallar independientemente de las otras, en lugar de dejar que cada equipo reinvente esto manualmente.

Qué observar: compara el tamaño de las dos cajas. La caja de la izquierda tiene 4 responsabilidades y cabe en una tarde de trabajo. La caja de la derecha tiene 5 responsabilidades — y cada una de ellas, por sí sola, es un proyecto de ingeniería (el aislamiento de fallas, por ejemplo, es todo un tema de los sistemas distribuidos clásicos). Eso explica por qué "solo agregar un agente más" nunca es "solo".

Meu agente faz <o que ele faz de errado> quando eu peco <a tarefa>.

Antes de sugerir qualquer mudanca, analise as cinco camadas NESTA ORDEM
e descarte cada uma explicitamente antes de passar pra proxima:

1. PROMPT — a instrucao em si tem ambiguidade real, ou ja e clara?
2. CONTEXTO — o que o agente "ve" no momento de agir esta limpo,
   ou tem coisa irrelevante competindo com o que importa?
3. HARNESS — ele tem a ferramenta certa, com a permissao certa,
   e a saida dela volta pra ele de um jeito util?
4. LOOP — existe condicao de parada e verificador? Ele sabe quando
   "terminou" de verdade, ou so para de tentar?
5. GRAFO — se ha mais de um agente/etapa, o problema esta na
   ligacao entre eles (roteamento, estado que vaza) e nao dentro
   de um unico no?

Para cada camada, diga "descartada" ou "e aqui" com uma frase de
justificativa. So recomende uma mudanca depois de passar pelas cinco.