Anthropic Python SDK 1.0: Fix the Silent Observability Break

Anthropic shipped Python SDK v1.0.0 on August 20. Most of the coverage called it a maintenance release. That framing is going to cost people. The headline change — swapping httpx for httpx2 — looks mechanical. What it actually does is silently break every tracing library, APM integration, and mock test suite that patches httpx by module name. Tests keep passing. Production observability goes dark. Nobody finds out until an incident.

What Changed in 1.0

Six breaking changes shipped in this release, ranging from loud (import errors, ValueError at startup) to silent (observability vanishes, agent loops quietly eat context). Here is the full inventory:

• httpx → httpx2 — the HTTP transport layer moves to a Pydantic-maintained fork
• Python 3.10 floor — 3.9 support dropped; systems on 3.9 silently stay on 0.x under loose version constraints
• Text Completions API removed — client.completions.create(), HUMAN_PROMPT, and AI_PROMPT are gone
• Sampling parameters removed — temperature, top_p, and top_k no longer exist on messages.create()
• AnthropicBedrock region required — the constructor raises ValueError instead of silently defaulting to us-east-1
• Tool runner compaction redesigned — compaction_control is gone; server-side context_management replaces it

The loud failures — import errors, ValueErrors, 400s — are straightforward. Find them, fix them, ship. The silent ones are where the real work is.

The Observability Trap

Here is exactly what happens if you upgrade without handling the httpx change:

1. You run pip install --upgrade "anthropic>=1,<2"
2. OpenTelemetry’s HTTPXClientInstrumentor keeps patching the old httpx module — the one the SDK no longer uses
3. Your respx or pytest-httpx mocks intercept zero SDK requests
4. Every test passes because nothing is being checked
5. Your Claude API spans disappear from Datadog, Sentry, or your OTEL collector
6. You find out during a production incident, not before

The fix is one line, called once at process startup before anything else imports httpx:

import httpx2
httpx2.alias_httpx()

If you want the correct fix rather than the quick one, switch to HTTPX2ClientInstrumentor from opentelemetry-instrumentation-httpx. The OpenTelemetry Python contrib package now ships both HTTPXClientInstrumentor (original) and HTTPX2ClientInstrumentor, plus the corresponding async transport wrappers. Update your instrumentation setup, drop the alias, and you are properly instrumented against the transport the SDK actually uses.

One more silent change: passing default_headers={"USER-AGENT": "my-app/1.0"} now replaces the SDK’s User-Agent header entirely instead of appending. If you rely on custom header identification in your API gateway logs, check this.

The Four Loud Ones

The remaining breaking changes announce themselves, which makes them easier to handle.

Python 3.9: If your pyproject.toml or requirements.txt specifies anthropic>=0.100 without an upper bound, pip will try to install 1.0 and fail on 3.9 environments, leaving the old version in place. Pin explicitly until you upgrade Python: anthropic==0.125.0.

Text Completions: If you are still calling client.completions.create(), the import fails immediately. The migration is mechanical — switch to messages.create() and swap completion.completion for message.content[0].text. The harder part is finding all the call sites in older codebases.

Sampling parameters: temperature, top_p, and top_k are gone from the method signatures. On legacy models, you can pass them via extra_body={"temperature": 0.2}. On current models — Fable 5, Mythos 5, Opus 5, Opus 4.8, Opus 4.7, Sonnet 5, Mythos Preview — those parameters return 400 errors regardless of how you pass them. Remove them and let the model use its defaults.

Bedrock region: Add aws_region="your-region" explicitly to AnthropicBedrock() before upgrading. The change is backward-compatible with 0.x, so you can land it as a safe no-op now. The risk is compliance: production services relying on the implicit us-east-1 default could route traffic to the wrong region without anyone noticing.

The Compaction Redesign

If you are running multi-turn agent loops with compaction_control in the tool runner, the old keyword argument is silently dropped on 1.0. Your loop does not error. It accumulates unlimited context across turns until it hits a context limit or triggers a cost alert — which for long-running agents can mean dozens of turns and significant spend before anything surfaces.

The migration adds a server-side beta flag and a context_management block with a minimum 50,000-token threshold. The design is more explicit about when compaction triggers, but it requires a deliberate code change rather than a drop-in replacement. Review the full before/after code comparison before making this change in production.

How to Migrate

For large codebases with many call sites, start with the automated path. Claude Code v2.1.239 added /claude-api upgrade on August 21 — one day after the SDK release — specifically for this migration. It handles mechanical edits: import rewrites, deprecated API removal, parameter cleanup. Always review the diff before shipping, particularly around custom httpx transport wiring and compaction logic.

The manual path is faster for small codebases. Run pyright or mypy immediately after upgrading the package. Almost every 1.0 break is a type error — the type checker catches roughly 60 percent of issues and gives you a prioritized fix list without reading the entire changelog.

If you cannot migrate immediately, pin to anthropic==0.125.0 — the last 0.x release. It remains stable. Just know that the pin does not protect against model-level enforcement: sampling parameters already fail on current Claude models regardless of SDK version.

The Broader Signal

The 1.0 label is not just a version number. This release strips out everything Anthropic has deprecated since 2023. Combined with the tool_choice deprecation from the Claude Fable 5.1 release on September 1, the pattern is clear: Anthropic is rapidly cleaning the API surface as the platform matures. Teams building on Claude API need a migration cadence. The era of accumulating version debt and one-day hotfixes is ending.

Read the official release notes and MIGRATION.md before you ship the upgrade. Then add an assertion to your test suite that verifies tracing spans appear after the change. That assertion is the only reliable way to confirm the observability problem is solved — not assumed.