Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
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, Claude Platform na AWS, Google Cloud e Microsoft Foundry.
pip install anthropicPara 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 à 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]"Python 3.9 ou posterior é necessário.
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.
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())Para melhor desempenho assíncrono, você pode usar o backend HTTP aiohttp em vez do padrão httpx:
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())O SDK fornece suporte para respostas em 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)O SDK também fornece auxiliares 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 auxiliares, 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ê).
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-5", messages=[{"role": "user", "content": "Hello, world"}]
)
print(count.input_tokens) # 10Este SDK fornece suporte para uso de ferramentas, também conhecido como "function calling" (chamada de função). Para mais detalhes, consulte Uso de ferramentas com Claude.
O SDK fornece auxiliares 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)A 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.
Este SDK fornece suporte para a API de Lotes de Mensagens em client.messages.batches.
Lotes de Mensagens recebem um array de requisições, onde cada objeto tem um identificador custom_id e os mesmos params de requisição da API de Mensagens 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"}],
},
},
]
)Depois que um Lote de Mensagens for 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)Parâmetros de requisição que correspondem a uploads de arquivos podem ser passados de várias formas diferentes:
PathLike (por exemplo, pathlib.Path)(filename, content, content_type)BinaryIOfrom 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.
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-5",
)
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 |
| N/A | APIConnectionError |
Para mais informações sobre depuração de requisições, consulte ID de requisição.
Todas as respostas de objetos 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_018EeWyXxfu5pfWkrYcMdjWGCertos erros são automaticamente repetidos 2 vezes por padrão, com um curto "exponential backoff" (recuo 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",
)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-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.
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 for esperado que uma requisição sem streaming leve mais do que 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 "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 TCP socket keep-alive para reduzir o impacto de timeouts de conexão ociosa em algumas redes. Isso pode ser sobrescrito passando uma opção http_client personalizada para o cliente.
Os 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 trabalhe 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.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 do cliente ou por requisição.
# Define cabeçalhos padrão para todas as requisições no cliente
client = Anthropic(
default_headers={"anthropic-version": "My-Custom-Value"},
)
# Ou sobrescreva 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"},
)Parâmetros de requisição aninhados são TypedDicts. As respostas são modelos Pydantic que também possuem 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.
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()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")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-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.
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 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-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.
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=debugEsta 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.
Para fazer requisições a endpoints não documentados, você pode usar client.get, client.post e outros verbos HTTP. As opções no cliente, como novas tentativas, são respeitadas ao fazer essas requisições.
import httpx
response = client.post(
"/foo",
cast_to=httpx.Response,
body={"my_param": True},
)
print(response.json())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.
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.
Você pode sobrescrever diretamente o cliente httpx para personalizá-lo para seu caso de uso, incluindo suporte a 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(...))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 automaticamenteRecursos 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-5",
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"],
)Todas as cinco classes de cliente estão incluídas no pacote base anthropic:
| Provedor | Cliente | Dependências extras |
|---|---|---|
| Agent Platform | from anthropic import AnthropicVertex | pip install "anthropic[vertex]" |
| Bedrock | from anthropic import AnthropicBedrockMantle | pip install "anthropic[bedrock]" |
Bedrock (caminho bedrock-runtime) | from anthropic import AnthropicBedrock | pip install "anthropic[bedrock]" |
| Claude Platform na AWS | from anthropic import AnthropicAWS | pip install "anthropic[aws]" |
| Foundry | from anthropic import AnthropicFoundry | Nenhuma |
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.
Este pacote geralmente segue as convenções de SemVer, embora certas mudanças incompatíveis com versões anteriores possam ser lançadas como versões menores:
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__)Was this page helpful?