Lição 1: Além da memória, existe o estado

Objetivos de aprendizado:

• Distinguir em uma frase “memória” (o contexto que você entrega ao modelo) de “estado de execução” (a cena em andamento que o harness está segurando), e dar um exemplo de cada
• Nomear pelo menos três motivos concretos para “uma queda é especialmente fatal para uma tarefa longa”, e dizer para qual parte da execução cada um aponta
• Dada uma lista de coisas que um harness em execução está manejando, decidir se cada uma é memória, estado de execução ou saída em disco — e se ela sobrevive ao processo ser morto

Pré-requisitos: Conclua os cursos anteriores desta série e entenda o loop de harness dirigido pelo stop_reason de "Agent Harness Fundamentals: Loops and Control" e o gerenciamento de contexto de "Context Engineering: Spending Finite Attention Where It Counts" | Próxima: Lição 2 >>

Turno 23, e o processo é morto

Imagine o harness que você escreveu em "Agent Harness Fundamentals: Loops and Control" rodando uma tarefa longa que leva 40 turnos: ler um lote de arquivos, analisá-los um a um e ir acrescentando conclusões a um relatório conforme avança. No turno 23, o processo é morto — talvez uma atualização de deploy, talvez o servidor tenha perdido energia, talvez você tenha errado o dedo no Ctrl+C.

Você confere o disco: os arquivos de relatório dos primeiros 22 turnos estão todos lá; o NOTES.md (aquele resumo de progresso da tarefa que você montou em "Context Engineering: Spending Finite Attention Where It Counts") ainda registra “até qual arquivo eu analisei, e qual foi a conclusão”. Parece que não se perdeu muita coisa — é só reiniciar o processo e continuar de onde parou.

Mas assim que você reinicia, descobre que o array messages dentro de runAgent está vazio — ele tem que ser reconstruído a partir de [{ role: "user", content: userInput }]. O contador turns voltou a zero. tokensUsed também voltou a zero. E se a queda pegou o turno 23 bem no meio entre “o modelo indicou uma ferramenta” e “o resultado da ferramenta foi devolvido para messages”, aquela chamada de ferramenta — quer tivesse acabado de começar a rodar, quer já tivesse terminado — também não deixa rastro nenhum.

A tarefa não retoma do turno 23; ela recomeça do turno 1. Os arquivos em disco estão todos lá, mas o registro do próprio harness sobre “até onde eu cheguei” não deixou nada para trás.

O que é memória, o que é estado

Antes que este curso possa ensinar o que veio ensinar, ele precisa traçar uma linha contra um conceito que é fácil de embaralhar.

Memória é o contexto que você entrega ao modelo — o Curso 5, "Agent Memory and State", cobre como persisti-la entre sessões, e o Curso 8, "Context Engineering: Spending Finite Attention Where It Counts", cobre exatamente o que você entrega ao modelo para olhar a cada turno. Ela responde à pergunta “o que o modelo já viu?”. O NOTES.md é um dos veículos da memória: ele já está gravado em disco, e o turno seguinte ou a sessão seguinte pode lê-lo de volta e jogá-lo no prompt.

Estado de execução é a cena em andamento que o próprio processo do harness está segurando — o array messages, contadores como turns e tokensUsed, a chamada de ferramenta que ainda não foi registrada. Ele responde à pergunta “o harness lembra até onde chegou?”.

A diferença essencial entre os dois não é “qual é o conteúdo”, e sim “onde ele vive agora”. A memória pode já estar em disco (o NOTES.md fica no sistema de arquivos, e o processo viver ou morrer não muda o fato de que ele continua lá); o estado de execução, por padrão, vive apenas na memória do processo — aquilo que a linha let messages = [...] cria é liberado junto com a memória no instante em que o processo termina, a menos que alguém o grave deliberadamente em disco. Nada da seção anterior — messages, turns, tokensUsed, a chamada de ferramenta órfã — é gravado em disco por conta própria.

Este state é exatamente o que este curso vai te ensinar a transformar em algo que pode ser gravado em disco e restaurado.

Por que isso é decisivo para tarefas longas

Primeiro, faça as contas: "Agents can run for long periods of time, maintaining state across many tool calls."¹ (Agentes podem rodar por longos períodos de tempo, mantendo estado ao longo de muitas chamadas de ferramenta.) É exatamente por isso que o array messages no turno 23 não para de crescer. Mas isso também significa que "Agents are stateful and errors compound."¹ (Agentes são stateful e os erros se acumulam.): quanto mais estado se empilha, no instante em que algo na cadeia dá errado o custo não é linear, ele se soma.

Some mais uma: "Without effective mitigations, minor system failures can be catastrophic for agents."¹ (Sem mitigações eficazes, falhas menores de sistema podem ser catastróficas para agentes.) Pôr “menor” e “catastrófica” lado a lado descreve exatamente a situação do turno 23 — o processo ser morto é, por si só, um evento de operação corriqueiro, mas ele apaga 22 turnos de estado de execução de uma só vez, e é isso que amplifica o custo.

Depois de um erro, "When errors occur, we can't just restart from the beginning: restarts are expensive and frustrating for users."¹ (Quando erros acontecem, não podemos simplesmente recomeçar do início: reinícios são caros e frustrantes para os usuários.) O que você quer construir, então, é um sistema em que, "Instead, we built systems that can resume from where the agent was when the errors occurred."¹ (Em vez disso, construímos sistemas que conseguem retomar de onde o agente estava quando os erros aconteceram.) — e é por isso que “além da memória, existe o estado” não é uma distinção acadêmica, e sim a base de saber se uma tarefa longa consegue sobreviver a uma interrupção.

Quanto mais longa a tarefa, mais pesada essa conta: "The LLM will potentially operate for many turns, and you must have some level of trust in its decision-making."² (O LLM potencialmente vai operar por muitos turnos, e você precisa ter algum nível de confiança na tomada de decisão dele.), e "The autonomous nature of agents means higher costs, and the potential for compounding errors."² (A natureza autônoma dos agentes significa custos maiores e o potencial de erros que se acumulam.). Quanto mais turnos ele roda, mais espesso o estado de execução que acumula, e mais uma única interrupção pode apagar.

Quedas não são raras

Aquele “o processo foi morto” no turno 23 soa como um acidente de baixa probabilidade, mas para uma tarefa longa que roda dezenas de turnos, ser interrompida no meio do caminho não é nada incomum. Até a mais rotineira das atualizações de deploy pode colidir com um agente em execução — e é por isso que as equipes deliberadamente "use rainbow deployments to avoid disrupting running agents, by gradually shifting traffic from old to new versions"¹ (usam rainbow deployments para evitar interromper agentes em execução, deslocando gradualmente o tráfego das versões antigas para as novas), pela razão de que "whenever we deploy updates, agents might be anywhere in their process."¹ (sempre que implantamos atualizações, os agentes podem estar em qualquer ponto do seu processo.).

Em outras palavras, até quem toca a operação trata “o agente pode ser interrompido a qualquer momento” como algo que vai acontecer, e projeta mecanismos justamente para desviar disso. O seu harness não tem motivo nenhum para supor que terá mais sorte.

A cura, em prévia: o roteiro deste curso

O estado de execução perdido no turno 23 tem uma correção em cinco etapas, que é também a ordem das cinco lições seguintes:

1. Checkpoints (Lição 2) — serializar periodicamente para um arquivo de checkpoint em disco o estado de execução, como messages, turns, tokensUsed e a chamada de ferramenta órfã.
2. Retomar de um checkpoint (Lição 3) — depois que o processo reinicia, ler esse estado de volta do arquivo de checkpoint, reconstruir messages e deixar o loop continuar de onde quebrou, em vez de recomeçar do turno 1.
3. Efeitos colaterais e idempotência (Lição 4) — a parte mais difícil de retomar não é “o estado sumiu”, é “algumas chamadas de ferramenta podem de fato já ter rodado”: quais ferramentas é seguro reexecutar, e quais precisam ser protegidas contra rodar duas vezes.
4. Rebobinar e bifurcar (Lição 5) — checkpoints não servem só para recuperação de desastre; eles também deixam você rebobinar para uma cena anterior e tentar de novo, ou bifurcar outra tentativa a partir de algum nó.
5. Mão na massa (Lição 6) — pegar o maquinário das lições anteriores, encaixá-lo no harness de "Agent Harness Fundamentals: Loops and Control" e você mesmo levar uma tarefa longa pelo caminho “morta no meio, reiniciada, executada até o fim”.

Um roteiro comunitário de código aberto construído em torno de “engenharia de harness” resume isso em uma linha: "Checkpoint state every node so you can resume, rewind, fork."³ (Faça checkpoint do estado em cada nó para que você possa retomar, rebobinar, bifurcar.) — isso é apenas um enquadramento, vindo de um documento comunitário, sobre o que o componente de persistência responde, não uma especificação que este curso copia literalmente, mas a ordem que ele aponta bate com as cinco etapas acima.

Proporção: nem toda tarefa precisa disso

Nem todo agente tem que carregar o maquinário de checkpoints. Sobre acrescentar complexidade, "you should consider adding complexity only when it demonstrably improves outcomes."² (você deveria considerar acrescentar complexidade apenas quando isso melhora comprovadamente os resultados.) — uma tarefa que se encerra em alguns turnos de chamada de ferramenta tem só um punhado de entradas em messages, e se o processo morrer você simplesmente roda de novo; o custo é perguntar mais uma vez, o que não justifica projetar um mecanismo inteiro de gravar e restaurar.

O que de fato precisa do maquinário deste curso é um cenário como o do turno 23 lá em cima: uma tarefa que roda dezenas de turnos, pode levar de minutos a horas e acumula pelo caminho uma pilha grande de estado de execução não persistido. Para decidir se você traz checkpoints para dentro, faça a si mesmo uma pergunta primeiro: se ela fosse morta agora, você aguentaria o custo de reexecutá-la? Se não aguentaria, é aí que entram as próximas lições.

Recapitulação

• Agentes podem rodar por longos períodos, mantendo estado ao longo de muitas chamadas de ferramenta, e justamente por isso são stateful e os erros se acumulam¹ — quanto mais estado se empilha, mais uma única falha pode apagar.
• Sem mitigações eficazes, uma falha menor de sistema pode ser catastrófica para um agente¹; depois de um erro você não pode recomeçar do início, porque reinícios são caros e frustrantes para os usuários, então você constrói sistemas que retomam de onde o erro aconteceu¹.
• Quedas não são raras — até uma atualização rotineira de deploy pede rainbow deployments justamente para evitar interromper agentes em execução, porque, na hora de implantar, um agente pode estar em qualquer ponto do seu processo¹.
• A operação autônoma carrega inerentemente custos maiores e o risco de erros que se acumulam²; quanto mais longa a tarefa, mais pesada essa conta, e mais ela precisa de um mecanismo que sobreviva a uma interrupção.
• Nem toda tarefa tem que carregar esse maquinário — acrescente complexidade apenas quando isso melhora comprovadamente os resultados², e para uma tarefa que se encerra em alguns turnos o custo de simplesmente reexecutá-la costuma ser aceitável.
• Memória (o contexto entregue ao modelo) e estado de execução (a cena em andamento que o harness segura) são duas coisas diferentes: a memória pode já estar persistida, o estado de execução por padrão vive apenas na memória do processo — e as próximas lições são sobre transformar também esse estado de execução em algo que pode ser gravado em disco e restaurado.

>> Lição 2: Checkpoints: gravando a cena de execução em disco