🪜 As cinco camadas

A primeira camada e a que todo mundo conhece: o prompt, o texto que voce escreve pedindo alguma coisa pro modelo. E tambem a camada onde a maioria das pessoas empaca — quando o agente faz besteira, o reflexo e "deixa eu reescrever o prompt". As vezes funciona. Na maioria das vezes, so adia o problema.

Melhorar prompt tem retorno decrescente rapido: as primeiras melhorias (ser especifico, dar exemplo, pedir formato de saida) resolvem muita coisa. Depois de um certo ponto, adicionar mais instrucao no prompt para de mexer no resultado. Isso e sinal — nao de que voce escreveu mal, mas de que o problema mudou de endereco.

O que olhar: a linha tracejada sobe sem quebrar — cada degrau esta em cima do anterior, nao no lugar dele. O brilho fica so no ultimo degrau, "grafo", que e o horizonte deste modulo. Guarde a ordem: e nela que voce vai diagnosticar onde um agente quebrado esta realmente travado.

A segunda camada e o contexto: tudo que o agente "enxerga" no momento de agir — arquivos abertos, historico da conversa, documentacao anexada, saida de uma ferramenta que ele acabou de rodar. O prompt e o que voce pede; o contexto e o que ele sabe enquanto responde. Sao coisas diferentes, e confundi-las e o erro mais comum depois do prompt.

Todo modelo tem uma janela de contexto limitada. Quando ela enche de coisa irrelevante — logs verbosos, arquivos que ninguem precisa, historico repetido — o modelo comeca a "esquecer" o que importa, mesmo que a instrucao original estivesse perfeita. Contexto errado derruba prompt bom; nao existe prompt bom o suficiente pra compensar uma janela de contexto poluida.

A terceira camada e o harness: a infraestrutura em volta do modelo. Quais ferramentas ele tem (ler arquivo, rodar comando, chamar uma API), com que permissoes, como a saida de cada ferramenta e capturada e devolvida pro modelo, o que acontece quando uma ferramenta falha (retentativa — tentar de novo automaticamente), e quanto orcamento de token a tarefa inteira tem pra gastar.

Prompt diz o que; harness diz com o que. Um agente com prompt perfeito e harness pobre (sem acesso ao arquivo certo, sem permissao pra rodar o comando que resolveria o problema) fica travado do mesmo jeito — e nenhuma reescrita de prompt destrava, porque o problema nunca esteve no texto.

A quarta camada e o loop: quantas vezes o agente tenta e como ele sabe que terminou. Essa e a Trilha 2 inteira condensada — descobrir, planejar, agir, verificar, parar. E a camada onde voce para de escrever prompt e passa a projetar ciclo: nao e mais sobre o que pedir numa unica chamada, e sobre como o sistema se comporta ao longo de varias.

Um agente pode ter prompt otimo, contexto limpo e harness bem montado e ainda falhar — porque ninguem desenhou a condicao de parada, ou porque o verificador (o que decide se o resultado ta bom) esta ausente ou fraco. Nesse ponto, mais prompt nao ajuda: o que falta e desenho de loop.

A quinta camada so faz sentido depois das outras quatro: quantos loops voce tem, e como eles se ligam. Um grafo, aqui, e literalmente varios loops (ou nos sem loop nenhum) conectados por arestas — o pesquisador manda pro escritor, o escritor manda pro revisor, o revisor pode devolver pro escritor. Cada um desses e um no; a rede toda e o grafo.

Subir pra esta camada sem dominar as quatro de baixo multiplica o problema em vez de resolver. Se um loop individual ja nao tem condicao de parada clara, colocar tres desses loops num grafo nao cria tres problemas — cria um problema combinatorio, porque agora cada loop mal desenhado pode contaminar os vizinhos.

O harness de UM loop cabe num script: entrada de prompt, janela de contexto, orcamento de token, logica de retentativa, captura de saida. Voce escreve isso numa tarde. O harness de um GRAFO faz tudo isso e mais: roteamento de mensagem entre nos, isolamento de falha de um no (um no cair nao pode derrubar o grafo inteiro), consistencia de estado entre nos (o que um no sabe tem que bater com o que o proximo espera), criacao dinamica de no (o grafo decide em tempo de execucao que precisa de mais um no), e observabilidade do grafo inteiro.

Observabilidade, aqui, e a capacidade de responder: quais nos rodaram, em que ordem, com que latencia (tempo de execucao). Num script de um loop so, essa pergunta e trivial — rodou uma vez, rodou de novo, parou. Num grafo com nos paralelos e roteamento condicional, sem instrumentacao voce simplesmente nao sabe o que aconteceu. E exatamente por isso que frameworks de orquestracao (ferramentas que coordenam varios agentes/nos) ganham tracao quando a conversa vai de loop pra grafo: eles resolvem esse pacote de problemas de runtime distribuido — um sistema onde varias partes rodam de forma coordenada, cada uma podendo falhar independente das outras — em vez de deixar cada equipe reinventar isso na mao.

O que olhar: compare o tamanho das duas caixas. A caixa da esquerda tem 4 responsabilidades e cabe numa tarde de trabalho. A caixa da direita tem 5 responsabilidades — e cada uma delas, sozinha, e um projeto de engenharia (isolamento de falha, por exemplo, e o assunto inteiro de sistemas distribuidos classicos). Isso explica por que "so adicionar mais um agente" nunca e "so".

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.