AnthropicClaude Certified Architect – Professional2026-102.4 Optimize context windows and manage token usage
Choose what a long conversation loses
Completed by the knowledge check
Learning objective
Manage long conversations and agent runs with compaction, tool-result clearing, and summarization that keep critical facts and provenance.
Core idea
Exact facts need an independent record, and compaction needs a retention check. At the Professional level, decide which representation the production runtime replaces, who controls that replacement, and how the next request recovers the facts the transformation cannot guarantee.
Choose by what grows. Summarize a conversation whose decisions must continue; clear obsolete tool output when the useful thread can remain intact. An application-owned summarizer gives you control of the summary format and history rewrite, with corresponding responsibility for loss and API compatibility. None of these operations verifies that an observation remains true.
How it works
Choose a compaction control point
Anthropic recommends on-demand compaction wherever available. It is beta: send anthropic-beta: compact-2026-09-04 and top-level compaction: {"type": "summarize"}. The server summarizes the supplied conversation instead of generating an ordinary reply. A successful response has stop_reason: "compaction" and a signed compaction content block.
Replace the summarized messages with the returned assistant message. Keep the block, including signature, exactly as returned and first in messages; send the beta header on every later request carrying it. Send the same system and tools on the summarization request. If you retain recent turns with preserved thinking, their validity also depends on the documented prefix conditions; do not assume an arbitrary history splice is safe.
When the conversation cannot pause, run the same on-demand request in the background with compact-2026-09-04: continue on full history, then replace only the messages sent for summarization after stop_reason: "compaction", retaining every turn appended meanwhile. This keeps two requests open against rate limits, so start with headroom for intervening turns and use the swapped history on the first request after the block arrives.
Threshold compaction instead runs inside an ordinary request. Configure context_management.edits with type: "compact_20260112" and header compact-2026-01-12. Its default trigger is {"type": "input_tokens", "value": 150000}; the minimum configurable value is 50,000. Append the response, including its compaction block, to history; the API drops content before that block on subsequent requests. Set pause_after_compaction: true when the integration must inspect the summary before continuation.
Both mechanisms support Claude Sonnet 5.5, but their platform lists differ. The on-demand documentation lists Claude API, Claude Platform on AWS, Google Cloud, and Microsoft Foundry; the threshold documentation also lists Amazon Bedrock. Check the selected model and platform rather than equating Claude Platform on AWS with Amazon Bedrock. For on-demand model support, the Models API with its beta header exposes capabilities.compaction.
You cannot send top-level compaction and context_management on the same request. Threshold compaction cannot run on a request carrying a signed on-demand block. Choose a coherent compaction path before composing features.
Clear disposable output selectively
For the Claude API, server-side context editing is beta with anthropic-beta: context-management-2025-06-27. Configure context_management.edits with type: "clear_tool_uses_20250919". It replaces the oldest results with placeholders before inference while your client retains full history. It does not summarize their meaning.
Set trigger, keep, and exclude_tools according to the task’s retention needs. Defaults are 100,000 input tokens and three recent tool uses. The trigger can use input_tokens or tool_uses; keep expresses retained tool uses. exclude_tools protects named tools’ interactions. By default, clear_tool_inputs: false leaves call parameters visible; enabling it also clears those inputs.
Clearing invalidates cached prefixes. clear_at_least requests a minimum token saving; if that saving is impossible, the edit does not apply. A small retained-result count can therefore leave a large context unchanged when protected results or the minimum-saving condition prevent removal. Observe the applied edit rather than assuming configuration equals execution.
Log context_management.applied_edits, including cleared_tool_uses and cleared_input_tokens. Together with the original request and policy, this records which history transformation occurred. It is not an archive of the removed content by itself. Keep source records separately when later review must reconstruct a decision.
Make summary retention testable
For on-demand compaction, compaction.instructions replaces the default summarization prompt; it accepts a nonblank string up to 16,384 characters. Threshold compaction’s edit also has instructions, which replaces its default prompt. Name the decisions, unresolved conflicts, exact identifiers, qualifications, and source pointers that must survive, and tell the summarizer not to call tools. Anthropic recommends tuning for recall before removing superfluous detail.
Test later decisions after repeated compactions, not only whether one summary reads well. A source identifier without its contradictory qualification can preserve attribution while changing meaning. A status that loses “not yet executed” can turn an intention into a claimed outcome. Compare those facts with the independent record and reinject what the next call requires.
A custom summarizer produces an application message instead of the API’s compaction block. You own its prompt, replacement range, and loading of retained facts. On models with preserved thinking, client-side changes to earlier turns can invalidate later thinking; use a documented supported history strategy rather than carrying incompatible blocks forward. Prefer the supported server path when those compatibility costs outweigh the custom representation’s value.
Keep failed transformations from deleting history
For on-demand compaction, HTTP 200 does not prove a summary exists. Check stop_reason before replacing history: an unsuccessful summarization can return empty content. If max_tokens cut the summary, resend with a larger allowance. If model_context_window_exceeded left no room for the summarization prompt, shorten instructions or reduce supplied messages. If tool_use occurs, retry with instructions prohibiting tool calls. For refusal or an empty end_turn, continue without the summary and retain the original history. History is replaced only after stop_reason confirms the compaction.
Compaction itself costs tokens. Aggregate usage.iterations, including its compaction entry; top-level input and output counts exclude that summarization work. A smaller active window does not imply a smaller total run bill.
Key distinctions and trade-offs
Match the loss mechanism to the workload:
| Approach | Control and benefit | Main cost or loss |
|---|---|---|
| On-demand compaction | Application chooses a completed-turn boundary | Extra summarization call and summary loss |
| Threshold compaction | API triggers inside ordinary requests | Request pauses for summarization |
| Tool-result clearing | Policy removes selected old output | Detail disappears from model context; cache rebuild |
| Custom summarization | Application owns representation and rewrite | Retention and history compatibility become application work |
Compaction preserves a thread, clearing removes selected bulk, and durable storage preserves recoverable facts. See 2.4.4 for the store’s ownership and retrieval policy.
Architecture / decision scenario
A healthcare operations assistant investigates scheduling failures over four hours. It has a 15-second response target. In an illustrative trial, threshold compaction makes triggering requests take 23 seconds; an application-scheduled on-demand summary between investigation phases takes seven seconds while no user response is pending. Raw log output accounts for 70% of input, but a small scheduling-decision record remains critical.
The tempting alternative is to clear every old result and continue. That removes the only provenance for an unresolved override. A custom summarizer could format the handoff for the scheduling system, but the team has no requirement that justifies owning its history rewrite and thinking-block compatibility. The architect instead saves the qualified findings and source pointers independently, selects on-demand compaction at completed phase boundaries, and checks stop_reason: "compaction" before swapping history. A failed summary leaves history intact for recovery. Phase boundaries suffice because the trial leaves enough headroom until the next idle interval; if continuous work would fill the window before an idle boundary, the team switches to background compaction and preserves turns added during summarization.
For a separate tool-heavy path using context editing, the team protects the scheduling-record tool with exclude_tools, keeps recent diagnostic results, and records applied_edits. It does not combine that request’s context_management with top-level compaction. The service owner accepts the design after replay verifies both latency and recovery of the unresolved override through multiple reductions; operations accounts for summarization through usage.iterations.
Common exam traps
Avoid these transformation mistakes:
- Treating clearing as a summary or compaction as exact storage.
- Mixing the two compaction headers and history-replay rules.
- Replacing history after any HTTP 200, including empty summary output.
- Assuming protected tools guarantee that enough tokens can be cleared.
- Truncating oldest turns at a fixed token count without preserving their critical facts.
- Counting only top-level usage when compaction runs.
- Retaining thinking blocks across an unsupported client-side rewrite.
What to remember
Choose the replacement boundary and its loss deliberately. Preserve exact facts independently, validate summary success before swapping history, record applied edits, and include summarization iterations in the run budget.
Knowledge check
An application on the Claude API requests on-demand compaction before the next investigation phase, which cannot start until the history is compacted. The response is HTTP 200 with empty content and stop_reason: "max_tokens". What should the application do?
instructions and fewer messagesmax_tokensstop_reason: "compaction" . A max_tokens stop means the summary was cut off, so the documented fix is a larger max_tokens . Shorter instructions answer model_context_window_exceeded , and continuing without a summary is the response to a refusal or an empty end_turn .A long-running operations agent on the Claude API uses tool-result clearing (clear_tool_uses_20250919) because raw log output fills most of its input. One tool, get_schedule_record, returns the only provenance for an unresolved override that later turns depend on. How should the design treat that tool’s results?
get_schedule_record with exclude_tools and store the record separatelyclear_tool_inputs: true and keep the default of three retained tool useskeep until the record’s tool use is usually among the retained onesapplied_edits in each response to recover the record after it is clearedexclude_tools protects a named tool’s interactions from clearing, and an independent record keeps the provenance recoverable whatever the context holds. A larger keep only delays removal, and applied_edits reports how many tool uses and input tokens were cleared — not the removed content.After a team enables on-demand compaction, an operations dashboard that sums the top-level usage.input_tokens and usage.output_tokens of every request shows each run’s token use falling sharply. Why can the dashboard be wrong?
usage.iterations , not the top-level countscompaction entry in usage.iterations , while its top-level counts are zero. A smaller active window does not imply a smaller run bill, so the dashboard must sum across usage.iterations .A team runs Claude Sonnet 5.5 through Amazon Bedrock and needs the API to compact its long agent conversations. Which mechanism fits that deployment?
compaction: {"type": "summarize"}compact-2026-09-04 headercompact_20260112 in context_management.editsReferences
- Anthropic, Compaction overview
- Anthropic, Compaction on demand
- Anthropic, Compaction at a token threshold
- Anthropic, Context editing
- Anthropic, Effective context engineering for AI agents
- Anthropic, Compaction in the background