Agent Mentor Learn
Memória e Estado de Agente · Lição 4 de 6

Lição 4: Estado estruturado: como um agente lembra em que ponto uma tarefa está

Objetivos de aprendizado:

  • Explicar por que enterrar o progresso de uma tarefa em prosa conversacional é pouco confiável, e por que ele precisa se tornar estado estruturado
  • Enunciar o ciclo de vida completo pelo qual um todo passa, da criação à remoção
  • Distinguir o custo de recomeçar do zero versus retomar de onde o trabalho foi interrompido
  • Decidir se um pedaço do estado de uma tarefa deve viver no histórico da sessão ou ser gravado em um checkpoint separado

Pré-requisitos: Conclua a Lição 3 e entenda os dois modos de memória externa | Anterior: Lição 3 << | Próxima: Lição 5 >>

Depois de reiniciar o processo, o agente ainda sabe em qual etapa parou

Um agente está executando uma tarefa de várias etapas: refatorar um módulo, que se divide em quatro etapas — "atualizar as definições de tipo", "atualizar os pontos de chamada", "rodar os testes", "atualizar a documentação". Ele acabou de terminar a segunda etapa quando o processo é interrompido por um reinício inesperado. Quando volta a subir, está diante da mesma descrição de tarefa. Ele deve refazer a etapa um do zero, ou sabe que já concluiu as duas primeiras etapas e pode continuar direto da etapa três?

A resposta se resume a uma coisa: se o progresso da tarefa foi registrado como estado estruturado, em vez de espalhado por uma pilha de prosa conversacional. Se "as definições de tipo já foram atualizadas" for apenas uma linha de linguagem natural em uma das respostas anteriores do modelo, enterrada entre dezenas de mensagens, o código hospedeiro não tem como extrair de forma confiável o fato concreto "em qual etapa estamos". Mas se esse progresso for expresso como uma lista de todos com campos fixos — onde cada tarefa carrega um marcador de status explícito — o código hospedeiro pode lê-lo diretamente: as etapas um e dois estão completed, a etapa três não começou.

Essa é a questão central que esta lição aborda. As Lições 1, 2 e 3 trataram todas de como gerenciar conteúdo — histórico de conversa, arquivos de memória. Esta lição trata de como expressar progresso, para que um agente ou seu aplicativo host, depois de uma interrupção, saiba exatamente até onde a tarefa chegou.

O ciclo de vida do todo: criado, ativado, concluído, removido

Tome a ferramenta de acompanhamento de tarefas do Claude Code como exemplo. A documentação oficial descreve o ciclo de vida completo pelo qual um todo passa durante a execução — quatro etapas:1

  1. Criado: o Claude adiciona o todo como pending quando identifica uma tarefa
  2. Ativado: o Claude define o todo como in_progress quando começa o trabalho
  3. Concluído: o Claude o marca como completed quando a tarefa termina com sucesso
  4. Removido: o Claude exclui um todo de que não precisa mais definindo status: "deleted" em uma chamada TaskUpdate1

Essas quatro etapas não são o vago "terminei" ou "estou trabalhando nisso" da linguagem natural. São quatro valores de status explícitos: pending, in_progress, completed, e deleted para remoção. Toda mudança de status acontece por meio de uma chamada de ferramenta explícita, não pelo modelo soltando um comentário no texto da resposta.

A documentação também detalha como esse mecanismo de fato aparece na conversa: "In a session that has the task-tracking tools, Claude keeps a written todo list, updating each item's status as it works. You see each change in the message stream as a structured tool call."1 (Em uma sessão que tem as ferramentas de acompanhamento de tarefas, o Claude mantém uma lista de todos escrita, atualizando o status de cada item conforme trabalha. Você vê cada mudança no fluxo de mensagens como uma chamada de ferramenta estruturada.) Essa frase fixa a distinção central: o progresso não é passivamente "refletido" na conversa, ele é ativamente escrito como uma chamada de ferramenta que pode ser identificada e analisada por si só. Essa é a verdadeira diferença entre estado estruturado e uma descrição de progresso espalhada pela prosa.

Checkpoints: tornar a recuperação algo diferente de recomeçar

Uma vez que você tem uma lista de todos estruturada, a próxima pergunta é: onde a própria lista vive? Se ela existir apenas no histórico de conversa desta sessão, então no momento em que a sessão realmente terminar (não uma breve interrupção, mas um fechamento completo, como a ideia de "quando a sessão termina, tudo o que está na janela some" da Lição 3), o registro de progresso desaparece junto. No fundo, a API é sem estado: "The Messages API is stateless, which means that you always send the full conversational history to the API."2 (A Messages API é sem estado, o que significa que você sempre envia todo o histórico da conversa para a API.)

É esse o problema que os checkpoints resolvem: gravar o estado de uma tarefa em algum momento no tempo — quais etapas estão prontas, qual etapa é a atual, quais etapas restam — em um pedaço de dado, e persisti-lo em algum lugar fora do tempo de vida da sessão. Os checkpoints usam o mesmo mecanismo subjacente da memória externa da Lição 3 (escrever um arquivo, lê-lo de volta depois); a diferença é que um checkpoint não armazena "conhecimento que vale a pena lembrar", ele armazena "até onde a tarefa chegou" — o tipo de estado que você pode usar diretamente para retomar a execução.

Com os checkpoints em vigor, a recuperabilidade finalmente se sustenta: depois de um reinício de processo, o agente não precisa adivinhar "onde eu estava". Ele lê o checkpoint mais recente, vê "as etapas um e dois estão completed, a etapa três está in_progress", e continua a partir da etapa três em vez de refazer as etapas um e dois.

A comparação de custo aqui é concreta. Na tarefa de refatoração, a etapa "atualizar as definições de tipo", se for idempotente (executá-la de novo produz o mesmo resultado), só custa tempo desperdiçado quando refeita do zero. Mas se alguma etapa for uma operação não idempotente como "inserir um registro de migração no banco de dados", recomeçar poderia inserir dois registros duplicados e até corromper dados. O que um checkpoint salva não é só tempo — é o risco de reexecutar por acidente esse tipo de operação não idempotente.

O estado estruturado existe para tornar a interrupção sobrevivível

De volta ao cenário que abriu esta lição: depois de um reinício de processo, o agente deve recomeçar ou retomar de onde foi interrompido? Agora podemos responder com clareza — depende de duas coisas terem sido feitas. O progresso da tarefa foi expresso como estado estruturado (em vez de espalhado pela prosa conversacional), e esse estado foi gravado em um checkpoint (em vez de viver apenas no histórico desta única sessão)? Você precisa dos dois. Com estado estruturado mas sem checkpoint, o estado ainda desaparece quando a sessão termina; com um checkpoint mas sem estado estruturado, o que foi gravado no checkpoint é em si linguagem natural vaga, e lê-lo de volta ainda não vai lhe dizer de forma confiável em qual etapa a tarefa chegou.

Esta lição foi sobre como expressar e preservar o progresso. A próxima lição se volta para outra questão que importa tanto quanto: será que esse estado e essa memória preservados poderiam se tornar alvo de atacantes — o que acontece se um atacante conseguir gravar conteúdo em um checkpoint ou em um arquivo de memória?

Recapitulação

  • O progresso de uma tarefa só pode ser lido de forma confiável pelo código hospedeiro depois que se torna estado estruturado; uma descrição de progresso espalhada por respostas em linguagem natural não pode ser analisada de forma estável em "em qual etapa estamos agora"
  • O ciclo de vida completo de um todo tem quatro etapas — criado (pending), ativado (in_progress), concluído (completed), removido (deleted) — e cada etapa acontece por meio de uma chamada de ferramenta estruturada explícita que pode ser observada no fluxo de mensagens
  • Estruturado e persistente são duas coisas diferentes: estruturado resolve "um programa consegue lê-lo", um checkpoint resolve "o estado ainda está lá depois de um reinício de processo ou do fim de uma sessão" — você precisa dos dois
  • Um checkpoint grava o estado de uma tarefa em um momento no tempo em algum lugar fora do tempo de vida da sessão, transformando a recuperação em "continuar de onde foi interrompido" em vez de "recomeçar", e evitando especialmente a reexecução acidental de operações não idempotentes
  • O estado estruturado, assim como a memória externa, se torna seu próprio alvo de ataque uma vez persistido — o tema da próxima lição; quanto mais você preserva, mais limites você tem que manter

>> Lição 5: Os limites e a segurança da memória

Footnotes

  1. Track todos — https://code.claude.com/docs/en/agent-sdk/todo-tracking ↩ ↩2 ↩3

  2. Using the Messages API — https://platform.claude.com/docs/en/build-with-claude/working-with-messages ↩

Exercícios

01

Um agente recebe a tarefa "adicionar testes unitários ao projeto" e a divide em três todos: "escrever os casos de teste", "rodar a suíte de testes", "corrigir os casos que falham". Seguindo a ordem cronológica abaixo, anote em qual estado do ciclo de vida (pending / in_progress / completed / deleted) cada todo deve estar em cada momento.

Nível 1: Rotule o estado do ciclo de vida em uma única execução de tarefa
  1. A tarefa acabou de ser decomposta; nenhum dos três começou.
  2. O agente começa a escrever os casos de teste.
  3. Os casos de teste estão escritos; o agente começa a rodar a suíte de testes.
  4. Rodar os testes revela dois casos que falham (caso A e caso B). O agente refina "corrigir os casos que falham" em dois novos todos, "corrigir o caso A" e "corrigir o caso B", e começa a corrigir o caso A.
  5. Ao corrigir o caso A, descobre-se que o caso B era na verdade o próprio teste escrito de forma errada e não precisa de mudança nenhuma, então "corrigir o caso B" é removido.
Critérios de conclusão · marcado localmente
02

Uma equipe projetou esta lógica de execução: o progresso da tarefa do agente aparece apenas no resumo em linguagem natural de cada uma de suas respostas, algo como "até agora as duas primeiras etapas estão prontas, atualmente cuidando da terceira". Esse resumo existe apenas no histórico de mensagens da sessão atual; a equipe não grava nenhum arquivo de checkpoint. O sistema ocasionalmente reinicia o processo por limites de recurso, e depois de um reinício a mesma tarefa é retomada.

Nível 2: Diagnostique um design de tarefa irrecuperável

Aponte os dois problemas neste design (um sobre "se o estado é estruturado", outro sobre "se o estado é persistido") e dê a direção de correção correspondente para cada um.

Critérios de conclusão · marcado localmente