Handoff: uma memória simples para agentes que não precisam lembrar de tudo

Existe uma tentação comum quando começamos a trabalhar com agentes de IA: tentar fazer com que eles lembrem de tudo.

A conversa inteira. Todas as decisões. Todos os detalhes. Tudo o que aconteceu ontem.

Na maior parte dos trabalhos, não preciso reconstruir cada passo. Preciso saber qual era o objetivo, onde o trabalho parou e o que fazer em seguida.

É aí que entra o handoff.

Passar o bastão

Handoff é a passagem de um trabalho entre turnos. Uma pessoa termina sua parte e outra assume. Antes de sair, ela deixa registrado:

o que foi feito;
o que ficou pendente;
quais decisões foram tomadas;
onde estão os arquivos;
quais verificações já foram executadas;
qual deve ser o próximo passo.

Com agentes, funciona da mesma forma.

Em vez de depender indefinidamente de uma sessão extensa, encerramos num ponto coerente e criamos um documento curto de passagem.

sessão 1
   ↓
handoff.md
   ↓
sessão 2

A próxima sessão não precisa reconstruir toda a história. Precisa de contexto suficiente para continuar e de referências que permitam verificar esse contexto no projeto.

Sessões crescem

Enquanto trabalhamos com um agente, a sessão acumula prompts, respostas, arquivos, decisões, tentativas e correções. Esse contexto tem custo e limites.

Alguns sistemas conseguem compactá-lo. Na Responses API da OpenAI, por exemplo, a compactação carrega para a próxima janela um estado reduzido com informações dos turnos anteriores. A própria documentação diz que esse estado é opaco e não foi feito para leitura humana.

Isso ajuda a manter uma interação longa, mas resolve um problema diferente. A compactação preserva contexto para o sistema continuar. O handoff registra, de forma legível e deliberada, o que a próxima pessoa ou sessão precisa conferir.

Foi por isso que passei a preferir uma prática explícita:

Quando chego a um ponto de equilíbrio, faço o handoff.

Registro o estado atual e posso começar outra sessão sem tratar a conversa anterior como a única fonte de continuidade.

Um handoff pode ser simples

Não é necessária uma plataforma especial. Um arquivo Markdown já resolve bastante:

# Handoff

Atualizado em: 2026-10-01

## Objetivo
Gerar a nova versão da proposta comercial.

## O que foi feito
- dados técnicos consolidados;
- template escolhido;
- primeira versão do HTML gerada.

## Decisões
- usar o template B;
- manter valores na moeda original;
- não incluir opcionais ainda.

## Verificações
- HTML aberto e revisado no navegador;
- valores comparados com dados/equalizacao.md.

## Pendências
- validar prazo;
- revisar condições comerciais;
- gerar PDF.

## Próximo passo
Confirmar o prazo com a área comercial antes de gerar o PDF.

## Arquivos
- output/proposta-v03.html
- dados/equalizacao.md

No dia seguinte, outra sessão lê esse arquivo, confere se os caminhos ainda existem e continua.

Uma data de atualização ajuda a detectar um handoff antigo. Em projetos com mudanças paralelas, também pode ser útil registrar a branch ou o commit usado como referência. O documento continua curto, mas deixa de depender de um estado implícito do repositório.

Handoff não é memória completa

Essa distinção é importante. O handoff não tenta guardar tudo. Ele preserva o necessário para continuidade.

É a diferença entre entregar para alguém centenas de páginas de conversa ou dizer:

Cheguei até aqui.
Estas decisões já foram tomadas.
Estes são os arquivos.
Falta fazer isto.

Para muitos trabalhos, isso é suficiente. Não é suficiente quando precisamos reconstruir toda a sequência de mudanças, demonstrar uma aprovação formal ou auditar cada ação. Nesses casos, o handoff deve apontar para o histórico do Git, para registros de decisão, chamados, logs ou outros artefatos apropriados.

O handoff.md descreve o estado presente. O versionamento preserva os checkpoints que nos trouxeram até ele.

O conhecimento permanente fica em outro lugar

O handoff também não substitui a base do agente.

Se durante o trabalho descobrimos uma regra permanente, ela provavelmente deveria ir para o AGENTS.md. Se descobrimos um procedimento reutilizável, talvez deva virar uma skill. Se produzimos um bom exemplo, ele pode permanecer entre os artefatos de referência.

Uma separação útil é:

AGENTS.md
→ como trabalhar

skills/
→ como executar capacidades específicas

knowledge/
→ o que precisa ser conhecido

handoff.md
→ onde paramos

O handoff registra o estado do trabalho, não todo o conhecimento do agente. Se uma regra continuar válida depois que a tarefa terminar, escondê-la no handoff torna essa regra difícil de reencontrar.

Manter o handoff confiável

Um handoff pode falhar mesmo estando bem escrito. Isso acontece quando ele fica desatualizado, menciona arquivos que não existem mais ou declara como concluída uma verificação que nunca foi executada.

Antes de encerrar a sessão, eu conferiria quatro coisas:

os caminhos citados existem;
decisões estão separadas de sugestões ainda não aprovadas;
verificações executadas estão separadas das que ainda faltam;
o próximo passo pode ser iniciado sem reler a conversa inteira.

Também não transformaria o handoff.md em um diário acumulativo. Quando uma pendência for resolvida, o estado deve ser atualizado. Se o histórico for importante, ele já tem lugares melhores para viver.

Isso permite descartar sessões

Quando existe um handoff confiável, a sessão deixa de ser um ativo precioso.

Podemos encerrá-la, abrir outra, trocar de modelo, retomar o trabalho amanhã ou passar a tarefa para outra pessoa. Essa portabilidade tem limites: modelos e ferramentas diferentes podem interpretar instruções de maneiras diferentes. Ainda assim, um estado legível e verificável reduz a dependência de uma conversa específica.

Essa prática complementa a ideia de que todo agente acorda com amnésia. Não precisamos impedir a amnésia. Precisamos deixar o projeto preparado para continuar apesar dela.

Uma memória pequena pode ser melhor

Existem projetos que exigem mecanismos de memória mais sofisticados. Um agente que acompanha relacionamentos durante meses, atende muitas pessoas ou precisa recuperar milhares de fatos não deveria depender apenas de um arquivo Markdown.

Para trabalhos com começo, estado atual e próximo passo reconhecíveis, eu começaria pela solução mais simples:

persistir o que importa e passar o bastão.

O objetivo não é fazer o agente lembrar de tudo. É garantir que ele saiba onde estamos e para onde devemos ir.

Às vezes, uma boa memória não é aquela que guarda tudo. É aquela que registra o necessário e deixa claro o que pode ser esquecido.