Two contracts change with one package
A team upgrading the Python client to 2.0.0 adopts a new API contract even if it leaves its model call untouched. Anthropic’s new major SDK versions send the 2026-10-21 version header instead of 2023-06-01. That shifts the maintenance task: installing the dependency also requires revisiting requests that the service previously accepted. The migration guide’s advice to ship application changes together with the SDK update makes this coupling explicit.[1]
Sampling controls offer a concrete example. Sending temperature, top_p or top_k now produces a 400 error even when the supplied value matches the former default. Setting temperature to 1 is therefore insufficient; the field must be removed. An older application that omitted sampling controls already used the same default temperature. That distinction separates an experiment intended to change model behavior from maintenance that simply removes an invalid request field.[1]
Conversation history is part of the request, too. Documents directly inside assistant messages must move into user messages, while documents nested in tool results remain permitted. A successful greeting is therefore a weak migration test for an agent that works with documents. The useful test unit is a task request with its history attached. Some integrations already place documents in user messages and may avoid this particular change; that alternative prevents treating every application as needing the same repair.[1]
Run the test through the gateway
Before reaching the service, a request may cross another boundary: the gateway. The new SDK sends the key through Authorization with a Bearer value. The Claude API accepts both authentication headers, but a proxy that only reads X-Api-Key needs adjustment. Acceptance by the API does not establish compatibility in the intermediary. Comparing the same application over a direct connection and the organization’s gateway is consequently a useful way to locate the affected layer.[1]
A practical migration exercise can begin by fixing the tasks accepted by the current deployment: a request carrying document history, a conversation with tool results and the sampling options actually used by the application. The replacement application and SDK can then face those same tasks through the same network path. Track which request fails and which change restores acceptance separately. Otherwise a repaired message format and an adjusted gateway receive credit for the same success, obscuring the mechanism. Deployments that never used the affected fields may face less work.[1]
The value of this approach is that progress can be measured without claiming a speed improvement from the release. Accepted tasks, error categories and the developer review needed for repairs can be compared. For older Bedrock models, retaining the previous SDK and API version also preserves a staged migration option. A useful outcome is an upgrade that explains which layer disrupted an existing task and keeps a route back to the previous deployment. Used that way, the explicit contract gives maintainers a clearer, more inspectable change to manage.[1]