Noções Básicas do SDK Python

9 exemplos para você começar com o SDK Python da Anthropic - 6 básicos e 3 intermediários.

Pré-requisitos

• Python 3.8 ou mais recente.
• Uma chave de API da Anthropic, disponível no Console da Anthropic.
• Instale o SDK: pip install anthropic.
• Defina sua chave como uma variável de ambiente para nunca codificá-la diretamente: export ANTHROPIC_API_KEY=sk-ant-....

Exemplos Básicos

1. Instale o SDK

Adicione o pacote oficial ao seu projeto com pip.

pip install anthropic

• Instala o pacote anthropic e suas dependências, incluindo httpx para transporte HTTP.
• Fixe uma versão em requirements.txt (anthropic>=0.40,<1.0) para compilações reproduzíveis.
• Nenhuma dependência de sistema extra é necessária em uma instalação padrão do Python.

2. Crie um cliente

Construa um cliente uma vez, reutilizando a chave de API do ambiente.

import anthropic
 
client = anthropic.Anthropic()

• Sem argumentos, Anthropic() lê a variável de ambiente ANTHROPIC_API_KEY automaticamente.
• Construa o cliente uma vez no início e reutilize-o para cada solicitação; não crie um novo cliente por chamada.
• Passe api_key="sk-ant-..." explicitamente apenas quando não puder usar uma variável de ambiente, por exemplo, quando uma chave for carregada de um gerenciador de segredos em tempo de execução.

Relacionado: O Modelo Mental do SDK Python da Anthropic - como o cliente se encaixa no design do SDK

3. Envie sua primeira mensagem

Chame a API Messages com um modelo, um limite de tokens e uma lista de mensagens.

import anthropic
 
client = anthropic.Anthropic()
 
message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Em uma frase, o que é um decorador Python?"}
    ],
)
 
print(message.content[0].text)

• model seleciona qual modelo Claude responde à solicitação; claude-sonnet-5 é um bom padrão para a maioria das cargas de trabalho.
• max_tokens limita o comprimento da resposta, não o comprimento da sua entrada.
• messages é uma lista de turnos; a primeira entrada deve ter role="user".

4. Leia o texto da resposta

message.content é uma lista de blocos de conteúdo, não uma única string.

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Nomeie três números primos."}],
)
 
for block in message.content:
    if block.type == "text":
        print(block.text)

• A resposta do Claude pode conter vários blocos de conteúdo (texto, chamadas de ferramenta e assim por diante), portanto, content é sempre uma lista.
• Verificar block.type == "text" antes de ler .text evita erros quando uma resposta contém blocos não textuais.
• Para uma resposta simples apenas de texto, message.content[0].text é um atalho comum assim que você conhece a estrutura de suas respostas.

5. Defina um prompt do sistema

Use o parâmetro system para direcionar o comportamento do modelo para toda a conversa.

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="Você é um tutor de Python conciso. Responda em um parágrafo curto.",
    messages=[{"role": "user", "content": "O que é um gerador?"}],
)
 
print(message.content[0].text)

• system é um parâmetro de nível superior, separado de messages, e se aplica a toda a solicitação.
• Use-o para instruções de persona, tom e formatação em vez de repeti-las em cada mensagem do usuário.
• Um prompt system estável e inalterado é também o que torna o cache de prompt eficaz posteriormente.

6. Controle max_tokens

max_tokens é um limite rígido para a resposta, e atingi-lo trunca a saída.

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=100,
    messages=[{"role": "user", "content": "Escreva um ensaio de 500 palavras sobre tipagem em Python."}],
)
 
print(message.stop_reason)  # "max_tokens" se o ensaio foi cortado
print(message.content[0].text)

• stop_reason informa por que a geração parou: "end_turn" para um término natural, "max_tokens" para uma truncagem.
• Definir max_tokens muito baixo para a tarefa corta silenciosamente a resposta em vez de gerar um erro.
• Um padrão comum para respostas curtas a médias é 1024-4096; saídas longas precisam de mais, e acima de aproximadamente 16000 você deve mudar para streaming (veja Relacionado).

Relacionado: Streaming de Respostas com o SDK Python - evite tempos limite em respostas grandes

Exemplos Intermediários

7. Conversa multi-turno

A API é sem estado - você reenviou todo o histórico da conversa em cada chamada.

import anthropic
 
client = anthropic.Anthropic()
 
messages = [
    {"role": "user", "content": "Minha linguagem favorita é Python."},
]
 
first = client.messages.create(model="claude-sonnet-5", max_tokens=200, messages=messages)
messages.append({"role": "assistant", "content": first.content[0].text})
 
messages.append({"role": "user", "content": "Qual foi a minha linguagem favorita que eu disse?"})
second = client.messages.create(model="claude-sonnet-5", max_tokens=200, messages=messages)
 
print(second.content[0].text)

• Claude não tem memória entre as chamadas; cada turno anterior que você deseja que seja lembrado deve estar na lista messages que você envia.
• Anexe a própria resposta do assistente de volta em messages antes de adicionar o próximo turno do usuário, para que o modelo veja sua própria resposta anterior.
• As mensagens devem começar com role="user" e geralmente alternar user/assistant.

8. Lide com erros com exceções tipadas

Capture as classes de exceção específicas do SDK em vez de um único except amplo.

import anthropic
 
client = anthropic.Anthropic()
 
try:
    message = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Olá"}],
    )
except anthropic.RateLimitError:
    print("Limite de taxa atingido - aguarde e tente novamente mais tarde.")
except anthropic.APIConnectionError:
    print("Erro de rede ao alcançar a API.")
except anthropic.APIStatusError as e:
    print(f"A API retornou um erro: {e.status_code} {e.message}")

• RateLimitError, APIConnectionError e APIStatusError são classes distintas para modos de falha distintos; capture o mais específico primeiro.
• O SDK já tenta novamente falhas transitórias (erros de rede, 429, 5xx) automaticamente, portanto, uma exceção aqui significa que as tentativas foram esgotadas ou a falha não pôde ser tentada novamente.
• Consulte a página de referência de exceções para o mapeamento completo do tipo de exceção para o tratamento recomendado.

Relacionado: Visão Geral dos Tipos de Exceção do SDK Python - o mapeamento completo de exceção para estratégia

9. Configure o tempo limite e as tentativas na construção

Defina padrões para todo o cliente sobre quanto tempo esperar e quantas vezes tentar novamente.

import anthropic
 
client = anthropic.Anthropic(
    max_retries=4,
    timeout=30.0,
)
 
message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Resuma o enredo de um conto sobre um farol."}],
)
 
print(message.content[0].text)

• max_retries controla quantas vezes o SDK tenta novamente automaticamente uma falha transitória antes de gerar um erro; o padrão é 2.
• timeout é em segundos para o SDK Python e se aplica por solicitação, a menos que substituído.
• Use client.with_options(...) para substituir qualquer uma das configurações para uma única chamada sem alterar os padrões do cliente.

Relacionado: Referência de Configuração de Tentativa e Tempo Limite do SDK Python - todas as configurações, comparadas lado a lado

Versões da pilha: Escrito contra a linha de modelos Claude atual em aproximadamente junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5 - e o SDK oficial anthropic para Python (última versão 0.x). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.