Anthropic Python SDK upgrade: what to check in your code first

If you call Claude from Python, a few changes between v1.14.0 and v2.5.0 of the Anthropic SDK can alter behavior without breaking your build. Tracing can switch on by itself, two exception classes moved under a parent, and the tool runner callbacks changed. Here is what to switch off, reread and retest.

Switch tracing off if you don't want it

Since v1.14.0 the client has native OpenTelemetry support. If your app registers a global tracer provider, the SDK creates spans with it after you upgrade, and they are exported with the rest of your traces. Requests also get trace context headers from the global propagator.

To disable it, pass open_telemetry=False to the client:

import anthropic client = anthropic.Anthropic(open_telemetry=False) 

Or set the environment variable ANTHROPIC_OPEN_TELEMETRY=false. I'd decide this before upgrading, because nothing in your code tells you it is on.

Reread your exception handlers

In v2.5.0 OverloadedError and ServiceUnavailableError became subclasses of InternalServerError. An except InternalServerError block now catches both. If you handle either one separately in an except that comes after the InternalServerError one, that block may never run, so put the subclasses first.

APIStatusError also gained error_code, details and api_message.

Retest tool runner callbacks

v2.2.0 changed several set_messages_params() behaviors:

• After append_messages(), the history is left to the caller, and the current reply stays out of the set_messages_params() callback.
• The callback gets its tools as definitions again.
• When the callback gives tools as definitions, function tools keep running. A tool the callback takes out of tools stops running.
• betas, user_profile_id and workspace_id stay in place when the callback leaves them out.

If you relied on the SDK managing history after append_messages(), start there.

Check the new input validation

v2.5.0 raises ValueError in the Bedrock client when model is empty, instead of sending the request to /model//invoke. The Bedrock client also raises it for "." or "..". The client now rejects path parameters such as '..;x' and ';x', and Vertex percent-encodes the model, project ID and region in the request path. If a model name comes from config, make sure an empty value fails where you expect.

When I'd upgrade

I'd upgrade soon if you run the tool runner with set_messages_params() or hit the stream errors fixed in v1.14.0, and I'd pin the tracing decision first if you already export traces. Coming from v1, the v2.0.0 entry lists new API version 2026-10-21 support as a breaking change, so read that entry before anything else.