Mantenha o contexto útil à medida que a tarefa cresce

Cerca de 22 minutos min de leitura, com 5 exemplos em 10 seções.

Edição 2026.11.2 Exemplos aprovados em 20 de nov de 2026 64 de 64 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.2. Leia o original

Ao final deste capítulo, você será capaz de calcular quanto espaço o prompt de uma execução ainda tem, estimar o tamanho de um prompt quando o harness não consegue contá-lo exatamente, e compactar os passos mais antigos de uma execução sem separar uma chamada de ferramenta do seu resultado.

O modelo lê o prompt inteiro a cada passo: o prompt de sistema, os esquemas das ferramentas, a issue e tudo o que a execução já fez até ali. Esse prompt precisa caber na janela com que o modelo foi carregado, e a resposta precisa caber na mesma janela. Uma execução que continua lendo arquivos acaba ficando sem espaço.

O problema aparece nas execuções mais longas do caso. O agente de manutenção de unitcraft, a biblioteca do capítulo 1, lê arquivos, executa os testes e tenta uma edição, e cada leitura acrescenta um arquivo inteiro ao prompt. No conjunto de tarefas registrado, T-16 atingiu o limite de passos de 16 do capítulo 2, e seu último prompt foi o maior de todos os passos do conjunto. Segundo as contagens registradas, esse último prompt deixou 612 tokens livres, o que significa que as execuções registradas chegaram mais perto da janela justamente ali. O restante do capítulo trata do que o harness deve fazer quando um prompt não cabe.

A janela que o modelo tem

O modelo registrado é o Qwen3-4B-Instruct-2507, executado a partir do arquivo GGUF que o capítulo 1 apresentou. O harness o carrega com um contexto de 8192 tokens, e o manifesto da gravação armazena esse mesmo valor como n_ctx. Trata-se de uma configuração de carregamento escolhida pelo harness. O modelo em si suporta muito mais: o model card dele indica um comprimento de contexto nativo de 262,144 tokens (model card), lido na branch principal (main) do card. Este livro executa o modelo na janela menor, então o número de que o orçamento precisa é o que a execução carrega.

O manifesto também armazena max_tokens, o máximo que a resposta pode ocupar: 1024 tokens. A resposta sai da mesma janela que o prompt, então o prompt fica com o que a resposta deixar.

A aritmética é simples. 8192 tokens, menos 1024 para a resposta, deixam 7168 tokens para tudo o que o modelo lê em um passo. O prompt contém o prompt de sistema, os esquemas das ferramentas, a issue, as notas, os passos anteriores e o último resultado de ferramenta, e tudo isso conta contra esse orçamento. Uma recusa é um resultado de ferramenta como qualquer outro: o harness devolve o texto dela ao modelo como uma mensagem de ferramenta, então ela também conta contra o orçamento. Este capítulo chama isso de orçamento de prompt.

budget-counts-tokens.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""The context the harness loads the model with, the room the reply keeps, and each run's largest prompt against them.The point rests on the line of steps over the prompt budget: no recorded step reached it."""import jsonfrom lib.context import PROMPT_BUDGET, REPLY, WINDOWfrom lib.models import RECORDEDfolder = RECORDED / "task-set"manifest = json.loads((folder / "manifest.json").read_text(encoding="utf-8"))steps = [json.loads(line) for line in (folder / "replies.jsonl").read_text(encoding="utf-8").splitlines()]assert manifest["n_ctx"] == WINDOW and manifest["max_tokens"] == REPLY, "the budget comes from the recorded load settings"print("load setting, n_ctx, in tokens:", WINDOW)  # the harness's own load setting, not the model's native lengthprint("reply reservation, max_tokens, in tokens:", REPLY)print("prompt budget, in tokens:", PROMPT_BUDGET)print("steps recorded:", len(steps))# ties go to the later run and step, so the same step is named on every runlargest = max(steps, key=lambda s: (s["prompt_tokens"], s["run"], s["step"]))print("largest prompt, in tokens:", largest["prompt_tokens"])print("largest prompt, run:", largest["run"])print("largest prompt, step:", largest["step"])print("room left for the reply at the largest step:", WINDOW - largest["prompt_tokens"] - REPLY)print("steps over the prompt budget:", sum(s["prompt_tokens"] > PROMPT_BUDGET for s in steps))for task in sorted(manifest["tasks"], key=lambda t: t["task"]):    mine = [s["prompt_tokens"] for s in steps if s["run"] == task["task"]]    print(f"{task['task']}: steps {len(mine)}, largest prompt {max(mine)}")    assert len(mine) == task["steps"], "the stored step count must match the replies"
Saídapython budget-counts-tokens.py
load setting, n_ctx, in tokens: 8192
reply reservation, max_tokens, in tokens: 1024
prompt budget, in tokens: 7168
steps recorded: 220
largest prompt, in tokens: 6556
largest prompt, run: T-16
largest prompt, step: 16
room left for the reply at the largest step: 612
steps over the prompt budget: 0
T-01: steps 16, largest prompt 4519
T-02: steps 16, largest prompt 4419
T-03: steps 12, largest prompt 3429
T-04: steps 5, largest prompt 2545
T-05: steps 5, largest prompt 2389
T-06: steps 16, largest prompt 6143
T-07: steps 9, largest prompt 4919
T-08: steps 7, largest prompt 3123
T-09: steps 6, largest prompt 2400
T-10: steps 16, largest prompt 5493
T-11: steps 16, largest prompt 3139
T-12: steps 12, largest prompt 3997
T-13: steps 16, largest prompt 4880
T-14: steps 7, largest prompt 2763
T-15: steps 10, largest prompt 3052
T-16: steps 16, largest prompt 6556
T-17: steps 9, largest prompt 2878
T-18: steps 4, largest prompt 1559
T-19: steps 9, largest prompt 4204
T-20: steps 13, largest prompt 4183

Antes de imprimir qualquer coisa, o código verifica se o manifesto da gravação indica a mesma janela e o mesmo limite de resposta que o harness, e interrompe a execução quando eles diferem. Em seguida, imprime o orçamento e o maior prompt de cada execução em relação a ele.

Uma API hospedada tem uma janela muito maior. A página de edição de contexto da documentação da API da Anthropic indica 100,000 tokens de entrada como o gatilho padrão para limpar resultados de ferramenta antigos (edição de contexto). Um gatilho em 100,000 tokens nunca dispararia numa janela de 8192 tokens, por isso este livro extrai o orçamento da configuração de carregamento do modelo que ele grava, e nunca de um padrão do fornecedor.

Regra prática: Obtenha a janela a partir da configuração de carregamento que a execução usou, conforme o manifesto a registra, e subtraia o limite da resposta antes de definir qualquer orçamento. Nunca a obtenha do comprimento anunciado de um modelo nem de um padrão do fornecedor, pois um orçamento copiado de um modelo maior permite que uma execução preencha a janela antes de o orçamento atuar.

Onde as execuções gravadas chegaram mais perto do orçamento

A gravação armazena a contagem de prompt que o modelo informou para cada passo, em replies.jsonl. O adaptador devolve essa contagem como prompt_tokens, conforme o capítulo 4 define a resposta, portanto são as contagens do próprio modelo. O harness não as estimou.

Com base nessas contagens, nenhum passo gravado atingiu o orçamento de prompt. Dos 220 passos gravados, 0 ultrapassaram esse limite. O maior foi o último passo de T-16, que deixou 612 tokens da janela de contexto livres depois de descontado o espaço reservado para a resposta. A verificação lê a gravação e não carrega nenhum modelo, de modo que qualquer pessoa pode executá-la sem o hardware que produziu a gravação. A mesma verificação, aplicada a uma nova gravação, mostra de imediato se os prompts dela ainda cabem no orçamento, o que a torna a primeira coisa a ser executada novamente após uma mudança de modelo.

Esse resultado diz menos do que parece. O conjunto de tarefas gravado usou o conjunto de ferramentas v1 e não havia nada entre o loop e o modelo que pudesse encurtar ou recusar um prompt. Nada foi compactado, e nenhum passo foi cortado para caber. As contagens mostram que esses prompts cabem. Elas não mostram o que o harness faz quando um prompt não cabe, e o restante deste capítulo trata desse caso.

Regra prática: Compare a contagem de cada passo com o orçamento de prompt antes de tirar qualquer conclusão de uma execução.

Estime o prompt quando o harness não puder contá-lo

A contagem exata vem do tokenizador próprio do modelo, que faz parte do arquivo do modelo. Os exemplos deste livro rodam offline e nunca abrem esse arquivo, que tem cerca de 2.5 GB e não está no livro. Por isso, o harness estima. Ele conta os caracteres de cada mensagem e dos esquemas das ferramentas, e divide por três, arredondando para cima: um token para cada 3 caracteres.

Escolhemos três observando a gravação do conjunto de tarefas. A primeira regra que testamos foi de quatro caracteres por token. Nos 220 passos do conjunto de tarefas, quatro ficou abaixo da contagem real em 216 deles. Uma estimativa abaixo da contagem é a direção perigosa, porque o harness acreditaria ter espaço que o modelo não tinha. Por isso, passamos para três.

A estimativa de cada passo pode ser comparada com a contagem que o modelo informou para esse mesmo passo.

estimate-vs-recorded.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""The estimate of each recorded request against the prompt count the model reported for it. The rule was chosen ontask-set; chapter-5-notes was recorded after the rule was fixed, so its lines are the held-out check. The point restson the steps below the recorded count: none, in either recording."""import jsonfrom lib.case import load_tasksfrom lib.context import CHARS_PER_TOKEN, PROMPT_BUDGET, Measured, Notes, characters, estimate, notes_toolsetfrom lib.loop import Stops, run_taskfrom lib.models import RECORDED, ReplayModelfrom lib.tools import V1from lib.trace import IdCounterdef replay(recording, tasks, tools, **limits):    """Every request the recorded runs sent: its messages, its tool schemas and the count the model reported."""    ids, requests = IdCounter(), []  # the replay rebuilds each request, so each estimate sees the messages the model saw    for task in tasks:        model = Measured(ReplayModel(recording, task.id))        run_task(model, task, tools, ids=ids, **limits).close()        requests += model.requests    return requestsdef report(name, requests):    """Prints the comparison of the estimate with the count, labelled with the recording's name, and returns the pairs."""    pairs = [(estimate(m, t), n) for m, t, n in requests]    print(f"{name} steps compared:", len(pairs))    print(f"{name} characters per token, recorded (all steps):",          f"{sum(characters(m, t) for m, t, _ in requests) / sum(n for _, n in pairs):.2f}")    print(f"{name} steps where the estimate is above the recorded count:", sum(e > n for e, n in pairs))    print(f"{name} steps where the estimate is below the recorded count:", sum(e < n for e, n in pairs))    print(f"{name} lowest estimate divided by the recorded count: {min(e / n for e, n in pairs):.2f}")    print(f"{name} highest estimate divided by the recorded count: {max(e / n for e, n in pairs):.2f}")    assert all(e >= n for e, n in pairs), f"{name}: the rule should never count fewer tokens than the model did"    return pairsmanifest = json.loads((RECORDED / "chapter-5-notes" / "manifest.json").read_text(encoding="utf-8"))assert manifest["context"]["chars_per_token"] == CHARS_PER_TOKEN, "the held-out recording used the same rule"print(f"estimate rule, characters per token: {CHARS_PER_TOKEN}")task_set = replay("task-set", load_tasks(), V1, max_steps=V1.step_cap)pairs = report("task-set", task_set)# four is the rule a reader would try first: it is the one the comparison is againstprint("task-set with 4 characters per token, steps below the recorded count:",      sum(estimate(m, t, 4) < n for m, t, n in task_set))print("task-set steps whose estimate is over the prompt budget:", sum(e > PROMPT_BUDGET for e, _ in pairs))print("of those, steps whose recorded count is within the budget:",      sum(e > PROMPT_BUDGET and n <= PROMPT_BUDGET for e, n in pairs))report("held-out", replay("chapter-5-notes", load_tasks(only=["T-01", "T-02", "T-06"]), notes_toolset(Notes()),                          max_steps=16, stops=Stops(repeat_limit=3, no_progress_limit=2)))
Saídapython estimate-vs-recorded.py
estimate rule, characters per token: 3
task-set steps compared: 220
task-set characters per token, recorded (all steps): 3.67
task-set steps where the estimate is above the recorded count: 220
task-set steps where the estimate is below the recorded count: 0
task-set lowest estimate divided by the recorded count: 1.14
task-set highest estimate divided by the recorded count: 1.35
task-set with 4 characters per token, steps below the recorded count: 216
task-set steps whose estimate is over the prompt budget: 3
of those, steps whose recorded count is within the budget: 3
held-out steps compared: 18
held-out characters per token, recorded (all steps): 3.74
held-out steps where the estimate is above the recorded count: 18
held-out steps where the estimate is below the recorded count: 0
held-out lowest estimate divided by the recorded count: 1.22
held-out highest estimate divided by the recorded count: 1.29

A estimativa ficou acima da contagem registrada em todos os 220 passos, e nunca abaixo dela. A razão entre estimativa e contagem variou de 1.14 a 1.35. As contagens registradas incluem os tokens do template de chat, que a estimativa não conta; por isso, a média de 3.67 caracteres por token é uma razão para este formato de prompt, e não para o texto isolado.

O custo do lado seguro também é visível. Três passos tiveram estimativa acima do orçamento de prompt, e em todos os três a contagem própria do modelo ficou dentro dele. Um harness que confiasse na estimativa teria compactado esses passos sem motivo.

A regra foi escolhida com os passos do conjunto de tarefas, por isso esses passos não podem testá-la. A verificação com dados reservados é a gravação chapter-5-notes. Ela foi feita depois que a regra foi fixada, e suas contagens não foram usadas para escolhê-la. Seus 18 passos mostram o mesmo padrão: nenhum abaixo da contagem, com razões de 1.22 a 1.29, e 3.74 caracteres por token. É o mesmo modelo e textos semelhantes, então não mostra que a regra vale para outro tokenizador, outro idioma ou código cheio de símbolos.

Regra prática: Estime com três caracteres por token e compare a estimativa com as contagens que o modelo informa nas primeiras execuções de qualquer modelo novo. Se a estimativa cair alguma vez abaixo da contagem informada, use um número menor de caracteres por token antes de confiar no orçamento.

Coloque o último resultado no fim

A posição de um fato no prompt importa tanto quanto a presença dele. Em um artigo de 2023, Liu e colegas constataram que o desempenho costumava ser maior quando a informação relevante vinha no início ou no fim de uma entrada longa, e caía quando ela estava no meio (Lost in the Middle). Esses modelos são mais antigos do que o que este livro registra, então o artigo descreve um padrão em modelos antigos, e não o que o Qwen3-4B-Instruct-2507 faz com um prompt longo.

O layout do livro coloca o problema e as notas perto do início, e o último resultado de ferramenta no fim, onde o modelo o lê por último antes de responder. Essa é a regra de design do livro. Nenhuma fonte aqui diz que o último resultado precisa vir por último, e o livro não mediu esse layout neste modelo. A razão da escolha é o artigo. O exemplo de compactação abaixo imprime cada mensagem enviada ao modelo na última chamada, em ordem: o prompt de sistema, o problema, o resumo, a última chamada e o resultado dela.

O layout tem um custo. A compactação coloca o resumo das etapas anteriores entre o problema e a última chamada com seu resultado, que é o meio do prompt. Pelo padrão descrito no artigo, é ali que um modelo usaria com menos eficácia a informação. O livro aceita esse custo.

Regra prática: Coloque o problema e as notas primeiro, e o último resultado de ferramenta por último. Trate isso como uma escolha de design, e só afirme um ganho depois que uma execução com as suas próprias tarefas mostrar um.

Compacte os passos mais antigos e mantenha o último par

Quando a estimativa ultrapassa o orçamento de prompt, o harness compacta. A compactação aqui é local: o próprio harness escreve o resumo, e o modelo nunca vê essa escrita acontecer. Os passos mais antigos viram uma única mensagem, com uma linha por passo: a chamada, seus argumentos cortados em 60 caracteres, e a primeira linha de seu resultado, também cortada em 60 caracteres. O prompt de sistema e o issue permanecem como estão. O último passo, sua chamada e seu resultado, entra palavra por palavra, para que o modelo veja a evidência mais recente por inteiro.

Os fornecedores também oferecem compactação em seus servidores. O guia de compactação da Anthropic descreve uma delas: a compactação "substitui os turnos mais antigos de uma conversa por um resumo que o Claude escreve no servidor" (compactação). Sua forma sob demanda é um beta, atrás do cabeçalho compact-2026-09-04. O livro não usa a forma no servidor, e nada neste capítulo depende de como ela se comporta. Lemos essa página e não a executamos.

A regra de corte é a que mais importa para um harness local. O guia do fornecedor sobre como manter os turnos recentes afirma isso com clareza: "Coloque o corte onde nenhuma chamada de ferramenta fique aberta, com cada chamada de ferramenta e seu resultado do mesmo lado" (manter os turnos recentes). Um corte que cai sobre um resultado de ferramenta deixa esse resultado sem a chamada que o pediu, por isso o harness recusa tal corte.

Quatro leituras e um fechamento, sob um orçamento de 2000 tokens estimados, bastam para ultrapassá-lo. Esse orçamento está bem abaixo dos 7168 reais, de propósito, para que a compactação aconteça em uma tarefa pequena. O orçamento real não é atingido por esta tarefa.

compact-keeps-last-result.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""Four reads of the case, then finish, under a small budget that the reads cross. The point rests on the callscompacted line and the last two lines: the summary replaces the older steps, and a cut that would leave the lastcall's result on its own is refused."""from lib.case import load_tasksfrom lib.chapter1 import callfrom lib.context import Compacting, Context, Measured, clean_cut, estimatefrom lib.loop import run_taskfrom lib.models import ScriptedModelfrom lib.tools import V2from lib.trace import IdCounter# estimated tokens: above the fixed part and one result, below the full transcript; the chapter's budget is 7168,# which the case's files never reachBUDGET = 2000replies = [call("read_file", path=p) for p in ("unitcraft/convert.py", "unitcraft/units.py", "unitcraft/parse.py",                                                "README.md")] + [call("finish", summary="Read four files.")]ctx = Context(prompt_budget=BUDGET)model = Compacting(Measured(ScriptedModel(replies)), ctx)run = run_task(model, load_tasks(only=["T-01"])[0], V2, max_steps=V2.step_cap, ids=IdCounter())sent, tools, _ = model.inner.requests[-1]# the last request: system prompt, issue, summary, the last call, its resultprint("budget, in estimated tokens:", BUDGET)print("steps:", run.steps)print("ended:", run.ended)print("calls compacted:", ctx.compactions)print("calls still over the budget:", ctx.over_budget)print("fixed part (system prompt, tool schemas, issue), estimated tokens:", estimate(sent[:2], tools))print("messages sent on the last call:", len(sent))for number, message in enumerate(sent, start=1):    print(f"message {number}, {message['role']}:", " ".join(message["content"].split()[:4]))# the summary's first line is its heading, so the steps start at the second lineprint("summary of the older steps:", *sent[2]["content"].splitlines()[1:], sep="\n  ")# the call is wrapped in <tool_call> tags, so its JSON is the second lineprint("kept call:", sent[3]["content"].strip().splitlines()[1][:60])print("kept result, in lines:", len(sent[4]["content"].splitlines()))print("cut before the last result alone, clean:", clean_cut(sent, len(sent) - 1))print("cut before the last call, clean:", clean_cut(sent, len(sent) - 2))assert ctx.compactions > 0 and not clean_cut(sent, len(sent) - 1) and clean_cut(sent, len(sent) - 2)
Saídapython compact-keeps-last-result.py
budget, in estimated tokens: 2000
steps: 5
ended: finish
calls compacted: 3
calls still over the budget: 0
fixed part (system prompt, tool schemas, issue), estimated tokens: 1289
messages sent on the last call: 5
message 1, system: You are a maintenance
message 2, user: `format_quantity` drops the trailing
message 3, user: Earlier steps, summarised by
message 4, assistant: <tool_call> {"name": "read_file", "arguments":
message 5, tool: # unitcraft unitcraft parses,
summary of the older steps:
  step 1: read_file({"path": "unitcraft/convert.py"}) -> """convert: change a quantity to another unit of the same di
  step 2: read_file({"path": "unitcraft/units.py"}) -> """The unit table: each symbol with its dimension and its fa
  step 3: read_file({"path": "unitcraft/parse.py"}) -> """parse_quantity: read a quantity written as text, such as
kept call: {"name": "read_file", "arguments": {"path": "README.md"}}
kept result, in lines: 42
cut before the last result alone, clean: False
cut before the last call, clean: True

A execução compactou 3 chamadas antigas, e a última chamada e seu resultado chegaram inteiros: uma leitura de README.md, cujo resultado tinha 42 linhas. A parte fixa, o prompt de sistema, os esquemas das ferramentas e o issue, somou 1289 tokens estimados. A compactação não consegue cortar essa parte, então um orçamento abaixo dela não pode ser atendido por nenhuma compactação.

Dois cortes são impressos por último. Um corte antes do último resultado, separado da sua chamada, é recusado, e um corte antes da sua chamada é válido. O código afirma as duas coisas, de modo que uma mudança em qualquer uma delas faz a execução falhar.

Regra prática: Mantenha a última chamada e seu resultado juntos, recuse qualquer corte que caia sobre um resultado de ferramenta e verifique se a parte fixa cabe no orçamento antes de contar com a compactação para fazer o resto caber.

Mantenha as notas fora do contexto

A compactação perde detalhes por design. O post de engenharia da Anthropic sobre engenharia de contexto trata isso como uma escolha: "A arte da compactação está na seleção do que manter e do que descartar, pois uma compactação excessivamente agressiva pode resultar na perda de contexto sutil, mas crítico, cuja importância só se torna aparente mais tarde" (Engenharia de contexto eficaz para agentes de IA). O mesmo post descreve a saída, que são as notas mantidas fora da janela de contexto, mas não relata nenhuma medição delas.

O harness acrescenta uma ferramenta note. O modelo escreve uma linha por fato, e o harness envia as notas após o problema em cada passo. A compactação não as corta, porque elas não fazem parte dos passos mais antigos. Um fato que o modelo escreve como nota sobrevive a todas as compactações. Um fato que permanece apenas em um resultado antigo é mantido, no máximo, como a primeira linha desse resultado.

notes-survive.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""A note the agent writes keeps a fact that an older read result had, after a compaction. The summary keeps only thefirst line of each read, and the fact sits on line 18 of format.py, so the read's summary line lacks it while the notekeeps it whole. The point rests on the last assertions: the fact is in the notes block and not in the read's line."""from lib.case import load_tasksfrom lib.chapter1 import callfrom lib.context import Compacting, Context, Measured, Notes, notes_toolsetfrom lib.loop import run_taskfrom lib.models import ScriptedModelfrom lib.trace import IdCounterBUDGET = 2000  # estimated tokens: the notes and the reads cross it, the last request fits under it# each note states a fact the run has just read in the case, so every note is true of unitcraftnotes = [    "format_quantity strips trailing zeros on line 18 of format.py (frac.rstrip), so 3.50 kg prints as 3.5 kg",    "test_pads_to_two_places in tests/test_format.py expects 3.5 kg to print as 3.50 kg, so the strip fails it",    "round_places goes through float, so 2.675 rounds to 2.67, and test_tie_at_a_binary_float_edge expects 2.68",]replies = [call("read_file", path="unitcraft/format.py"), call("note", text=notes[0]),           call("read_file", path="tests/test_format.py"), call("note", text=notes[1]),           call("read_file", path="unitcraft/rounding.py"), call("note", text=notes[2]),           call("read_file", path="README.md"), call("finish", summary="Read the case and noted the failing tests.")]store = Notes()ctx = Context(notes=store, prompt_budget=BUDGET)  # the notes are kept outside the older steps, so compaction keeps themmodel = Compacting(Measured(ScriptedModel(replies)), ctx)run = run_task(model, load_tasks(only=["T-01"])[0], notes_toolset(store), max_steps=16, ids=IdCounter())sent = model.inner.requests[-1][0]block = next(m["content"] for m in sent if m["content"].startswith("Your notes so far"))summary = next(m["content"] for m in sent if m["content"].startswith("Earlier steps"))read_line = summary.splitlines()[1]  # the first step: the read of format.py, with its first result line cut shortprint("steps:", run.steps)print("ended:", run.ended)print("compactions:", ctx.compactions)print("notes written:", len(store.lines))print("notes whole in the notes block:", sum(line in block for line in store.lines))print("lines in the notes block that name the fact (rstrip):", sum("rstrip" in line for line in block.splitlines()))print("summary line for the read of format.py:", read_line)assert ctx.compactions > 0, "the run should compact"assert all(line in block for line in store.lines), "every note should be whole in the notes block"assert "format.py" in read_line and "rstrip" not in read_line, "the read's summary line must lack the fact"assert "rstrip" in block, "the note must keep the fact"
Saídapython notes-survive.py
steps: 8
ended: finish
compactions: 5
notes written: 3
notes whole in the notes block: 3
lines in the notes block that name the fact (rstrip): 1
summary line for the read of format.py: step 1: read_file({"path": "unitcraft/format.py"}) -> """format_quantity: write a quantity as text, such as ``3.50

Este exemplo é um script, não o modelo. Um ScriptedModel lê quatro arquivos e escreve três notas, cada uma logo após a leitura de onde veio. O fato está na linha 18 do arquivo, e o resumo guarda apenas a primeira linha do arquivo, de modo que a linha do resumo para essa leitura traz a docstring, e não o fato. A execução passou por 5 compactações. Todas as 3 notas estão íntegras no bloco de notas da última requisição, e 1 dessas linhas nomeiam o fato. Cada nota afirma algo que a execução havia lido no caso, de modo que você pode conferir cada uma delas com os arquivos do caso.

Isso mostra o mecanismo. Não mostra que um modelo vai escrever as notas. A seção seguinte verifica isso em uma gravação do modelo.

Regra prática: Escreva em uma nota um fato de que um passo posterior precisa, e não apenas no resumo. Um resumo guarda uma seleção, e as notas são o único lugar em que o livro guarda um fato por inteiro.

O que o modelo gravado fez com o orçamento

A gravação chapter-5-notes foi feita com o conjunto de ferramentas v2 do capítulo 3, a ferramenta de notas e as regras de parada do capítulo 2. Suas três execuções são T-01, T-02 e T-06. Sete execuções do conjunto de tarefas atingiram o limite de passos de 16 (T-01, T-02, T-06, T-10, T-11, T-13, T-16), e o script da gravação identifica essas três como as execuções longas que atingiram esse limite. Ela não executa as outras quatro. Reproduzimos as três execuções com compactação ativada, para ver o que o modelo fez com as ferramentas e com o orçamento.

recorded-context-use.py Python 3.12.15 · pydantic 2.14.3 Aprovado
"""The three recorded runs of chapter 5, replayed with the compaction on: how each ended, whether its check passed,its note calls and compactions, and its largest prompt by the estimate and by the count the model reported. The pointrests on the check lines and the zero counts: no run passed its check, and no run wrote a note or was compacted."""import jsonfrom lib.case import load_tasksfrom lib.context import Compacting, Context, Measured, Notes, estimate, notes_toolsetfrom lib.loop import Stops, run_taskfrom lib.models import RECORDED, ReplayModelfrom lib.trace import IdCountermanifest = json.loads((RECORDED / "chapter-5-notes" / "manifest.json").read_text(encoding="utf-8"))recorded = {t["task"]: t for t in manifest["tasks"]}  # the recording's own check result, stored with each runids, passed, notes_total, compact_total, est_max, rec_max = IdCounter(), 0, 0, 0, 0, 0for task in load_tasks(only=["T-01", "T-02", "T-06"]):    notes = Notes()    context = Context(notes=notes)  # the default budget, 7168 tokens, which no run reaches    model = Compacting(Measured(ReplayModel("chapter-5-notes", task.id)), context)    # the step cap of 16 and the stop rules are those the recording was made with    run = run_task(model, task, notes_toolset(notes), max_steps=16, ids=ids,                   stops=Stops(repeat_limit=3, no_progress_limit=2))    run.close()    print(f"{task.id} kind: {recorded[task.id]['kind']}")    print(f"{task.id} ended: {run.ended}")    print(f"{task.id} check passed: {'yes' if recorded[task.id]['done'] else 'no'}")    print(f"{task.id} note calls: {sum(r['tool'] == 'note' for r in run.trace.records)}")    print(f"{task.id} compactions: {context.compactions}")    passed += recorded[task.id]["done"]    notes_total += sum(r["tool"] == "note" for r in run.trace.records)    compact_total += context.compactions    est_max = max([est_max] + [estimate(m, t) for m, t, _ in model.inner.requests])    rec_max = max([rec_max] + [n for _, _, n in model.inner.requests])print("total note calls:", notes_total)print("total compactions:", compact_total)print("runs whose check passed:", passed)print("largest estimated prompt over the three runs, in tokens:", est_max)print("largest recorded prompt over the three runs, in tokens:", rec_max)assert notes_total == 0, "the recorded runs made no note calls"assert compact_total == 0, "the recorded runs were never compacted"assert passed == 0, "none of the three recorded runs passed its check"
Saídapython recorded-context-use.py
T-01 kind: fix
T-01 ended: ask_user
T-01 check passed: no
T-01 note calls: 0
T-01 compactions: 0
T-02 kind: fix
T-02 ended: finish
T-02 check passed: no
T-02 note calls: 0
T-02 compactions: 0
T-06 kind: implement
T-06 ended: no_progress
T-06 check passed: no
T-06 note calls: 0
T-06 compactions: 0
total note calls: 0
total compactions: 0
runs whose check passed: 0
largest estimated prompt over the three runs, in tokens: 4012
largest recorded prompt over the three runs, in tokens: 3189

O modelo não escreveu notas em nenhuma das três execuções, e nenhuma execução foi compactada. O maior prompt que a estimativa viu teve 4012 tokens, e o maior que o modelo relatou teve 3189. Ambos ficam abaixo do orçamento de prompt.

Cada execução terminou antes de seu contexto se aproximar do orçamento, e nenhuma delas passou na verificação. T-01 terminou como ask_user, quando o modelo fez uma pergunta à pessoa. T-01 é uma tarefa de correção, então essa pergunta foi um repasse errado. T-02 terminou como finish, quando o modelo chamou finish, e sua verificação não passou. T-06 terminou como no_progress, que é a regra de parada do capítulo 2: duas edições seguidas deixaram as contagens de testes inalteradas. Assim, o modelo parou duas execuções por conta própria, ambas de forma errada, e uma regra de parada parou a terceira. Apresentados execução por execução, os resultados das verificações dão 0 aprovações em três.

Três execuções em três tarefas mostram o que aconteceu nessas tarefas, e nada sobre as outras dezessete. Essas execuções não testam nem o orçamento nem as notas.

Regra prática: Antes de julgar um orçamento ou uma ferramenta por uma gravação, verifique como cada execução terminou. Uma execução que para cedo nunca testa o orçamento, e um modelo que nunca chama uma ferramenta nunca a testa.

Meça o efeito em vez de citá-lo

Um relatório técnico de julho de 2025 da Chroma, "Context Rot", de Hong, Troynikov e Huber, constatou que "o desempenho do modelo varia significativamente conforme o comprimento da entrada muda, mesmo em tarefas simples" (Context Rot). O relatório avalia 18 LLMs de vários fornecedores, incluindo o Qwen3, em tarefas próprias. Este capítulo não reexecuta essas tarefas e, por isso, não cita nenhum tamanho de efeito delas.

O livro mede suas próprias execuções. O Capítulo 10 executa o conjunto de tarefas em duas versões do harness e compara os resultados como contagens de tarefas concluídas. O harness v2 acrescenta o orçamento entre várias outras mudanças, de modo que essa comparação não pode atribuir o ganho somente ao orçamento. Uma execução filha no capítulo 8 mantém um orçamento próprio, contado em seus próprios passos.

Cada exemplo aqui mede outra coisa. O exemplo do orçamento mede onde os prompts registrados se situavam, e os exemplos de compactação e de notas medem o que o harness retém. Nenhum deles mede como o comprimento afeta as respostas de um modelo; por isso, este capítulo não afirma que um prompt longo prejudica a precisão.

Regra prática: Meça como um orçamento altera o seu próprio conjunto de tarefas, com as contagens que as execuções reportam, antes de afirmar que ele ajuda. Cite um efeito publicado somente com sua configuração e sua fonte, e apenas como resultado desse relatório.

Como um orçamento dá errado, e como perceber

Quatro coisas dão errado com orçamentos na prática, e cada uma pode ser percebida.

A primeira é um modelo alterado. Um modelo novo pode ter outra janela, outro tokenizador ou outro limite de resposta. O orçamento fica então errado sem nenhum erro, porque a verificação continua sendo executada e continua passando com o número antigo. Você percebe quando a janela no manifesto da gravação não corresponde mais à constante que o harness usa, então mantenha os dois vinculados e faça a execução falhar quando forem diferentes. A seção sobre a janela explica a verificação.

A segunda é uma estimativa que se desvia. A estimativa só é tão boa quanto a regra de caracteres por token para o modelo e para o texto à frente. A resposta já traz a contagem própria do modelo, então compare as duas em cada passo das primeiras execuções reais e registre os pares. Uma estimativa abaixo da contagem é o sinal de que é preciso agir, porque o harness então acredita ter um espaço que não tem.

A terceira é um resumo que deixa de fora o que um passo posterior precisa. Uma execução compactada pode chamar a mesma ferramenta outra vez, porque o primeiro resultado agora é apenas uma linha no resumo. As regras de parada do capítulo 2 detectam repetições exatas, mas uma quase repetição, como a leitura do mesmo arquivo com um caminho ligeiramente diferente, passa por elas. Conte as leituras que uma execução faz do mesmo arquivo e trate uma repetição como sinal de que o resumo perdeu alguma informação.

A quarta é um bloco de notas que cresce. As notas são enviadas em cada passo, a compactação nunca as corta, e nada limita o tamanho de uma nota nem a quantidade delas. Uma execução que escreve muitas notas faz crescer sua parte fixa até que a compactação não consiga cumprir o orçamento. O contexto conta, em over_budget, as chamadas que continuam acima do orçamento depois da compactação, e um número maior que zero é o sinal.

Regra prática: registre a estimativa e a contagem informada em cada passo de uma execução real, e trate uma estimativa abaixo da contagem como falha. Quando uma execução pedir um arquivo que o próprio resumo já cobre, verifique o que o resumo manteve antes de a execução ler o arquivo novamente.

Decisões tomadas neste capítulo

  • O orçamento de prompt é a configuração de carga menos o espaço reservado para a resposta, e acompanha a configuração de carga, não o comprimento anunciado pelo modelo.
  • O harness estima o prompt em três caracteres por token. As etapas do conjunto de tarefas escolheram essa regra, e a gravação posterior das notas do capítulo 5, que não a escolheu, mostra o mesmo padrão.
  • A compactação é local e determinística, de modo que uma execução reproduzida se compacta exatamente como a original. As etapas mais antigas viram uma linha cada, e a última chamada e seu resultado são mantidos palavra por palavra. Um corte que cai sobre um resultado de ferramenta é recusado.
  • As notas são uma ferramenta que o modelo pode usar. Elas são enviadas após o problema em cada etapa, de modo que a compactação nunca as corta, e o modelo decide se as escreve.
  • O livro não usa a compactação do lado do servidor oferecida pelo fornecedor.

As gravações mostram que os prompts cabem, e que a estimativa permaneceu acima da contagem nos dois conjuntos de etapas. O Capítulo 10 compara duas versões do harness por contagens, e não pode atribuir o mérito apenas ao orçamento.

Regra prática: Cite as execuções em que um orçamento ou uma ferramenta foram testados. Uma afirmação sobre um orçamento que nenhuma execução alcançou é uma afirmação sobre o projeto, não sobre o modelo.

Este capítulo, nesta edição

Edição 2026.11.2Exemplos aprovados em 20 de nov de 20265 de 5 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.2.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 5 de 12: Mantenha o contexto útil à medida que a tarefa cresce

  1. A janela que o modelo tem
  2. Onde as execuções gravadas chegaram mais perto do orçamento
  3. Estime o prompt quando o harness não puder contá-lo
  4. Coloque o último resultado no fim
  5. Compacte os passos mais antigos e mantenha o último par
  6. Mantenha as notas fora do contexto
  7. O que o modelo gravado fez com o orçamento
  8. Meça o efeito em vez de citá-lo
  9. Como um orçamento dá errado, e como perceber
  10. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos