Agent Upstart

Cool things people are building with agents — and practical help getting the most out of them.

Playbooks · Coding tasks

Claude API effort control: change gear mid-stream

Written November 12, 2026

A beta API control lets you raise or lower Claude's effort between messages — trading speed, thoroughness and cost inside one agent run.

The dial itself

On the Claude API, effort is set with output_config.effort on the request. Anthropic's effort documentation describes it as the control for how many tokens Claude spends on a response, trading thoroughness against token efficiency on a single model. There are five levels: low, medium, high, xhigh, and max. Most models default to high; Claude Opus 5.5 and Claude Haiku 5.5 default to medium. Not every model that supports max supports xhigh.

Effort applies to every output token, including text, tool calls and their arguments, and thinking when it is active, so it works with or without thinking. At lower levels Claude makes fewer and terser tool calls and proceeds to action with less preamble; at higher levels it explains the plan, makes more tool calls, and writes fuller summaries. Because the spend is tokens, effort is a cost control as much as a quality one: the documentation publishes no per-level token multiplier, so the saving from dropping a level is something to measure on your own workload, not a figure to budget from a table.

The beta: change it between messages

The new part is changing the level partway through one conversation without breaking the prompt cache. The per-message effort documentation gives three steps:

  1. Add a role: "system" message to messages, with empty content and the new level in output_config.effort.
  2. Send the beta header mid-conversation-output-config-2026-07-01.
  3. Leave the top-level output_config.effort value unchanged.

Put the message after everything you have already sent, and keep it in place on later requests. Do not insert it before turns already sent, and do not move or remove it later. The new level stays in effect until a later message changes it.

When the new level starts

The message's position decides when the change bites, and the rule is not retroactive. Placed directly after a user turn with new input, the new level governs Claude's reply to that turn. Placed anywhere else, such as between an assistant turn and the next user turn, it starts at the next user turn with new input. A user turn that holds only tool_result blocks does not count as new input, so a change dropped into the middle of a tool loop waits for the next real user message, and everything already generated keeps the level it was written at.

The alternative — setting a new top-level value on the next request — applies to the whole request, but top-level effort shapes the rendered prompt, so changing it between requests can invalidate all or part of the cached prefix. Anthropic's guidance is to prefer the per-message change where the model supports it, and otherwise to pick a level at the start of a cached conversation and hold it constant.

Who can use it

Per-message effort is a beta on the Messages API and Managed Agents, for Claude Fable 5.2 and 5.1, Mythos 5.2 and 5.1, Opus 5.5 and Opus 5, Sonnet 5.5, and Haiku 5.5. The failure modes are plain errors: without the beta header, a per-message output_config returns a 400 error; with the header, a model without per-message support returns a 400 saying so. On Sonnet 5.5 with between_tools thinking, and on Haiku 5.5 with thinking disabled, the level cannot be changed mid-conversation at all; there, varying effort per turn means using adaptive thinking.

Limits

Related playbooks

Sources

Back to: Coding playbooks hub · Also: Token cost calculator