deniz.in

Markets

Weather

Loading weather

· via dev.to (home feed)

Upgrading to Claude Sonnet 5.5: request, thinking and tool changes beyond the model ID

A dev.to guide by the Tokenhot Team details the request fields, thinking profiles and tool-choice behavior that change when moving integrations to claude-sonnet-5-5 — and why gateway docs alone prove little.

Upgrading to Claude Sonnet 5.5: request, thinking and tool changes beyond the model ID

A walkthrough published on dev.to by the Tokenhot Team argues that most of the work in moving to Claude Sonnet 5.5 happens after the model string changes. The authors split a migration into three independent reviews — the request your application sends, the response handling it depends on, and the outcome users receive — because each layer fails differently when only the model identifier changes. The guide addresses standard Messages API integrations (text requests, client-side tools, structured output) and excludes computer-use setups and Anthropic's Managed Agents, which it says follow different migration rules. It also notes its own request samples were validated offline only.

Audit the outgoing request first

The first step is capturing a redacted copy of a real outgoing request — taken after SDK defaults, client presets and middleware have been applied — and logging its model, protocol, endpoint, SDK version and beta headers. A configuration screen can claim one thing while another layer quietly injects stale settings. Keep the original capture untouched so a later failure can be blamed on the model change rather than on a second edit.

Against that baseline, the guide lists concrete substitutions. Use the exact identifier for your provider, claude-sonnet-5-5 on the native Claude API. Drop a manual thinking setup (type enabled plus budget_tokens) in favor of adaptive thinking with an explicit effort level. Strip inherited temperature, top_p and top_k, since non-default values are rejected. Move an assistant prefill on the last message into the prompt or a supported output schema, and prefer output_config.format over a raw output_format field. The cleanup load depends on the starting point: an integration coming from Sonnet 4.5 carries more legacy behavior than one already on Sonnet 5.

Choose a thinking profile deliberately

Sonnet 5.5 enables adaptive thinking by default, according to the guide. To avoid up-front thinking, the documented option is between_tools — the older disabled value no longer serves that purpose. In that mode, effort accepts low, medium or high; the thinking object may contain only type; controls such as display, budgets or bindings are not permitted; and effort must stay constant within a conversation.

A sample request in the article combines the new model identifier, a max_tokens cap, a between_tools thinking object and medium effort. The authors flag two caveats: the 1024-token cap is a testing convenience rather than production guidance, and effort is a workload control, not a conversion formula for an old token budget — only regression results show whether a chosen level suffices. Setting effort explicitly also prevents later runs from silently picking up a different default.

Tool choice changes break control flow

Sonnet 5.5 rejects the forced tool_choice values any and tool, the guide reports. Replacing them with auto is not behavior-neutral: the model may reply with plain text instead of a call, so applications need an explicit branch for a missing tool invocation. Where the platform supports it, strict: true constrains a tool's arguments to its schema, but it does not force the tool to run — and the setting should not be copied onto routes that lack support, with the guide citing a Bedrock exception in Anthropic's migration notes.

The authors advise testing tool selection and argument validity as separate acceptance criteria. A syntactically valid JSON response is not a successful tool round trip if the application needed a lookup performed, and an API rejection does not prove the tool implementation failed, since the tool may never have been invoked.

Parse response blocks, not positions

On the response side, the guide warns against assuming the first content block is text. Keep the original content array for conversation replay and derive a display string separately by filtering for text blocks; callers must still inspect the stop reason and route tool calls or incomplete outcomes themselves. An apparently empty thinking field is not automatically broken: the default display can omit thinking text while signed blocks are preserved, and progress notes may appear in thinking blocks rather than ordinary text. Display problems should not be fixed by editing signatures or reconstructing the assistant turn.

Documentation is not acceptance

For teams routing through a third-party gateway, the article closes with a ladder of evidence. A model listing and a basic endpoint example establish only a documented entry point; source-level support shows an implementation path; a successful authorized request proves acceptance for that account at that time; and only a regression suite reconciled with billing records demonstrates broader workload behavior and cost. The authors note that their own gateway reference still names an older Sonnet model in its example response, which they say is neither proof of misrouting nor grounds for inferring aliases — and they caution against sending a Messages JSON body to an OpenAI-shaped endpoint merely because both carry the same model label.

Why it matters

An upgrade that looks like a one-line change can shift semantics in several places at once: sampling parameters that were previously tolerated now fail requests, removed tool forcing changes control flow, and new thinking defaults alter latency and cost. The guide's value is turning a vague migration into a testable checklist: capture the real request, rework thinking and tool configuration, verify response parsing, and demand route-level evidence before shipping. For anyone upgrading an existing Claude integration, or evaluating a gateway that claims to serve the new model, that discipline separates a staged migration from a production surprise.

  • #anthropic
  • #claude
  • #api-migration
  • #llm
  • #developer-tools

Related posts