Anthropic Python SDK v1.0: What Breaks and How to Migrate

The Anthropic Python SDK v1.0 landed on August 20, 2026, and the release-notes entry is blunt about what it is: the HTTP layer moves from httpx to httpx2, the package now requires Python 3.10 or later, and a set of long-deprecated surface is removed outright — the legacy Text Completions API, the temperature, top_p and top_k parameters on Messages methods, and the tool runner’s client-side compaction_control.

The easy compression of that list is “Anthropic removed sampling controls.” It did not. The Messages API reference still documents and accepts all three parameters, and the SDK ships a documented workaround. What actually changed is one layer deeper: seven current Claude models reject any non-default sampling value with a 400 regardless of how the request reaches them. The SDK removal lands alongside that model-level rule, and the workaround only buys you anything on older models. That distinction is the whole story, and this guide leads with it.

Below: what shipped and what did not (this is Python only), the sampling split by model, a migration matrix with before-and-after code for every breaking change in the SDK’s own MIGRATION.md, the one change that can break a running agent loop with nothing raised, the instrumentation that quietly stops seeing your Anthropic calls alongside it, the Bedrock construction that now fails at startup instead, and a real hold-back pin for teams that cannot move today.

The v1.0.0 tag on anthropic-sdk-python was published on August 20, 2026 at 19:58 UTC, and its Conventional-Commits body is almost comically short: a single BREAKING CHANGES line pointing at the httpx2 upgrade and “some minor breaking changes,” a bug fix that stops the helpers warning about output_format=, and a chore restoring the original streaming-event imports. Everything of substance lives in MIGRATION.md, which the release notes name as the canonical source “for every change with before-and-after snippets.”

Read the timing alongside the last 0.x release and the shape of the event becomes clear. v0.125.0 went out on August 19 at 22:00 UTC — less than a day earlier — carrying managed-agents web-search configuration and self-hosted-sandbox memory-store support, none of it migration-related. v1.0 adds no comparable capability. It is the moment Anthropic chose to cash in a backlog of deprecations at once, which is exactly what a major version is for under the SemVer policy in Anthropic’s own Python SDK docs: the package “generally follows SemVer,” with the caveat that some backward-incompatible type-only or internal changes may ship as minor versions.

Three scope notes matter before you touch anything. First, this is the Python anthropic package only. The TypeScript SDK’s GitHub Releases show v0.120.0 (August 19) as the newest entry and no v1.0.0 tag exists there. Second, it is separate from the Aug-19 wave that moved computer use, browser use, the Files API, Agent Skills and Admin API user management to GA — our post on that GA wave covers it and nothing in it is restated here. Third, this is not Claude Code, which has its own changelog and version line.

Anthropic’s own install line for the new major is pip install --upgrade "anthropic>=1,<2". The upper bound is the point: it lets you take future 1.x releases without being carried into a future 2.0 by a loose constraint. The rest of this post assumes you are deciding whether to run that command this week or pin and schedule it.

Here is the sentence that is easiest to get wrong. MIGRATION.md removes temperature, top_p and top_k from the typed method signatures of messages.create(), messages.stream() and messages.parse(). The Messages API reference still lists all three as optional number fields with full descriptions — defaults, ranges, the nucleus-sampling explanation. Nothing on that page says they were removed from the API. The SDK dropped the parameters; the wire protocol did not.

The documented escape hatch is extra_body, and MIGRATION.md gives the before-and-after itself:

# Before (0.x): typed keyword argument
message = client.messages.create(
    model=MODEL,
    max_tokens=1024,
    temperature=0.2,
    messages=[{"role": "user", "content": "Summarise this contract."}],
)

# After (1.x): pass it through to the request body
message = client.messages.create(
    model=MODEL,
    max_tokens=1024,
    extra_body={"temperature": 0.2},
    messages=[{"role": "user", "content": "Summarise this contract."}],
)

So far, an SDK-only story, and the release notes give it a one-line rationale: v1.0 “removes long-deprecated surface.” What makes it more than a signature change sits in a different document entirely. The Thinking docs’ “Limits and feature compatibility” section — evergreen reference documentation describing the current model line, not an August 20 announcement — states the model-level rule that makes the workaround moot for most production traffic:

Put the two documents together and the picture is exact. Seven current models hard-reject any non-default sampling value, through the SDK, through raw HTTP, with thinking on or off. On those models, extra_body={"temperature": 0.2} produces the same 400 the typed argument would have. There, the SDK removal takes away nothing the API would have honoured — the typed surface and the model behaviour now agree. extra_body exists for the older models where sampling is still honoured, and for default values everywhere. The table below is that rule extracted into something you can scan.

The practical consequence for a migration: grep your codebase for the three parameter names before you upgrade, and sort each hit by the model it targets. Hits against the seven current models were already failing or were sitting at default values — delete them. Hits against older models move to extra_body, with a comment naming the model dependency, because the moment that call is repointed at a current model it becomes a 400 in production. Teams that went through our Opus 4.6 to 4.7 migration playbook will recognise the shape: the model boundary, not the SDK boundary, is where sampling assumptions break.

MIGRATION.md documents each change but never says whether it is confined to the SDK or reflects something at the API or model layer. That column is the synthesis this table adds. “SDK-only” means a raw HTTP caller is unaffected; “SDK + model” means the behaviour you hit is enforced below the SDK; “client to server” means a capability moved rather than disappeared; “SDK client removed” means the typed wrapper is gone and MIGRATION.md does not state what the underlying endpoint does. The last column is the minimum action if you pin to 0.125.0 instead of migrating.

Fifteen rows, and only one of them — sampling — is enforced at the model layer. One more, compaction, moved to a server-side beta rather than vanishing. That ratio is the reassuring part of the release. It also tells you where to spend review time: the “Behaviour changes” rows deserve a test each, and so does the HTTP-layer row, because the changes that fail quietly give you nothing to grep for, while the renames and the removed-surface rows announce themselves at import or at the first call. The sections below take them in turn.

MIGRATION.md explains the transport move in one line: the SDK’s HTTP layer moved from httpx, “which is no longer actively maintained,” to httpx2. The httpx2 project on PyPI is stewarded by Pydantic Services Inc., whose pydantic/httpx2 repository hosts the fork, with original-author continuity from Tom Christie, httpx’s creator, and its current release at the time the SDK shipped was 2.12.0 from August 18 — two days earlier. The PyPI description is explicit about the motive: “With HTTPX itself seeing limited activity recently, Pydantic is picking up stewardship under the HTTPX2 name so that users have a reliably maintained path forward — including timely security updates.”

Notice what Anthropic does not say. Neither the release notes nor the SDK docs call httpx2 “the official successor” or claim an endorsement from the httpx maintainers. The release notes say “a maintained, API-compatible fork”; the SDK docs page, in its “Configuring the HTTP client” section, independently says “an API-compatible fork of httpx.” Neither phrase carries an endorsement, and that restraint is the accurate version — it is the one to repeat in your change ticket.

For most codebases the change is invisible, because the default client is built for you and the DefaultHttpxClient helpers are unchanged. You have work to do in two situations: you construct your own http_client, Timeout or transport objects from httpx, or you run tracing or mocking libraries that patch httpx by module name.

# Before (0.x): custom client built from httpx
import httpx
from anthropic import Anthropic

client = Anthropic(
    http_client=httpx.Client(proxy="http://proxy.internal:3128"),
    timeout=httpx.Timeout(60.0),
)

# After (1.x), option A: build the same objects from httpx2
import httpx2 as httpx
from anthropic import Anthropic

client = Anthropic(
    http_client=httpx.Client(proxy="http://proxy.internal:3128"),
    timeout=httpx.Timeout(60.0),
)

# After (1.x), option B: make plain `import httpx` resolve to httpx2.
# Call this once at process startup, before any library imports httpx.
import httpx2

httpx2.alias_httpx()

Option B is the one that matters for observability and test suites. MIGRATION.md names the category — libraries that patch httpx directly — and the usual suspects are respx, pytest-httpx, OpenTelemetry’s HTTPXClientInstrumentor and Sentry’s httpx integration. Without the alias, those tools keep instrumenting a module the SDK no longer uses, and the failure mode is silent: tests pass against a mock that never fires, traces stop showing Anthropic spans, and nobody gets an exception. Put httpx2.alias_httpx() in the same bootstrap that configures tracing, and add one test that asserts an Anthropic call appears in your span exporter.

The loudest removal is the legacy Text Completions client. client.completions.create() — the SDK’s wrapper for the /v1/complete endpoint — is gone, and so are the anthropic.HUMAN_PROMPT and anthropic.AI_PROMPT constants that built its prompt strings. Any module that still imports them fails at import time on 1.x, which at least makes this the easiest break to find. The fix is the port to Messages that has been the documented path for a long time.

# Before (0.x): legacy Text Completions
from anthropic import AI_PROMPT, HUMAN_PROMPT, Anthropic

client = Anthropic()
completion = client.completions.create(
    model=MODEL,
    max_tokens_to_sample=300,
    prompt=f"{HUMAN_PROMPT} Summarise this contract.{AI_PROMPT}",
)
text = completion.completion

# After (1.x): Messages
from anthropic import Anthropic

client = Anthropic()
message = client.messages.create(
    model=MODEL,
    max_tokens=300,
    messages=[{"role": "user", "content": "Summarise this contract."}],
)
text = message.content[0].text

The Python floor is the quieter removal, and the one with the longest lead time. MIGRATION.md states it plainly — “The minimum supported Python version has increased from 3.9 to 3.10” — and PyPI’s metadata for anthropic 1.0.0 confirms it independently with Requires-Python: >=3.10 and classifiers for 3.10 through 3.14 only. A pip resolver on a 3.9 interpreter will simply refuse to select 1.0.0, which is polite, but it also means a service that pins anthropic loosely on 3.9 will stay on 0.x forever without telling anyone. Add an explicit upper bound so the intention is visible in the lockfile.

This is the change most likely to break a running agent loop without raising anything. On 0.x, the tool runner accepted a client-side compaction_control argument that compacted context locally once a token threshold was crossed. On 1.x that argument is removed, and the replacement is the server-side context_management feature behind the compact-2026-01-12 beta. Same job, different layer, and one new constraint: MIGRATION.md notes the trigger threshold must be at least 50,000 tokens.

# Before (0.x): client-side compaction
runner = client.beta.messages.tool_runner(
    model=MODEL,
    max_tokens=4096,
    tools=TOOLS,
    messages=history,
    compaction_control={"enabled": True, "context_token_threshold": 100_000},
)

# After (1.x): server-side context management (beta)
runner = client.beta.messages.tool_runner(
    model=MODEL,
    max_tokens=4096,
    tools=TOOLS,
    messages=history,
    betas=["compact-2026-01-12"],
    context_management={
        "edits": [
            {
                "type": "compact_20260112",
                "trigger": {"type": "input_tokens", "value": 100_000},
            }
        ]
    },
)

Why it fails quietly: a loop that relied on local compaction and simply drops the argument keeps running, keeps accumulating context, and only surfaces a problem when it hits a context limit or a cost alarm many turns later. Two checks catch it. First, an integration test that drives a loop past the old threshold and asserts the compaction edit appears in the response. Second, a config lint that refuses any trigger value below 50,000 — the floor is documented, and a threshold copied over from an old client-side config can sit below it, which was fine locally and is rejected server-side now.

If your agent loop lives in the Claude Agent SDK rather than in the Python SDK’s tool runner, this section does not apply to you directly — the Agent SDK has its own migration playbook, and our production-patterns guide covers context management on that side.

On 0.x, constructing AnthropicBedrock or AsyncAnthropicBedrock with no region configured silently fell back to us-east-1. On 1.x, MIGRATION.md documents that the same construction raises a ValueError instead. The resolution order is explicit: an aws_region= constructor argument first, then the AWS_REGION or AWS_DEFAULT_REGION environment variables, then the boto3 profile configuration. If none of those yields a region, the client refuses to start.

The SDK docs frame this class carefully: AnthropicBedrock is retained for existing applications on the Bedrock InvokeModel path, while AnthropicBedrockMantle is the recommended class for new Bedrock projects. The region change is about the legacy class, which is precisely the one most likely to be sitting in an older service with a minimal constructor call.

The design call is the right one. A client that quietly routes production traffic to a region nobody chose is a data-residency incident waiting for an auditor, and the old default made that the path of least resistance. The cost is a one-time startup failure in any environment that relied on it — which is why the explicit constructor argument is worth landing this week even if the SDK upgrade itself waits.

The remaining changes are mechanical, but two of them hide in code that runs rarely. On the async client, .with_raw_response results now require await response.parse() where 0.x allowed a synchronous .parse(). The .text and .content properties on raw responses became methods — response.text() and response.read() — and the response gains directly accessible json(), iter_bytes(), iter_text() and iter_lines().

# Before (0.x): async raw response
response = await client.messages.with_raw_response.create(**params)
message = response.parse()
request_id = response.headers.get("request-id")
body = response.text

# After (1.x)
response = await client.messages.with_raw_response.create(**params)
message = await response.parse()
request_id = response.headers.get("Request-Id")  # names are case-insensitive now
body = response.text()

Headers are the second quiet one. Names are now case-insensitive, which is a loosening, but raw bytes values now raise and must be decoded to str first — a tightening that lands on whichever middleware stuffs a signed token into a header without decoding it. Structured output is the third: passing a raw schema dict as output_format= is removed from message methods in favour of output_config={"format": {...}}, and the parse(), stream() and count_tokens() helpers accept only types for output_format=. Finally, messages.parse(stream=True) is gone, which MIGRATION.md notes “never worked” — use messages.stream() with output_format= and read stream.get_final_message().parsed_output.

None of these justify delaying the migration on their own. They do justify running the migration on a branch with the full test suite, rather than bumping the version in a dependency-update bot and merging on green, because raw-response code and header middleware are exactly the paths most suites do not exercise.

The hold-back pin is a real, currently installable version, not a guess: anthropic==0.125.0, the last 0.x release, published on August 19 and still on PyPI. The looser form anthropic>=0.125,<1 does the same job while leaving room for any further 0.x uploads. Either way, a pin is a dated exception with an owner, and the table below is the decision behind it: the symptom that forces the pin, the pin itself, how much pressure sits behind the deadline, and what changes when you do migrate.

The last row is the one to internalise. Pinning protects you from SDK-level changes; it does nothing for a behaviour the model enforces. That is the general lesson of a 1.0 like this one, and it maps onto the framework in our API versioning decision matrix: a client library’s major version is a contract about the typed surface, and the typed surface can be narrower than the wire protocol or wider than what a given model honours. When the three disagree, the model wins, and your tests should be written against the model.

Looking forward, the direction of travel is not hard to read. Anthropic’s typed surface and the sampling restriction on its current models now agree, the Agent SDK and Codex CLI have both been through their own config migrations this summer — Codex’s was a config-schema move rather than a transport swap — and the pattern across vendors is that SDK majors are increasingly the place where deprecations get enforced rather than announced. The teams that cope best keep a single adapter module around each vendor client, so the next major touches one file. If you are building or operating agentic systems on Claude and want that adapter layer designed before the next migration rather than during it, our AI transformation engagements start with exactly that audit, and our web development team handles the runtime and dependency upgrades that usually come bundled with it.