Anthropic Python SDK 1.0: migrar à mão ou com Claude Code

Migrar um projeto Python do anthropic 0.x para o 1.0 leva um comando de instalação, pip install --upgrade "anthropic>=1,<2", e depois uma passada por uma lista fixa de mudanças incompatíveis: a camada HTTP agora roda sobre o httpx2, os leitores assíncronos de .with_raw_response viraram corrotinas, o Text Completions e os parâmetros temperature/top_p/top_k sumiram, e o AnthropicBedrock se recusa a ser construído sem uma região.¹ Percorra essa lista à mão com o guia oficial de migração, ou deixe o Claude Code fazer as edições com /claude-api upgrade python e revise o diff.¹³ A nota de lançamento do Claude Code chama o comando de /claude-api upgrade; o guia de migração acrescenta o argumento python, que é a forma a digitar.¹³ Os dois caminhos terminam no mesmo lugar – a página abaixo cobre cada um deles, atualizada em relação ao anthropic 1.0.0 (lançado no PyPI em 20 de agosto de 2026; verificado em 25 de agosto).² {.answer-block}

TL;DR

• Atualize com pip install --upgrade "anthropic>=1,<2" e depois rode pyright ou mypy: o guia de migração observa que um verificador de tipos aponta quase todas as mudanças incompatíveis, o que o transforma em um checklist pronto.¹
• Python 3.10 é o novo piso. Nada mais no seu ambiente muda; o SDK continua suportando Pydantic v1 e v2.¹
• httpx virou httpx2. Valores simples como timeout=30.0 continuam funcionando; objetos httpx que você entrega ao cliente precisam vir do httpx2, e bibliotecas que fazem patch no httpx ficam cegas até você chamar httpx2.alias_httpx().¹
• Removidos: Text Completions, parâmetros de amostragem e dicts de schema em output_format. client.completions.create(), temperature, top_p e top_k sumiram; dicts de schema passam para output_config={"format": {...}}.¹
• O Claude Code v2.1.239 (21 de agosto de 2026) adicionou /claude-api upgrade para migrar projetos Python do anthropic 0.x para o 1.x.³ Trate a saída dele como qualquer migração automatizada: leia o diff antes de fazer o commit.

O que quebra quando eu atualizo para o anthropic 1.0?

Seis mudanças carregam a maior parte do peso; condenso a referência rápida do guia nessas seis, e as remoções menores vêm em seguida.¹ A maior delas tem um motivo simples: a camada HTTP do SDK saiu do httpx, que não é mais mantido ativamente, para o httpx2, um fork compatível em API mantido pela equipe do Pydantic, com as mesmas classes, o mesmo comportamento e correções de segurança incluídas.¹

Remoções menores e uma mudança de comportamento vêm junto, cada uma com sua substituição:¹

A última linha morde em silêncio: default_headers={"USER-AGENT": "my-app/1.0"} agora substitui o User-Agent do próprio SDK em vez de enviar os dois.¹

Como migro à mão?

Três passos, nesta ordem: atualize, deixe o verificador de tipos encontrar o que quebrou e depois corrija por categoria.

pip install --upgrade "anthropic>=1,<2"
pyright   # or mypy

Corrija primeiro os imports de httpx, porque eles falham mais alto. As re-exportações do próprio SDK (anthropic.Timeout, anthropic.DefaultHttpxClient, anthropic.DefaultAsyncHttpxClient, anthropic.DefaultAioHttpClient) já apontam para o httpx2 e continuam funcionando; só os objetos que você constrói diretamente a partir do httpx precisam do alias.¹

# Before
import httpx
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    timeout=httpx.Timeout(60.0, connect=5.0),
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

# After
import httpx2 as httpx  # or `import httpx2` and rename the references
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    timeout=httpx.Timeout(60.0, connect=5.0),
    http_client=DefaultHttpxClient(
        proxy="http://my.proxy.example",
        transport=httpx.HTTPTransport(local_address="0.0.0.0"),
    ),
)

Se outro código na aplicação ainda importa httpx e compartilha clientes ou tipos de exceção com o SDK, ou se você roda o HTTPXClientInstrumentor do OpenTelemetry, a integração httpx do Sentry, respx, pytest-httpx ou vcrpy, chame httpx2.alias_httpx() uma vez no topo do seu ponto de entrada. Ela precisa rodar antes de qualquer coisa importar httpx (caso contrário lança RuntimeError), e o guia a reserva para aplicações: uma biblioteca nunca deve chamá-la em nome dos seus usuários.¹ No pytest, a opção menos intrusiva do guia é um plugin carregado cedo, um módulo tests/_alias_httpx.py que chama httpx2.alias_httpx(), registrado no pyproject.toml para carregar antes do respx, do pytest-httpx e dos seus módulos de teste:¹

# tests/_alias_httpx.py
import httpx2

httpx2.alias_httpx()  # makes `import httpx` / `import httpcore` resolve to httpx2 / httpcore2

# pyproject.toml
[tool.pytest.ini_options]
addopts = "-p tests._alias_httpx"
pythonpath = ["."]

Objetos de resposta e de erro agora são tipos httpx2. A troca de pacote vale para o que o SDK retorna, não só para o que você passa. APIStatusError.response, APIConnectionError.request, response.http_response / .headers / .url em raw responses e o argumento response= que os event hooks do seu http_client customizado recebem são todos objetos httpx2. Eles carregam exatamente os mesmos atributos de antes, então só as verificações isinstance e as anotações de tipo que citam httpx.Response / httpx.Request / httpx.Headers precisam mudar para httpx2.¹ O caso do isinstance merece uma segunda olhada. O guia diz apenas que essas verificações precisam mudar;¹ o motivo de elas importarem é que, a menos que httpx2.alias_httpx() tenha feito httpx resolver para httpx2, uma verificação como isinstance(err.response, httpx.Response) contra o pacote antigo retorna False sem lançar nada, e o handler pula o seu branch.

# Before
def log_failure(err: anthropic.APIStatusError) -> None:
    response: httpx.Response = err.response
    print(response.status_code, response.headers.get("request-id"))


# After
def log_failure(err: anthropic.APIStatusError) -> None:
    response: httpx2.Response = err.response
    print(response.status_code, response.headers.get("request-id"))

Depois, os leitores de raw response. .with_raw_response costumava retornar LegacyAPIResponse para os dois clientes; agora retorna as mesmas classes APIResponse / AsyncAPIResponse que .with_streaming_response já usava.¹

Depois, os parâmetros removidos. Os modelos atuais não usam temperature, top_p nem top_k, então os métodos gerados não os aceitam mais. Um modelo anterior à mudança ainda os honra via extra_body, que o SDK mescla no JSON da requisição como está.¹

# Before
client.messages.create(..., model="claude-sonnet-4-6", temperature=0.2)

# After
client.messages.create(..., model="claude-sonnet-4-6", extra_body={"temperature": 0.2})

Dicts de schema se movem do mesmo jeito: output_format={"type": "json_schema", "schema": ...} em beta.messages.create() vira output_config={"format": {"type": "json_schema", "schema": ...}}; os helpers parse() / stream() / count_tokens() / tool_runner() mantêm output_format=Order para uma classe, e um dict de schema ali agora lança TypeError.¹

Termine com o Bedrock. AnthropicBedrock e AsyncAnthropicBedrock costumavam registrar um aviso e cair para us-east-1; agora lançam ValueError na construção. A região é resolvida a partir de aws_region=, depois de AWS_REGION / AWS_DEFAULT_REGION e depois da sessão boto3 do aws_profile informado.¹ O SDK também passou a ignorar eventos de streaming do Bedrock desconhecidos que antes repassava; o único caso conhecido é amazon-bedrock-invocationMetrics.¹

Como migro com o Claude Code?

O próprio guia de migração aponta o atalho: rode /claude-api upgrade python no seu projeto e revise o diff.¹ O Claude Code v2.1.239, lançado em 21 de agosto de 2026, é onde o comando chegou; a nota de lançamento diz, na íntegra, “Added /claude-api upgrade to migrate Python projects from anthropic 0.x to 1.x, and updated the skill’s Python reference for 1.x (timeouts use anthropic.Timeout, not httpx.Timeout)” (adicionado /claude-api upgrade para migrar projetos Python do anthropic 0.x para o 1.x, e atualizada a referência Python da skill para o 1.x: timeouts usam anthropic.Timeout, não httpx.Timeout).³

Essa frase é toda a superfície verificada: um comando da skill /claude-api que migra o uso de 0.x de um projeto para 1.x. Não encontrei mais nenhuma documentação sobre como ele escolhe as edições, então trate-o exatamente como isso: uma migração automatizada cujo diff você revisa. Atualize para a v2.1.239 ou posterior (claude update, ou a referência de instalação e atualização), abra uma sessão na raiz do projeto e rode:

/claude-api upgrade python

Depois leia o diff hunk por hunk, rode o verificador de tipos e rode a suíte de testes – a mesma revisão que você daria ao PR de migração de um colaborador. O passo do verificador de tipos importa mais do que o normal aqui, porque quase toda quebra do 1.0 é um erro de tipo, e essa verificação não se importa com quem fez as edições.¹ O único detalhe que a nota de lançamento destaca, anthropic.Timeout em vez de httpx.Timeout, bate com o guia: essa re-exportação já aponta para o httpx2.¹³

Novo no Claude Code? O guia rápido cobre a primeira sessão, e o guia completo cobre as skills embutidas e os comandos de barra.

Perguntas frequentes

O anthropic 1.0 ainda suporta Pydantic v1?

Sim. O SDK continua suportando Pydantic v1 e v2; o mínimo de Python 3.10 é a única mudança de ambiente.¹

Por que minha configuração de OpenTelemetry ou respx para de enxergar as requisições do SDK depois da atualização?

Essas bibliotecas fazem patch no httpx, que o SDK não usa mais. Chame httpx2.alias_httpx() antes de qualquer coisa importar httpx; a partir daí, import httpx resolve para httpx2 no processo inteiro.¹

Ainda posso passar temperature para um modelo mais antigo?

Sim, por meio de extra_body={"temperature": 0.2}, que o SDK mescla no JSON da requisição. Para messages.batches.create(), coloque a chave direto no dict params da requisição.¹

O que substituiu a compactação no cliente do tool_runner?

Compactação no servidor: passe betas=["compact-2026-01-12"] e context_management={"edits": [{"type": "compact_20260112", "trigger": {"type": "input_tokens", "value": 100_000}}]} para tool_runner(). No exemplo do guia, esse par substitui compaction_control={"enabled": True, "context_token_threshold": 100_000}; o limiar do trigger precisa ser de pelo menos 50.000 tokens.¹

Preciso tirar o httpx_aiohttp dos requirements?

Sim. anthropic[aiohttp] e http_client=DefaultAioHttpClient() funcionam como antes, mas o extra não instala mais o httpx_aiohttp, porque agora ele vem dentro do SDK.¹

Principais conclusões

Para desenvolvedores de aplicações: - Fixe "anthropic>=1,<2", rode o verificador de tipos e corrija por categoria, nesta ordem: imports de httpx, awaits de raw response, parâmetros removidos, região do Bedrock.¹ - Coloque httpx2.alias_httpx() nas primeiras linhas do ponto de entrada se qualquer outra coisa no processo compartilha objetos httpx com o SDK ou instrumenta o httpx.¹

Para mantenedores de bibliotecas: - Nunca chame httpx2.alias_httpx() dentro de uma biblioteca; em vez disso, use o alias no import (import httpx2 as httpx).¹ - Troque anthropic.Transport / ProxiesTypes por httpx2.BaseTransport / httpx2.Proxy.¹

Para equipes que usam o Claude Code: - Atualize para a v2.1.239 ou posterior e rode /claude-api upgrade python na raiz do projeto; revise o diff e depois rode o verificador de tipos e os testes antes de fazer o commit.¹³

Referências