CertSafari
    Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards· Lessons

    Domain 2 · Lesson 12/39

    Reasoning effort and context lifecycle for long-running agents

    Reasoning Effort and Context Lifecycle

    20 min read
    2.17% of exam
    6 sources
    Published 18 Nov 2026
    Docs as of 18 Nov 2026

    What you will be able to do

    • Set output_config.effort for a workload's latency and accuracy target, and say why thinking budgets and max_tokens are the wrong levers on current models
    • Distinguish tool-result clearing, thinking-block clearing, compaction and the memory tool by what each removes or keeps
    • Choose on-demand, background or threshold compaction based on whether the agent can pause, and fix a summary that drops needed facts
    • Use the memory tool to carry state across sessions that each start with an empty history
    • Match a context lifecycle strategy to a workload's stated session length, latency and accuracy requirements

    Key concept

    Active context as a curated, finite resource — Each turn, an agent's context should hold only what the next step needs. Effort sets how many tokens Claude spends on a turn, and the lifecycle strategy (clearing, compaction, memory) sets which earlier tokens come along with it.

    1.Effort controls how much Claude spends per turn

    A long-running agent has two budgets to manage: how much it reasons on each turn, and how much history it carries into the next one. The effort parameter sets the first. A context lifecycle strategy sets the second. Getting either one wrong looks the same from outside: slow turns, rising cost, or an agent that loses track of its work. So you choose them together, against the workload's session length, latency target and accuracy bar.

    Effort is one request field, output_config.effort. It trades thoroughness against token efficiency on the same model, and it is not an on/off switch for thinking. It applies to every output token: the reply text, the arguments of tool calls, and thinking when thinking is active. Lowering it makes an agent faster and cheaper in two ways at once. The model thinks less, and it makes fewer, shorter tool calls.

    A Messages API request that runs at medium effortpython
    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=[
            {
                "role": "user",
                "content": "Analyze the trade-offs between microservices and monolithic architectures",
            }
        ],
        output_config={"effort": "medium"},
    )
    The five effort levels and the workloads each one is meant for
    LevelBehaviourTypical use
    maxNo limit on token spending; the deepest reasoningTasks that need the most thorough analysis possible
    xhighMore capability for long-horizon workAgentic and coding tasks that run over 30 minutes, with token budgets in the millions
    highSpends as many tokens as the task needsComplex reasoning, difficult coding, agentic tasks
    mediumBalanced, with moderate token savingsAgentic tasks that must balance speed, cost and performance
    lowMost efficient, with some loss of capabilitySimple tasks that need the best speed and lowest cost, such as subagents

    The default level depends on the model, which matters when you migrate. Most models default to high. Claude Opus 5.5 and Claude Haiku 5.5 default to medium, so a request that omits effort runs one level lower on Opus 5.5 than it did on Claude Opus 5. Claude Sonnet 5.5 defaults to high on the Claude API. Not every model that supports max also supports xhigh.

    On some models, effort is the only control you have over thinking. Adaptive thinking is always on in Claude Opus 5.5, and a request that tries to disable it fails at every effort level. On that model, the amount of reasoning is set entirely by effort. Some models let you change effort per message mid-conversation without invalidating the prompt cache. The caching rules themselves are covered in cache breakpoints and invalidation.

    Checkpoint 1 of 9· Fill the gap

    This request should run Claude Opus 5.5 at medium effort. Which request field completes it?

    response = client.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=[
            {
                "role": "user",
                "content": "Analyze the trade-offs between microservices and monolithic architectures",
            }
        ],
         ? ={"effort": "medium"},
    )

    Sources1

    2.Tuning effort against a latency target

    The token budget from older designs no longer exists. On Claude Sonnet 5.5, Opus 5.5, Haiku 5.5 and any model numbered 4.7 or higher, thinking: {type: "enabled"} returns a 400 error. To migrate, remove budget_tokens, use adaptive thinking, and control depth with effort. max_tokens is a different kind of control. It is a hard limit on all output, thinking plus reply text. Set it low and long answers get truncated, but the model doesn't decide any more carefully when to think. At high effort and above, it needs to be large.

    For latency-sensitive work on Sonnet 5.5, start low. For chat, begin at medium or low. For agentic coding and multistep tool use, begin at medium on well-specified tasks and move to high for harder or longer ones. Use xhigh or max only where your evals show a quality gain. Sonnet 5.5 also has a way to answer without thinking first: send thinking: {"type": "between_tools"}, not "disabled". This works at low, medium and high, and returns a 400 at xhigh or max. It has a catch. With between_tools, changing effort with a per-message output_config returns a 400 error. If you need effort to vary turn by turn, stay on adaptive thinking.

    The system prompt and effort control different things. On Claude Opus 5, effort sets how much the model thinks, not how long its visible reply is, so you get shorter replies by asking for them in the prompt. Thinking frequency works the other way round. Effort is the lever calibrated for it, and a stronger instruction is not.

    Lowering effort has an accuracy cost, and you should measure it before shipping. Sonnet 5.5's levels are calibrated differently from Claude Sonnet 5's, so run a fresh effort sweep on your own evals rather than reusing old settings. On a representative traffic sample, compare these before and after the change:

    • how often turns produce thinking
    • output tokens per turn
    • tail latency
    • answer quality

    The quality check matters most for long agent prompts. Haiku 5.5 at low effort tends to skip steps there.

    Checkpoint 2 of 9· Check yourself

    A latency-sensitive support agent on Claude Sonnet 5.5 sends thinking: {"type": "between_tools"} at medium effort. The team now wants harder turns to go to high effort, using a per-message output_config. What happens, and what should they do?

    Checkpoint 3 of 9· Exam question

    A customer-support agent on Claude Sonnet 5.5 through the Messages API must meet a 4-second p95 latency target. Traces show the model emits a thinking block on nearly every turn, including turns that only relay a tool result. A system prompt line telling it to answer directly did not change this behavior. Choose two.(Select 2)

    0 of 2 selected

    Sources21

    3.Clearing tool results and old thinking

    Context editing removes specific content that Claude has already used, and leaves the rest of the conversation intact. It offers two server-side strategies. clear_tool_uses_20250919 targets agents with heavy tool use, where a file read or a search result is dead weight once Claude has processed it. clear_thinking_20251015 removes thinking blocks from earlier assistant turns.

    Tool-result clearing starts once input grows past a trigger. It removes the oldest results first, and each cleared result is replaced with placeholder text that tells Claude something was there. By default, Claude's original tool calls stay visible. Setting clear_tool_inputs to true clears the call parameters as well. Clearing happens on the server before the prompt reaches Claude. Your application keeps sending the full, unedited history and never has to sync its copy with the edited one.

    Configuration options for clear_tool_uses_20250919
    OptionDefaultEffect
    trigger100,000 input tokensClearing starts when the prompt passes this threshold (input_tokens or tool_uses)
    keep3 tool usesNumber of the most recent tool use/result pairs that survive clearing
    clear_at_leastNoneMinimum tokens to clear per activation; if the API can't reach it, nothing is cleared
    exclude_toolsNoneTools whose uses and results are never cleared
    clear_tool_inputsfalseAlso clear the tool call parameters, not just the results

    Thinking-block clearing is configured with keep, which counts how many recent assistant turns hold on to their thinking. If you include the strategy without keep, you get a value of 1 on every model, including models whose own default keeps all thinking. The choice is a trade-off. Keeping thinking preserves the prompt cache. Clearing it frees space in the context window, and the cache is invalidated at the point where clearing happens. Tool-result clearing also invalidates cached prefixes, so clear_at_least exists to make sure each clearing frees enough tokens to justify a new cache write.

    Checkpoint 4 of 9· Check yourself

    Your team turns on clear_tool_uses_20250919 for a long-running coding agent. A developer proposes changing the client so that, after each response, it keeps only the cleared version of the conversation. What should the team do with the client's history?

    Sources3

    4.Compaction for one long conversation

    Compaction replaces whole stretches of older turns with a summary. Clearing removes individual items, but compaction summarizes the conversation itself. Claude writes the summary on the server, so you don't write any summarization code. It keeps a long task inside the context window and keeps the active context small, which matters because response quality drops as a conversation grows. Server-side compaction comes in two modes, and they differ in who decides when it runs and whether the agent has to wait.

    Server-side compaction modes compared against an agent's constraints
    QuestionOn demandAt a token threshold
    Who decides whenYou, by sending a requestThe API, when input tokens reach your trigger
    Code you writeA loop that requests the summary and swaps it inOne parameter on ordinary requests
    Runs in the backgroundYesNo: it runs inside the request that reaches the threshold
    Recent turns kept word for wordYesYes, by pausing after compaction and reinserting them
    Kept turns keep their thinking (preserved-thinking models)Yes, under conditionsNo

    Background compaction keeps work moving. You send the compaction request with the history as it stands and note how many messages it covered. The conversation continues on the full history while the request runs. When the block comes back, you drop exactly the messages it summarized from the front of the history and put the block in their place. Every turn added in the meantime stays after it. Use on-demand compaction wherever it is available. Choose it over threshold compaction when operators can't let the agent stall.

    A summary that loses facts is fixed through the prompt that writes it. The default prompt covers the task, current state, discoveries, next steps and preferences. It won't necessarily keep the specific identifiers a later turn depends on, such as ticket numbers, account IDs or open decisions. Writing your own summarization prompt that names those as required content replaces the default prompt. Settings applied after the summary can't bring them back. Raising effort doesn't help, because the facts are no longer in context to reason about. Keeping old thinking blocks doesn't help either, because the summarized turns are gone.

    Some workloads are a poor fit for compaction. These include tasks that need precise recall of early conversation details, tasks that must track exact state across many variables, and workflows that use server-side tools heavily. The last case applies to the client-side SDK variant, compaction_control in the TypeScript and Ruby tool_runner. That variant adds up cache-read tokens from a server tool's internal calls and can trigger compaction too early. Server-side compaction is generally preferred.

    Checkpoint 5 of 9· Check yourself

    After server-side compaction, a support agent on a long ticket-handling session keeps losing the account IDs and ticket numbers that later turns need. Which change fixes this at the source?

    Checkpoint 6 of 9· Exam question

    An autonomous operations agent on Claude Sonnet 5.5 through the Messages API runs for many hours in one conversation. Operators cannot let work stall while a summary is written, and after the first compaction the agent forgot ticket IDs and open decisions. Choose two changes that fit these constraints.(Select 2)

    0 of 2 selected

    Sources453

    5.Memory for work that spans sessions

    Clearing and compaction both work inside a single conversation. A session that starts with an empty message history gets nothing from either one. The memory tool covers that gap. Claude creates, reads, updates and deletes files under /memories, and those files persist between sessions. The tool runs on the client. Claude requests file operations, and your handler carries them out against storage you control, such as a per-user directory or keys in a database. A handler must reject any path outside /memories.

    The memory tool enabled together with tool-result clearingpython
    response = client.beta.messages.create(
        model="claude-opus-5-5",
        max_tokens=4096,
        messages=[{"role": "user", "content": "Hello"}],
        tools=[{"type": "memory_20250818", "name": "memory"}],
        betas=["context-management-2025-06-27"],
        context_management={"edits": [{"type": "clear_tool_uses_20250919"}]},
    )

    For a multi-day project, set up the memory files deliberately rather than writing them ad hoc. Without them, an agent can spend each morning re-exploring the repository and reopening design decisions it already made. The recovery pattern has three parts:

    1. An initializer session creates a progress log, a feature checklist, and a pointer to any startup script before substantive work starts.
    2. Every later session opens by reading those files. That restores state without re-exploring the code base or retracing decisions.
    3. Before a session ends, it updates the progress log with what was finished and what remains.

    Work on one feature at a time, and mark it done only after end-to-end verification. That keeps the log trustworthy.

    Memory works alongside the other strategies, not instead of them. Combined with tool-result clearing, Claude gets an automatic warning as context nears the clearing threshold, so it can write important results to memory before they are removed. Combined with compaction, compaction keeps the working context small, and memory holds whatever must survive summarization.

    Checkpoint 7 of 9· Put it in order

    A coding agent works on one project over several days, and each day starts a new session with an empty message history. Put the steps of the memory-based recovery pattern in the order a well-run project follows them.

    1. 1.The session works on one feature and marks it done only after end-to-end verification
    2. 2.An initializer session creates a progress log, a feature checklist and a pointer to the startup script before substantive work begins
    3. 3.A later session opens by reading those memory files to restore the project state
    4. 4.Before the session ends, it updates the progress log with what was finished and what remains

    Checkpoint 8 of 9· Exam question

    A Messages API agent migrates a legacy codebase over roughly two weeks of daily sessions. Every session starts with an empty message history, and engineers report that each morning the agent re-explores the repository and repeats earlier design decisions. Accuracy matters more than first-turn latency. Which context lifecycle strategy addresses the problem?

    Sources63

    6.Matching the strategy to the workload

    Start from the workload's constraints. Session length decides whether you need anything beyond a single conversation. The latency requirement decides whether the agent can wait while a summary is written. The accuracy requirement decides how much loss you can accept from summarizing or clearing. Effort is set alongside all of this, using the measured sweep described earlier, because a long agent at max effort fills its context faster than one at medium.

    Workload constraint and the context lifecycle strategy that fits it
    Workload constraintStrategyWhy
    One long conversation that can pause brieflyOn-demand compaction, or compaction at a token threshold for the least codeSummarizes older turns so the task fits in the window
    One long conversation that must never stallOn-demand compaction in the backgroundWork continues on the full history until the summary block is swapped in
    Heavy tool output that is disposable once usedclear_tool_uses_20250919 plus the memory toolRemoves stale results; the pre-clearing warning lets Claude save what matters
    Thinking blocks crowding the windowclear_thinking_20251015 with a chosen keepTrades cache hits against window space
    Work spanning sessions that start emptyMemory tool with initializer, read and update stepsOnly memory files persist between sessions
    Precise recall of early details or exact state across many variablesAvoid relying on compaction; keep facts in memory filesSummaries are lossy for this kind of state

    Two common combinations are worth knowing. A research agent that runs for hours in one conversation, with a strict accuracy bar on cited identifiers, should use background on-demand compaction with a custom summary prompt, and also write identifiers to memory. A coding agent that works in daily sessions needs the memory protocol first. Within each session it can add tool-result clearing, with exclude_tools covering any tool whose output must stay visible. To check what clearing will save before you commit to it, the token-counting endpoint accepts context_management and returns both the count after clearing and the original count.

    Checkpoint 9 of 9· Match them up

    Match each workload constraint to the context lifecycle strategy that fits it.

    Tap a term, then the definition that fits it.

    Sources3

    Practise it for real

    Use the token-counting endpoint to measure what tool-result clearing would save on a real agent transcript before you enable it.

    1. 1.Take a long agent transcript with many tool results and call client.beta.messages.count_tokens with betas=["context-management-2025-06-27"] and a clear_tool_uses_20250919 edit with trigger 30000 input tokens and keep 5 tool uses.

      Why: The counting endpoint applies context management, so you can see the effect without running the agent.

      You should see: A response with input_tokens and context_management.original_input_tokens.

    2. 2.Subtract input_tokens from original_input_tokens.

      Why: The difference is the number of tokens clearing would remove on this request.

      You should see: A positive saving when the transcript exceeds the trigger, and zero when it doesn't.

    3. 3.Add clear_at_least with a value larger than the saving you measured and count again.

      Why: clear_at_least stops clearing when the saving is too small to justify invalidating the prompt cache.

      You should see: input_tokens equals original_input_tokens, because the strategy wasn't applied.

    Stuck? Get a nudge

    If the saving is small, raise the trigger or lower keep before accepting the cache cost.

    Sources

    (6)

    Every claim above is drawn from one of these pages, quoted as it was written on the date shown.

    1. 1.
      “Because effort applies to every output token, it works with or without thinking. Lower effort also means fewer and terser tool calls.”
      ↩︎ Effort controls how much Claude spends per turn
      “Claude Opus 5.5 and Claude Haiku 5.5 default to medium.”
      ↩︎ Effort controls how much Claude spends per turn
      “Requests that set thinking: {"type": "disabled"} return a 400 error at every effort level.”
      ↩︎ Effort controls how much Claude spends per turn
      “Long-running agentic and coding tasks (over 30 minutes) with token budgets in the millions”
      ↩︎ Effort controls how much Claude spends per turn
      “For chat and other latency-sensitive work, start with medium or low.”
      ↩︎ Tuning effort against a latency target
      “To have the model respond without thinking first, send thinking: {"type": "between_tools"}, not "disabled".”
      ↩︎ Tuning effort against a latency target
      “Run a fresh effort sweep on your evals rather than carrying over the setting you used on Claude Sonnet 5.”
      ↩︎ Tuning effort against a latency target
      “Effort controls thinking volume, not visible response length”
      ↩︎ Tuning effort against a latency target
      “In long agent prompts, the model is more likely to skip a search, stop early, or skip a check at low.”
      ↩︎ Tuning effort against a latency target
      “With between_tools, effort can’t change mid-conversation: a per-message output_config.effort at a different level returns a 400 error.”
      ↩︎ Checkpoint
    2. 2.
      “remove budget_tokens, set thinking: {type: "adaptive"}, and control reasoning depth with output_config: {effort: ...} instead of a token budget.”
      ↩︎ Tuning effort against a latency target
      “remove budget_tokens, set thinking: {type: "adaptive"}, and control reasoning depth with output_config: {effort: ...} instead of a token budget.”
      ↩︎ Exam trap 1
    3. 3.
      “The API replaces each cleared result with placeholder text indicating to Claude that it was removed.”
      ↩︎ Clearing tool results and old thinking
      “Context editing is applied server-side before the prompt reaches Claude.”
      ↩︎ Clearing tool results and old thinking
      “Invalidates cached prompt prefixes when content is cleared.”
      ↩︎ Clearing tool results and old thinking
      “Avoid compaction when using server-side tools extensively.”
      ↩︎ Compaction for one long conversation
      “Claude receives an automatic warning to preserve important information.”
      ↩︎ Memory for work that spans sessions
      “Tasks requiring precise recall of early conversation details”
      ↩︎ Matching the strategy to the workload
      “The token counting endpoint supports context management, allowing you to preview how many tokens your prompt will use after context editing is applied.”
      ↩︎ Matching the strategy to the workload
      “context is a finite resource with diminishing returns, and irrelevant content degrades model focus.”
      ↩︎ Key concept
      “Context editing is applied server-side before the prompt reaches Claude.”
      ↩︎ Exam trap 4
      “Your client application maintains the full, unmodified conversation history. You do not need to sync your client state with the edited version.”
      ↩︎ Checkpoint
    4. 4.
      “Compaction replaces the older turns of a conversation with a summary that Claude writes on the server”
      ↩︎ Compaction for one long conversation
      “Write your own summarization prompt: when the default summary drops something a later turn needs. Your prompt replaces the default one.”
      ↩︎ Compaction for one long conversation
      “No: it runs inside the request that reaches the threshold”
      ↩︎ Exam trap 2
      “Compaction in the background: when the conversation can’t pause for the summary.”
      ↩︎ Checkpoint
    5. 5.
      “the compaction request runs while the conversation continues on its full history, and the swap waits until the block arrives.”
      ↩︎ Compaction for one long conversation
    6. 6.
      “Claude can create, read, update, and delete files that persist between sessions”
      ↩︎ Memory for work that spans sessions
      “The memory tool operates client-side: Claude requests file operations, and your application runs them.”
      ↩︎ Memory for work that spans sessions
      “compaction keeps the active context small without client-side bookkeeping, and memory preserves the information that must survive summarization.”
      ↩︎ Memory for work that spans sessions
      “Each new session opens by reading those memory files.”
      ↩︎ Exam trap 3
      “Each new session opens by reading those memory files. This restores the project state without re-exploring the code base”
      ↩︎ Checkpoint

    Ready to test yourself?

    Practise Anthropic Claude Certified Architect – Professional (CCAR-P) - December 7 onwards in quiz mode.

    Spotted a mistake, or was something unclear? Tell us.