Lição 1: A janela de contexto é toda a memória que um agente tem
Objetivos de aprendizado:
- Explicar por que "o agente lembra da nossa conversa anterior" é uma ilusão
- Nomear o que conta para a janela de contexto de uma única requisição e o que não conta
- Explicar o que é context rot, e por que uma janela maior não é automaticamente melhor de usar
- Julgar se uma chamada de API é sem estado, e o que isso significa para a memória
Pré-requisitos: os quatro primeiros cursos desta série, incluindo o protocolo de ida e volta das chamadas de ferramenta de Tool calling de agentes: fazendo agentes agirem de verdade | Próxima: Lição 2 >>
Uma conversa que parece lembrar
Você está conversando com um agente de suporte ao cliente:
No segundo turno o agente claramente "lembra" que seu nome é Sarah e lembra que você perguntou sobre o ORD-2026-8842. Parece que ele arquivou esses detalhes em algum lugar e consegue recuperá-los na próxima vez.
A verdade é bem mais simples. A cada requisição, o seu código reempacota cada mensagem desde o início da conversa até agora e envia ao modelo como está.1 O modelo não está vendo "eu lembro que seu nome é Sarah" — ele está relendo "o usuário disse: meu nome é Sarah" do zero, toda e cada vez. Cada frase do turno anterior, cada chamada de ferramenta, tem de ser colocada na requisição deste turno pelo seu próprio código. O modelo não armazena nada por conta própria.
A chamada de API é sem estado
Colocando de forma ainda mais direta: entre uma chamada e a próxima, nada é discretamente guardado para você no servidor. Uma vez que esta requisição é processada, esses tokens somem da visão do modelo. Se a próxima requisição não carregar nada, o modelo vê uma folha em branco — ele nem sabe o seu nome.
A razão de parecer memória é que o aplicativo host faz o trabalho braçal por você: ele reenvia o array completo de mensagens do histórico. Isso não é uma capacidade do modelo; é um array no seu código que continua crescendo. Essa propriedade tem um nome — sem estado (stateless). Nas palavras da documentação oficial: "The Messages API is stateless, which means that you always send the full conversational history to the API."1 (A Messages API é sem estado, o que significa que você sempre envia todo o histórico da conversa para a API.) O servidor não mantém nenhum estado privado por sessão entre requisições; toda "memória" tem de ser carregada e reenviada pelo próprio cliente.
O que de fato está na janela de contexto
Tudo o que o modelo consegue ver mora em um contêiner chamado janela de contexto. A documentação é explícita de que tudo em uma requisição conta: "Everything in the request counts toward the context window: the system prompt, every message in messages (including tool results, images, and documents), and your tool definitions. The output Claude generates for the turn, including its extended thinking, counts too."2 (Tudo na requisição conta para a janela de contexto: o system prompt, cada mensagem em messages (incluindo resultados de ferramentas, imagens e documentos) e as suas definições de ferramentas. A saída que o Claude gera no turno, incluindo o raciocínio estendido, também conta.)
Nesta requisição, system, tools e todas as três mensagens no array messages contam para a janela de contexto. Uma vez que a resposta do modelo é gerada, esses tokens de saída também contam para o uso da janela deste mesmo turno. A resposta traz um campo usage que informa quantos tokens de entrada e de saída o turno de fato consumiu: "Every response reports what the request consumed in its usage field."2 (Toda resposta relata o que a requisição consumiu no seu campo usage.)
Qualquer coisa não empacotada nesta requisição — digamos, um registro de pedido parado em um banco de dados que nenhuma ferramenta consultou ainda — não faz parte da janela de contexto. O modelo não consegue vê-la e não pode saber que ela existe do nada. É por isso que "memória" tem de ser ativamente carregada para dentro desta requisição por algum mecanismo; ela não é automaticamente alcançável.
A janela apodrece — maior não é melhor
Há um teto para quanto a janela guarda — a capacidade varia por modelo, e o número oficial chega até 1 milhão de tokens: "The context window (up to 1M tokens, depending on the model) holds the conversation history plus the new output Claude generates."2 (A janela de contexto (até 1M de tokens, dependendo do modelo) guarda o histórico da conversa mais a nova saída que o Claude gera.) Mas isso não significa que você deva enchê-la o máximo possível. A documentação nomeia um fenômeno específico, context rot: "As token count grows, accuracy and recall degrade, a phenomenon known as context rot. This makes curating what's in context just as important as how much space is available."2 (Conforme a contagem de tokens cresce, a acurácia e a recuperação se degradam, um fenômeno conhecido como context rot. Isso torna curar o que está no contexto tão importante quanto o espaço que há disponível.) Em outras palavras, quanto mais conteúdo a janela guarda e mais desorganizada ela fica, pior o modelo se torna em extrair dela a resposta certa — o que faz o que você coloca no contexto importar tanto quanto o espaço que sobra.2
Isso molda o design de memória diretamente: despejar todo o histórico no contexto não é de graça (enche a capacidade da janela), e também não é sem custo (faz o modelo trabalhar mais para achar a única frase que de fato é relevante agora, enterrada em uma pilha de informação obsoleta). A Lição 2 cobre como lidar com esse acúmulo na prática — como truncar o histórico, como resumi-lo, em vez de deixá-lo crescer sem limite.
A palavra "memória" é, na verdade, uma metáfora
De volta àquela conversa de suporte do início. Quando dizemos "o agente lembra que seu nome é Sarah", a forma precisa de colocar é: o seu código reenviou o histórico completo — aquele contendo "meu nome é Sarah" — ao modelo como está, mais uma vez, e o modelo o releu dentro desta requisição. Sem armazenamento, sem recuperação, apenas um reenvio.
Isso não é implicância com detalhes. Entender que "memória é uma ilusão produzida pelo reenvio" molda diretamente como você projeta um agente que de fato "lembra":
- Se o array de histórico cresce sem limite, a janela enche cedo ou tarde, e você ainda pega context rot por cima — o problema que a Lição 2 resolve.
- Se alguma informação precisa persistir por múltiplas sessões (não só dentro desta conversa), você não pode contar com enfiá-la no array messages; ela tem de ser escrita em algum lugar externo — a memória externa que a Lição 3 cobre.
- Se o agente precisa saber "quão longe eu já cheguei" no meio de uma tarefa, esse progresso também tem de ser estado estruturado visível na janela de contexto, não algo que o modelo adivinha — o assunto da Lição 4.
Os três fios são corolários diferentes do mesmo fato: o modelo sabe apenas o que está na janela; o que não está na janela não existe no que diz respeito ao modelo.
Recapitulação
- "O agente lembra da nossa conversa anterior" é uma ilusão: a verdade é que o aplicativo host reempacota o histórico completo em cada requisição, e o modelo não armazena nada por conta própria1
- A chamada de API é sem estado; o servidor não mantém nenhum estado privado por sessão entre requisições, então toda "memória" tem de ser ativamente carregada pelo cliente1
- A janela de contexto guarda tudo o que esta requisição de fato carrega: o system prompt, cada mensagem em
messages (incluindo resultados de ferramentas, imagens, documentos), as definições de ferramentas e a própria saída do modelo no turno2
- A janela tem um teto de tamanho, e maior não é automaticamente melhor de usar — context rot significa que quanto mais tokens você empilha, mais a acurácia e a recuperação se degradam2
- Captar que "o modelo sabe apenas o que está na janela" leva direto aos problemas que as próximas três lições resolvem: como gerenciar o histórico, como externalizar a memória, como estruturar o estado
Lição 2: Gerenciando o histórico da conversa: acrescentar, truncar, resumir >>