Anthropic Claude SDK
O SDK Python da Anthropic chama os modelos Claude através da API de Mensagens. Ele suporta streaming, uso de ferramentas, visão e saídas estruturadas para aplicações LLM de produção.
Receita
Cartão de receita de referência rápida - pronto para copiar e colar.
import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
system="Você é um assistente útil.",
messages=[{"role": "user", "content": "Olá!"}],
)
print(message.content[0].text)Quando usar isso:
- Construindo aplicações em modelos Claude (Sonnet, Haiku, Opus).
- Transmitindo respostas longas para usuários em tempo real.
- Dando ao Claude acesso a ferramentas (pesquisa, banco de dados, APIs).
- Processando imagens ou documentos com a capacidade de visão do Claude.
Exemplo de Trabalho
"""anthropic_claude_sdk.py - mensagens, streaming e uso de ferramentas."""
from __future__ import annotations
import json
import anthropic
client = anthropic.Anthropic()
# Mensagem básica
response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=512,
system="Você é um revisor de código Python. Seja conciso.",
messages=[{"role": "user", "content": "Revise: def add(a,b): return a+b"}],
)
print(response.content[0].text)
# Streaming
print("--- streaming ---")
with client.messages.stream(
model="claude-sonnet-4-20250514",
max_tokens=256,
messages=[{"role": "user", "content": "Conte de 1 a 5."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
print()
# Uso de ferramentas
tools = [{
"name": "get_weather",
"description": "Obter o clima de uma cidade",
"input_schema": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
}]
def get_weather(city: str) -> str:
return json.dumps({"city": city, "temp_f": 72, "condition": "sunny"})
msg = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
tools=tools,
messages=[{"role": "user", "content": "Qual é o clima em Austin?"}],
)
while msg.stop_reason == "tool_use":
tool_results = []
for block in msg.content:
if block.type == "tool_use":
result = get_weather(**block.input)
tool_results.append({
"type": "tool_result",
"tool_use_id": block.id,
"content": result,
})
msg = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
tools=tools,
messages=[
{"role": "user", "content": "Qual é o clima em Austin?"},
{"role": "assistant", "content": msg.content},
{"role": "user", "content": tool_results},
],
)
print(msg.content[0].text)O que isso demonstra:
- Criação básica de mensagens síncronas.
- Streaming com
messages.streametext_stream. - Definição de ferramentas com esquema JSON e loop de uso de ferramentas.
- Submissão de resultados de ferramentas multi-turno de volta ao Claude.
Mergulho Profundo
Como Funciona
- API de Mensagens aceita
system,messagesetoolsopcionais. - Blocos de conteúdo são tipados:
text,tool_use,tool_result,image. - stop_reason indica por que a geração terminou:
end_turn,tool_use,max_tokens. - Streaming emite eventos;
text_streamproduz apenas deltas de texto. - Contagem de tokens via
client.messages.count_tokens()antes de enviar.
Níveis de Modelo
| Modelo | Velocidade | Capacidade | Uso |
|---|---|---|---|
| Haiku | Mais Rápido | Tarefas Básicas | Classificação, extração |
| Sonnet | Equilibrado | Raciocínio Forte | Aplicações Gerais |
| Opus | Mais Lento | Melhor Qualidade | Análise Complexa, codificação |
Notas Python
# Cliente Assíncrono
import asyncio
import anthropic
async def main():
client = anthropic.AsyncAnthropic()
msg = await client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=256,
messages=[{"role": "user", "content": "Oi"}],
)
print(msg.content[0].text)
asyncio.run(main())Armadilhas
max_tokensausente - A API requermax_tokens; as requisições falham sem ele. Correção: sempre definamax_tokensexplicitamente.- Loop de ferramentas não implementado - Claude retorna
tool_use, mas o código não o manipula. Correção: verifiquestop_reasone envie blocostool_result. - Chave de API codificada - risco de segurança no código-fonte. Correção:
anthropic.Anthropic()lêANTHROPIC_API_KEYdo ambiente. - Não tratamento de limites de taxa - erros 429 travam o aplicativo. Correção: nova tentativa de backoff exponencial com
tenacityou configuração de retentativa do SDK. - Ignorando limites de tokens - conversas longas excedem a janela de contexto. Correção: corte mensagens antigas ou resuma o histórico.
- Acesso incorreto ao bloco de conteúdo - assumindo que todos os blocos são texto. Correção: verifique
block.typeantes de acessar.text.
Alternativas
| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| SDK Anthropic | Modelos Claude | Precisa do ecossistema OpenAI |
| SDK OpenAI | Modelos GPT, ferramentas mais amplas | Prefere a segurança/estilo do Claude |
| LiteLLM | Abstração multi-provedor | Simplicidade de provedor único |
| AWS Bedrock | Claude via AWS IAM | API direta é mais simples |
FAQs
Como defino a chave de API?
export ANTHROPIC_API_KEY="sk-ant-..."- Ou passe
api_key=para o construtor. - Nunca envie chaves para o git.
O que é o loop de uso de ferramentas?
- Envie a mensagem do usuário com as ferramentas definidas.
- Se
stop_reason == "tool_use", execute a ferramenta. - Envie os resultados da ferramenta de volta como uma mensagem do usuário.
- Repita até
stop_reason == "end_turn".
Como faço streaming de respostas?
with client.messages.stream(...) as stream:
for text in stream.text_stream:
print(text, end="")- Use streaming assíncrono para servidores web.
O Claude pode ler imagens?
{"role": "user", "content": [
{"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": b64}},
{"type": "text", "text": "O que há nesta imagem?"},
]}Como conto tokens?
count = client.messages.count_tokens(
model="claude-sonnet-4-20250514",
messages=[{"role": "user", "content": "Olá"}],
)
print(count.input_tokens)O que é pensamento estendido?
- Alguns modelos Claude suportam um bloco de pensamento antes da resposta.
- Útil para tarefas de raciocínio complexas.
- Verifique a documentação do modelo para disponibilidade.
Como lido com erros?
import anthropic
try:
client.messages.create(...)
except anthropic.RateLimitError:
time.sleep(5) # backoff
except anthropic.APIStatusError as e:
print(e.status_code, e.message)Prompt do sistema vs primeira mensagem do usuário?
- O parâmetro
systemé o prompt do sistema dedicado. - Mais limpo do que incorporar instruções em mensagens do usuário.
Como uso o Claude com FastAPI?
- Use
AsyncAnthropicem manipuladores de rota assíncronos. - Transmita com
StreamingResponsepara SSE para clientes.
Quais modelos estão disponíveis?
- Verifique https://docs.anthropic.com para IDs de modelos atuais.
- Nomes de modelos incluem datas de versão (por exemplo,
claude-sonnet-4-20250514).
Como reduzir custos?
- Use Haiku para tarefas simples.
- Defina
max_tokensapropriado. - Cache de prompts de sistema repetidos onde suportado.
Posso obter saída JSON?
- Instrua o Claude a responder em JSON no prompt do sistema.
- Use o uso de ferramentas com um esquema para estrutura garantida.
- Veja Saída Estruturada.
Relacionados
- SDKs OpenAI e Outros - comparação de provedores
- Uso de Ferramentas e Chamada de Funções - padrões de ferramentas
- Streaming e Chamadas LLM Assíncronas - streaming assíncrono
- Engenharia de Prompt - prompts do sistema
- Tokens, Custo e Limites de Taxa - orçamento
Versões de Stack: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.