SDK Python

O SDK Python da Anthropic fornece acesso conveniente à Claude API a partir de aplicações Python. Ele suporta operações síncronas e assíncronas, streaming e integrações com Amazon Bedrock, Claude Platform on AWS, Google Cloud e Microsoft Foundry.

Instalação

pip install anthropic

Para integrações específicas de plataforma ou melhor desempenho assíncrono, instale com extras:

# Para suporte ao Amazon Bedrock
pip install "anthropic[bedrock]"

# Para suporte ao Google Cloud
pip install "anthropic[vertex]"

# Para suporte ao Claude Platform na AWS
pip install "anthropic[aws]"

# O suporte ao Microsoft Foundry está incluído no pacote base

# Para melhor desempenho assíncrono com aiohttp
pip install "anthropic[aiohttp]"

Requisitos

É necessário Python 3.10 ou posterior. Se você estiver atualizando a partir de uma versão 0.x do SDK, consulte o guia de migração para v1 para a lista de mudanças incompatíveis.

Uso

import os
from anthropic import Anthropic

client = Anthropic(
    # Este é o padrão e pode ser omitido
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
)

message = client.messages.create(
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude",
        }
    ],
    model="claude-opus-5",
)

for block in message.content:
    if block.type == "text":
        print(block.text)

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação. Se sua chave de API for uma chave pessoal ou de conta de serviço com acesso a vários workspaces, defina o ID do workspace no cabeçalho de requisição anthropic-workspace-id; Selecionar um workspace mostra a opção por requisição para este SDK.

Uso assíncrono

import os
import asyncio
from anthropic import AsyncAnthropic

client = AsyncAnthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY"),
)


async def main() -> None:
    message = await client.messages.create(
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Hello, Claude",
            }
        ],
        model="claude-opus-5",
    )
    print(message.content)


asyncio.run(main())

Usando aiohttp para melhor concorrência

Para melhor desempenho assíncrono, você pode usar o backend HTTP aiohttp em vez do httpx2 padrão:

import os
import asyncio
from anthropic import AsyncAnthropic, DefaultAioHttpClient


async def main() -> None:
    async with AsyncAnthropic(
        api_key=os.environ.get("ANTHROPIC_API_KEY"),
        http_client=DefaultAioHttpClient(),
    ) as client:
        message = await client.messages.create(
            max_tokens=1024,
            messages=[
                {
                    "role": "user",
                    "content": "Hello, Claude",
                }
            ],
            model="claude-opus-5",
        )
        print(message.content)


asyncio.run(main())

Respostas em streaming

O SDK fornece suporte a respostas em "streaming" (streaming) usando Server-Sent Events (SSE).

client = Anthropic()

stream = client.messages.create(
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude",
        }
    ],
    model="claude-opus-5",
    stream=True,
)
for event in stream:
    print(event.type)

O cliente assíncrono usa exatamente a mesma interface:

client = AsyncAnthropic()

stream = await client.messages.create(
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude",
        }
    ],
    model="claude-opus-5",
    stream=True,
)
async for event in stream:
    print(event.type)

Helpers de streaming

O SDK também fornece helpers de streaming que usam gerenciadores de contexto e fornecem acesso ao texto acumulado e à mensagem final:

async def main() -> None:
    async with client.messages.stream(
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Say hello there!",
            }
        ],
        model="claude-opus-5",
    ) as stream:
        async for text in stream.text_stream:
            print(text, end="", flush=True)
        print()

        message = await stream.get_final_message()
        print(message.to_json())


asyncio.run(main())

O streaming com client.messages.stream(...) expõe vários helpers, incluindo acumulação e eventos específicos do SDK.

Alternativamente, você pode usar client.messages.create(..., stream=True), que retorna apenas um iterável dos eventos no stream e usa menos memória (ele não constrói um objeto de mensagem final para você).

Contagem de tokens

Você pode ver o uso exato de uma determinada requisição por meio da propriedade de resposta usage:

message = client.messages.create(...)
print(message.usage)
# Usage(input_tokens=25, output_tokens=13)

Você também pode contar tokens antes de fazer uma requisição:

count = client.messages.count_tokens(
    model="claude-opus-5", messages=[{"role": "user", "content": "Hello, world"}]
)
print(count.input_tokens)  # 10

Uso de ferramentas

Este SDK fornece suporte a "tool use" (uso de ferramentas), também conhecido como chamada de funções. Para mais detalhes, consulte Uso de ferramentas com Claude.

Helpers de ferramentas

O SDK fornece helpers para definir e executar ferramentas como funções Python puras. O decorador @beta_tool gera o esquema da ferramenta a partir da assinatura da função e da docstring:

import json
from anthropic import Anthropic, beta_tool

client = Anthropic()


@beta_tool
def get_weather(location: str) -> str:
    """Get the weather for a given location.

    Args:
        location: The city and state, for example, San Francisco, CA
    Returns:
        A JSON-encoded string with the location, temperature, and weather condition.
    """
    return json.dumps(
        {
            "location": location,
            "temperature": "68°F",
            "condition": "Sunny",
        }
    )


# Use o tool_runner para lidar automaticamente com chamadas de ferramentas
runner = client.beta.messages.tool_runner(
    max_tokens=1024,
    model="claude-opus-5",
    tools=[get_weather],
    messages=[
        {"role": "user", "content": "What is the weather in SF?"},
    ],
)
for message in runner:
    print(message)

Em cada iteração, uma requisição à API é feita. Se a resposta incluir uma chamada a uma das ferramentas fornecidas, a ferramenta é chamada automaticamente e o resultado é retornado diretamente ao modelo na próxima iteração.

Lotes de mensagens

Este SDK fornece suporte a Processamento em lote em client.messages.batches.

Criando um lote

Message Batches recebe um array de requisições, onde cada objeto tem um identificador custom_id e os mesmos params de requisição da Messages API padrão:

client.messages.batches.create(
    requests=[
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-5",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hello, world"}],
            },
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-5",
                "max_tokens": 1024,
                "messages": [{"role": "user", "content": "Hi again, friend"}],
            },
        },
    ]
)

Obtendo resultados de um lote

Depois que um Message Batch tiver sido processado, indicado por .processing_status == 'ended', você pode acessar os resultados com .batches.results():

client = anthropic.Anthropic()
batch_id = "batch_abc123"
result_stream = client.messages.batches.results(batch_id)
for entry in result_stream:
    if entry.result.type == "succeeded":
        print(entry.result.message.content)

Upload de arquivos

Parâmetros de requisição que correspondem a uploads de arquivos podem ser passados de várias formas diferentes:

• Um objeto PathLike (por exemplo, pathlib.Path)
• Uma tupla de (filename, content, content_type)
• Um objeto do tipo arquivo BinaryIO

from pathlib import Path
from anthropic import Anthropic

client = Anthropic()

# Upload usando um caminho de arquivo
client.files.upload(
    file=Path("/path/to/file"),
)

# Upload usando bytes
client.files.upload(
    file=("file.txt", b"my bytes", "text/plain"),
)

O cliente assíncrono usa exatamente a mesma interface. Se você passar uma instância de PathLike, o conteúdo do arquivo é lido de forma assíncrona automaticamente.

Tratamento de erros

Quando a biblioteca não consegue se conectar à API, ou se a API retorna um código de status que não indica sucesso (ou seja, resposta 4xx ou 5xx), uma subclasse de APIError é lançada:

import anthropic
# ...
try:
    message = client.messages.create(
        max_tokens=1024,
        messages=[
            {
                "role": "user",
                "content": "Hello, Claude",
            }
        ],
        model="claude-opus-5",
    )
except anthropic.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)  # an underlying Exception, likely raised within httpx2
except anthropic.RateLimitError as e:
    print("A 429 status code was received; we should back off a bit.")
except anthropic.APIStatusError as e:
    print("Another non-200-range status code was received")
    print(e.status_code)
    print(e.response)

Os códigos de erro são os seguintes:

IDs de requisição

Para mais informações sobre depuração de requisições, consulte ID de requisição.

Todas as respostas de objeto no SDK fornecem uma propriedade _request_id, que é adicionada a partir do cabeçalho de resposta request-id, para que você possa registrar rapidamente requisições com falha e reportá-las à Anthropic.

message = client.messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5",
)
print(message._request_id)  # e.g., req_018EeWyXxfu5pfWkrYcMdjWG

Novas tentativas

Certos erros são automaticamente repetidos 2 vezes por padrão, com um curto backoff exponencial. Erros de conexão (por exemplo, devido a um problema de conectividade de rede), 408 Request Timeout, 409 Conflict, 429 Rate Limit e erros internos >=500 são todos repetidos por padrão.

Você pode usar a opção max_retries para configurar ou desabilitar isso:

# Configure o padrão para todas as requisições:
client = Anthropic(
    max_retries=0,  # default is 2
)

# Ou configure por requisição:
client.with_options(max_retries=5).messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5",
)

Timeouts

Por padrão, as requisições expiram após 10 minutos. Você pode configurar isso com a opção timeout, que aceita um float ou um objeto httpx2.Timeout:

import httpx2
from anthropic import Anthropic

# Configure o padrão para todas as requisições:
client = Anthropic(
    timeout=20.0,  # 20 seconds (default is 10 minutes)
)

# Controle mais granular:
client = Anthropic(
    timeout=httpx2.Timeout(60.0, read=5.0, write=10.0, connect=2.0),
)

# Substitua por requisição:
client.with_options(timeout=5.0).messages.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5",
)

Em caso de timeout, o SDK lança um APITimeoutError.

Observe que requisições que expiram são repetidas duas vezes por padrão.

Requisições longas

Evite definir um valor grande de max_tokens sem usar streaming. Algumas redes podem descartar conexões ociosas após um certo período de tempo, o que pode fazer com que a requisição falhe ou sofra timeout sem receber uma resposta da Anthropic.

O SDK lançará um ValueError se uma requisição sem streaming tiver duração esperada superior a aproximadamente 10 minutos. Passar stream=True ou sobrescrever a opção timeout no nível do cliente ou da requisição desabilita esse erro.

Uma latência de requisição esperada maior que o timeout para uma requisição sem streaming resultará no cliente encerrando a conexão e tentando novamente sem receber uma resposta.

O SDK define uma opção de TCP socket keep-alive para reduzir o impacto de timeouts de conexões ociosas em algumas redes. Isso pode ser sobrescrito passando uma opção http_client personalizada ao cliente.

Paginação automática

Os métodos de listagem na Claude API são paginados. Você pode usar a sintaxe for para iterar pelos itens em todas as páginas:

client = Anthropic()

all_batches = []
# Busca automaticamente mais páginas conforme necessário.
for batch in client.messages.batches.list(limit=20):
    all_batches.append(batch)
print(all_batches)

Para iteração assíncrona:

async def main() -> None:
    all_batches = []
    async for batch in client.messages.batches.list(limit=20):
        all_batches.append(batch)
    print(all_batches)


asyncio.run(main())

Alternativamente, você pode usar os métodos .has_next_page(), .next_page_info() ou .get_next_page() para um controle mais granular ao trabalhar com páginas:

first_page = await client.messages.batches.list(limit=20)

if first_page.has_next_page():
    print(f"will fetch next page using these details: {first_page.next_page_info()}")
    next_page = await first_page.get_next_page()
    print(f"number of items we just fetched: {len(next_page.data)}")

# Remova `await` para uso não assíncrono.

Ou trabalhar diretamente com os dados retornados:

first_page = await client.messages.batches.list(limit=20)

print(f"next page cursor: {first_page.last_id}")
for batch in first_page.data:
    print(batch.id)

# Remova `await` para uso não assíncrono.

Cabeçalhos padrão

O SDK envia automaticamente o cabeçalho anthropic-version definido como 2023-06-01.

Se necessário, você pode sobrescrevê-lo definindo cabeçalhos padrão no objeto cliente ou por requisição.

# Defina cabeçalhos padrão para todas as requisições no cliente
client = Anthropic(
    default_headers={"anthropic-version": "My-Custom-Value"},
)

# Ou substitua por requisição
client.messages.with_raw_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5",
    extra_headers={"anthropic-version": "My-Custom-Value"},
)

Sistema de tipos

Parâmetros de requisição

Parâmetros de requisição aninhados são TypedDicts. As respostas são modelos Pydantic, que também têm métodos auxiliares para coisas como serializar de volta para JSON (v1, v2).

Requisições e respostas tipadas fornecem autocompletar e documentação dentro do seu editor. Se você quiser ver erros de tipo no VS Code para ajudar a detectar bugs mais cedo, defina python.analysis.typeCheckingMode como basic.

Modelos de resposta

Para converter um modelo Pydantic em um dicionário, use os métodos auxiliares:

message = client.messages.create(...)

# Converter para string JSON
json_str = message.to_json()

# Converter para dicionário
data = message.to_dict()

Tratando campos null vs ausentes

Nas respostas, você pode distinguir entre campos que são explicitamente null e campos que não foram retornados (ausentes):

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
if response.my_field is None:
    if "my_field" not in response.model_fields_set:
        print("field was not in the response")
    else:
        print("field was null")

Uso avançado

Acessando dados brutos da resposta (por exemplo, cabeçalhos)

A Response "bruta" retornada pelo httpx2 pode ser acessada por meio da propriedade .with_raw_response no cliente. Isso é útil para acessar cabeçalhos de resposta ou outros metadados:

client = Anthropic()

response = client.messages.with_raw_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5",
)

print(response.headers.get("request-id"))
message = (
    response.parse()
)  # get the object that `messages.create()` would have returned
print(message.content)

Esses métodos retornam um objeto APIResponse. No cliente assíncrono, eles retornam um AsyncAPIResponse, e .parse(), .read(), .text() e .json() devem ser aguardados com await.

Streaming do corpo da resposta

A abordagem .with_raw_response lê antecipadamente o corpo completo da resposta quando você faz a requisição. Para fazer streaming do corpo da resposta, use .with_streaming_response, que requer um gerenciador de contexto e só lê o corpo da resposta quando você chama .read(), .text(), .json(), .iter_bytes(), .iter_text(), .iter_lines() ou .parse(). No cliente assíncrono, esses são métodos assíncronos.

with client.messages.with_streaming_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-5",
) as response:
    print(response.headers.get("request-id"))

    for line in response.iter_lines():
        print(line)

O gerenciador de contexto é necessário para que a resposta seja fechada de forma confiável.

Logging

O SDK usa o módulo logging da biblioteca padrão.

Você pode habilitar o logging definindo a variável de ambiente ANTHROPIC_LOG como debug ou info:

export ANTHROPIC_LOG=debug

Fazendo requisições personalizadas/não documentadas

Esta biblioteca é tipada para acesso conveniente à API documentada. Se você precisar acessar endpoints, parâmetros ou propriedades de resposta não documentados, a biblioteca ainda pode ser usada.

Endpoints não documentados

Para fazer requisições a endpoints não documentados, você pode usar client.get, client.post e outros verbos HTTP. As opções do cliente, como novas tentativas, são respeitadas ao fazer essas requisições.

import httpx2

response = client.post(
    "/foo",
    cast_to=httpx2.Response,
    body={"my_param": True},
)

print(response.json())

Parâmetros de requisição não documentados

Se você quiser enviar explicitamente um parâmetro extra, pode fazê-lo com as opções de requisição extra_query, extra_body e extra_headers.

Propriedades de resposta não documentadas

Para acessar propriedades de resposta não documentadas, você pode acessar os campos extras como response.unknown_prop. Você também pode obter todos os campos extras no modelo Pydantic como um dict com response.model_extra.

Configurando o cliente HTTP

O SDK envia requisições com httpx2, um fork do httpx compatível em nível de API. Para personalizar o cliente HTTP, incluindo proxies e transportes, passe seu próprio cliente httpx2 como http_client:

import httpx2
from anthropic import Anthropic, DefaultHttpxClient

client = Anthropic(
    # Ou use a variável de ambiente `ANTHROPIC_BASE_URL`
    base_url="http://my.test.server.example.com:8083",
    http_client=DefaultHttpxClient(
        proxy="http://my.test.proxy.example.com",
        transport=httpx2.HTTPTransport(local_address="0.0.0.0"),
    ),
)

Você também pode personalizar o cliente por requisição usando with_options():

client.with_options(http_client=DefaultHttpxClient(...))

Ferramentas de rastreamento e mocking que fazem patch do próprio httpx, como o HTTPXClientInstrumentor do OpenTelemetry, a integração httpx do Sentry, respx ou pytest-httpx, não veem as requisições do SDK por padrão. Para usá-las, chame httpx2.alias_httpx() uma vez na inicialização, antes que qualquer coisa importe httpx. Isso faz com que import httpx resolva para httpx2 em todo o processo.

Gerenciando recursos HTTP

Por padrão, a biblioteca fecha as conexões HTTP subjacentes sempre que o cliente é coletado pelo garbage collector. Você pode fechar o cliente manualmente usando o método .close(), se desejar, ou com um gerenciador de contexto que fecha ao sair.

with Anthropic() as client:
    message = client.messages.create(...)

# O cliente HTTP é fechado automaticamente

Recursos beta

Recursos beta estão disponíveis antes do lançamento geral para obter feedback antecipado e testar novas funcionalidades. Você pode verificar a disponibilidade de todas as capacidades e ferramentas do Claude na visão geral de construir com Claude.

Você pode acessar a maioria dos recursos beta da API por meio da propriedade beta do cliente. Para habilitar um recurso beta específico, você precisa adicionar o cabeçalho beta apropriado ao campo betas ao criar uma mensagem.

Por exemplo, para habilitar a edição de contexto:

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    betas=["context-management-2025-06-27"],
)

Integrações de plataforma

Todas as cinco classes de cliente estão incluídas no pacote base anthropic:

O cliente AnthropicAWS está em beta. Passe workspace_id ao construtor ou defina a variável de ambiente ANTHROPIC_AWS_WORKSPACE_ID.

Use AnthropicBedrockMantle para novos projetos; AnthropicBedrock permanece para aplicações existentes que usam a API InvokeModel do Bedrock.

Versionamento semântico

Este pacote geralmente segue as convenções do SemVer, embora certas mudanças incompatíveis com versões anteriores possam ser lançadas como versões menores:

1. Mudanças que afetam apenas tipos estáticos, sem quebrar o comportamento em tempo de execução.
2. Mudanças em partes internas da biblioteca que são tecnicamente públicas, mas não destinadas ou documentadas para uso externo.
3. Mudanças que não devem impactar a grande maioria dos usuários na prática.

Determinando a versão instalada

Se você atualizou para a versão mais recente, mas não está vendo os novos recursos que esperava, seu ambiente Python provavelmente ainda está usando uma versão mais antiga. Você pode determinar a versão em uso em tempo de execução com:

print(anthropic.__version__)

Recursos adicionais

• Repositório no GitHub
• Referência da API
• Streaming de mensagens
• Uso de ferramentas com Claude