CLI, SDKs e bibliotecasSDKs de cliente

SDK Python

Instale e configure o SDK Python da Anthropic com suporte a clientes síncronos e assíncronos

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

Para documentação de recursos da API com exemplos de código, consulte a referência da API. Esta página aborda recursos e configurações do SDK específicos para Python.

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 Vertex AI
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.9 ou posterior.

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-4-8",
)
print(message.content)

Considere usar python-dotenv para adicionar ANTHROPIC_API_KEY="my-anthropic-api-key" ao seu arquivo .env para que sua chave de API não seja armazenada no controle de versão.

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação.

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-4-8",
    )
    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 httpx 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-4-8",
        )
        print(message.content)


asyncio.run(main())

Respostas em streaming

O SDK fornece suporte para respostas em streaming usando "Server-Sent Events" (eventos enviados pelo servidor), ou SSE.

client = Anthropic()

stream = client.messages.create(
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude",
        }
    ],
    model="claude-opus-4-8",
    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-4-8",
    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-4-8",
    ) 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 através 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-4-8", messages=[{"role": "user", "content": "Hello, world"}]
)
print(count.input_tokens)  # 10

Uso de ferramentas

Este SDK fornece suporte para uso de ferramentas, também conhecido como "function calling" (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 schema 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-4-8",
    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 o Claude quiser chamar uma das ferramentas fornecidas, ela é chamada automaticamente, e o resultado é retornado diretamente ao modelo na próxima iteração.

Lotes de mensagens

Este SDK fornece suporte para a API de Lotes de Mensagens em client.messages.batches.

Criando um lote

A API de Lotes de Mensagens recebe um array de requisições, onde cada objeto tem um identificador custom_id e os mesmos params de requisição que a API de Mensagens padrão:

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

Obtendo resultados de um lote

Uma vez que um Lote de Mensagens tenha 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 semelhante a arquivo BinaryIO

from pathlib import Path
from anthropic import Anthropic

client = Anthropic()

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

# Fazer upload usando bytes
client.beta.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 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 de não 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-4-8",
    )
except anthropic.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)  # an underlying Exception, likely raised within httpx
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:

Código de Status	Tipo de Erro
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
409	`ConflictError`
422	`UnprocessableEntityError`
429	`RateLimitError`
>=500	`InternalServerError`

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-4-8",
)
print(message._request_id)  # e.g., req_018EeWyXxfu5pfWkrYcMdjWG

Diferentemente de outras propriedades que usam um prefixo _, a propriedade _request_id é pública. A menos que documentado de outra forma, todas as outras propriedades, métodos e módulos com prefixo _ são privados.

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-4-8",
)

Timeouts

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

import httpx
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=httpx.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-4-8",
)

Em caso de timeout, um APITimeoutError é lançado.

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

Requisições longas

Considere usar a API de Mensagens com streaming para requisições de execução mais longa.

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 expire sem receber uma resposta da Anthropic.

O SDK lançará um ValueError se for esperado que uma requisição sem streaming leve mais de aproximadamente 10 minutos. Passar stream=True ou substituir a opção timeout no nível do cliente ou da requisição desabilita esse erro.

Uma "latency" (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 keep-alive de socket TCP para reduzir o impacto de timeouts de conexão ociosa em algumas redes. Isso pode ser substituído passando uma opção http_client personalizada para o cliente.

Paginação automática

Métodos de listagem na API do Claude 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 substituí-lo definindo cabeçalhos padrão no objeto cliente ou por requisição.

Substituir cabeçalhos padrão pode resultar em tipos incorretos e outros comportamentos inesperados ou indefinidos no SDK.

# 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-4-8",
    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 versus campos que não foram retornados (ausentes):

response = client.messages.create(
    model="claude-opus-4-8",
    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 de resposta (por exemplo, cabeçalhos)

A Response "bruta" retornada pelo httpx pode ser acessada através 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-4-8",
)

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.

Streaming do corpo da resposta

A abordagem .with_raw_response lê avidamente o corpo completo da resposta quando você faz a requisição. Para fazer streaming do corpo da resposta em vez disso, 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-4-8",
) 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. Opções no cliente, como novas tentativas, serão respeitadas ao fazer essas requisições.

import httpx

response = client.post(
    "/foo",
    cast_to=httpx.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.

Os parâmetros extra_ substituem parâmetros documentados com o mesmo nome. Por razões de segurança, certifique-se de que esses métodos sejam usados apenas com dados de entrada confiáveis.

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

Você pode substituir diretamente o cliente httpx para personalizá-lo para seu caso de uso, incluindo suporte para proxies e transportes:

import httpx
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=httpx.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(...))

Use DefaultHttpxClient e DefaultAsyncHttpxClient em vez de httpx.Client e httpx.AsyncClient brutos para garantir que a configuração padrão do SDK (timeouts, limites de conexão, etc.) seja preservada.

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 manualmente o cliente 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 através 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 usar a API de Arquivos:

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please summarize this document for me."},
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": "file_abc123",
                    },
                },
            ],
        },
    ],
    betas=["files-api-2025-04-14"],
)

Integrações de plataforma

Para guias detalhados de configuração de plataforma com exemplos de código, consulte:

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

Provedor	Cliente	Dependências extras
Bedrock	`from anthropic import AnthropicBedrockMantle`	`pip install "anthropic[bedrock]"`
Bedrock (caminho `bedrock-runtime`)	`from anthropic import AnthropicBedrock`	`pip install "anthropic[bedrock]"`
Vertex AI	`from anthropic import AnthropicVertex`	`pip install "anthropic[vertex]"`
Foundry	`from anthropic import AnthropicFoundry`	Nenhuma
Claude Platform on AWS	`from anthropic import AnthropicAWS`

O cliente AnthropicAWS está em beta. Passe workspace_id para o 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:

Mudanças que afetam apenas tipos estáticos, sem quebrar o comportamento em tempo de execução.
Mudanças nos internos da biblioteca que são tecnicamente públicos, mas não destinados ou documentados para uso externo.
Mudanças que não se espera que impactem 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 sendo usada em tempo de execução com:

print(anthropic.__version__)

Recursos adicionais

Was this page helpful?

CLI, SDKs e bibliotecasSDKs de cliente

SDK Python

Instale e configure o SDK Python da Anthropic com suporte a clientes síncronos e assíncronos

Para documentação de recursos da API com exemplos de código, consulte a referência da API. Esta página aborda recursos e configurações do SDK específicos para Python.

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 Vertex AI
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.9 ou posterior.

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-4-8",
)
print(message.content)

Considere usar python-dotenv para adicionar ANTHROPIC_API_KEY="my-anthropic-api-key" ao seu arquivo .env para que sua chave de API não seja armazenada no controle de versão.

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação.

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-4-8",
    )
    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 httpx 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-4-8",
        )
        print(message.content)


asyncio.run(main())

Respostas em streaming

O SDK fornece suporte para respostas em streaming usando "Server-Sent Events" (eventos enviados pelo servidor), ou SSE.

client = Anthropic()

stream = client.messages.create(
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Hello, Claude",
        }
    ],
    model="claude-opus-4-8",
    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-4-8",
    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-4-8",
    ) 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.

Contagem de tokens

Você pode ver o uso exato de uma determinada requisição através 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-4-8", messages=[{"role": "user", "content": "Hello, world"}]
)
print(count.input_tokens)  # 10

Uso de ferramentas

Este SDK fornece suporte para uso de ferramentas, também conhecido como "function calling" (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 schema 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-4-8",
    tools=[get_weather],
    messages=[
        {"role": "user", "content": "What is the weather in SF?"},
    ],
)
for message in runner:
    print(message)

Lotes de mensagens

Este SDK fornece suporte para a API de Lotes de Mensagens em client.messages.batches.

Criando um lote

A API de Lotes de Mensagens recebe um array de requisições, onde cada objeto tem um identificador custom_id e os mesmos params de requisição que a API de Mensagens padrão:

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

Obtendo resultados de um lote

Uma vez que um Lote de Mensagens tenha 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 semelhante a arquivo BinaryIO

from pathlib import Path
from anthropic import Anthropic

client = Anthropic()

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

# Fazer upload usando bytes
client.beta.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 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 de não 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-4-8",
    )
except anthropic.APIConnectionError as e:
    print("The server could not be reached")
    print(e.__cause__)  # an underlying Exception, likely raised within httpx
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:

Código de Status	Tipo de Erro
400	`BadRequestError`
401	`AuthenticationError`
403	`PermissionDeniedError`
404	`NotFoundError`
409	`ConflictError`
422	`UnprocessableEntityError`
429	`RateLimitError`
>=500	`InternalServerError`

IDs de requisição

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

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

Novas tentativas

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-4-8",
)

Timeouts

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

import httpx
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=httpx.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-4-8",
)

Em caso de timeout, um APITimeoutError é lançado.

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

Requisições longas

Considere usar a API de Mensagens com streaming para requisições de execução mais longa.

Uma "latency" (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.

Paginação automática

Métodos de listagem na API do Claude 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 substituí-lo definindo cabeçalhos padrão no objeto cliente ou por requisição.

Substituir cabeçalhos padrão pode resultar em tipos incorretos e outros comportamentos inesperados ou indefinidos no SDK.

# 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-4-8",
    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).

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 versus campos que não foram retornados (ausentes):

response = client.messages.create(
    model="claude-opus-4-8",
    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 de resposta (por exemplo, cabeçalhos)

A Response "bruta" retornada pelo httpx pode ser acessada através 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-4-8",
)

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.

Streaming do corpo da resposta

with client.messages.with_streaming_response.create(
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    model="claude-opus-4-8",
) 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

Endpoints não documentados

import httpx

response = client.post(
    "/foo",
    cast_to=httpx.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.

Os parâmetros extra_ substituem parâmetros documentados com o mesmo nome. Por razões de segurança, certifique-se de que esses métodos sejam usados apenas com dados de entrada confiáveis.

Propriedades de resposta não documentadas

Configurando o cliente HTTP

Você pode substituir diretamente o cliente httpx para personalizá-lo para seu caso de uso, incluindo suporte para proxies e transportes:

import httpx
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=httpx.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(...))

Gerenciando recursos HTTP

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

# O cliente HTTP é fechado automaticamente

Recursos beta

Por exemplo, para usar a API de Arquivos:

client = Anthropic()

response = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "Please summarize this document for me."},
                {
                    "type": "document",
                    "source": {
                        "type": "file",
                        "file_id": "file_abc123",
                    },
                },
            ],
        },
    ],
    betas=["files-api-2025-04-14"],
)

Integrações de plataforma

Para guias detalhados de configuração de plataforma com exemplos de código, consulte:

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

Provedor	Cliente	Dependências extras
Bedrock	`from anthropic import AnthropicBedrockMantle`	`pip install "anthropic[bedrock]"`
Bedrock (caminho `bedrock-runtime`)	`from anthropic import AnthropicBedrock`	`pip install "anthropic[bedrock]"`
Vertex AI	`from anthropic import AnthropicVertex`	`pip install "anthropic[vertex]"`
Foundry	`from anthropic import AnthropicFoundry`	Nenhuma
Claude Platform on AWS	`from anthropic import AnthropicAWS`

O cliente AnthropicAWS está em beta. Passe workspace_id para o 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:

Mudanças que afetam apenas tipos estáticos, sem quebrar o comportamento em tempo de execução.
Mudanças nos internos da biblioteca que são tecnicamente públicos, mas não destinados ou documentados para uso externo.
Mudanças que não se espera que impactem a grande maioria dos usuários na prática.

Determinando a versão instalada

print(anthropic.__version__)

Recursos adicionais

Was this page helpful?