Como Começar com a API do Claude em Python: Guia Passo a Passo

Adicionar o Claude a uma aplicação Python é mais simples do que parece. Com a SDK oficial da Anthropic, você pode fazer sua primeira chamada à API em minutos. Este guia prático, baseado no tutorial de Bala Priya C no KDnuggets, cobre desde a instalação até o streaming de respostas.

Pré-requisitos e instalação

Você precisa de Python 3.9 ou superior, uma conta gratuita no Claude Console e uma chave de API obtida na página Settings > API Keys do Console. Com US$ 5 em créditos é possível trabalhar em todos os exemplos deste guia.

Instale a SDK da Anthropic com:

pip install anthropic

Nunca coloque a chave de API diretamente no código-fonte. Armazene como variável de ambiente:

export ANTHROPIC_API_KEY="sua-chave-aqui"

export ANTHROPIC_API_KEY="sua-chave-aqui"

Ou use um arquivo .env com python-dotenv. A SDK lê automaticamente a variável ANTHROPIC_API_KEY do ambiente.

Fazendo sua primeira chamada à API

O ponto de entrada é client.messages.create(). Você passa três parâmetros principais: o ID do modelo, um limite de max_tokens e uma lista de messages.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=256,
    messages=[
        {
            "role": "user",
            "content": "Em uma frase, o que é uma janela de contexto?"
        }
    ]
)

print(response.content[0].text)

O campo model aceita o ID exato do modelo (ex: claude-sonnet-5). max_tokens é um teto rígido de tokens de saída — se for muito baixo, a resposta será cortada antes de concluir o pensamento. A lista de messages deve sempre começar com um turno do tipo "user".

Entendendo o objeto de resposta

A resposta de messages.create() é um objeto Message tipado. Vale a pena inspecionar a estrutura completa antes de construir qualquer coisa sobre ela:

• stop_reason: diz por que o Claude parou de gerar. end_turn significa que terminou naturalmente; max_tokens indica que a resposta foi cortada pelo seu limite — talvez seja necessário aumentá-lo.
• usage: rastreia tokens de entrada e saída — é como a Anthropic calcula o faturamento e como você detecta prompts se aproximando do limite de contexto do modelo.
• content: é uma lista — em respostas de texto padrão sempre tem um item, um TextBlock. Use response.content[0].text como forma idiomática de extrair o texto.

Usando system prompts

Um system prompt permite dar ao Claude um papel persistente, definir restrições ou fornecer contexto que se aplica à conversa inteira. É passado como parâmetro system no nível superior — separado da lista de mensagens:

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=256,
    system="Você é um revisor de código Python. Responda apenas em português, de forma direta e sem explicações genéricas.",
    messages=[
        {"role": "user", "content": "Revise: def soma(a,b): return a+b"}
    ]
)

O system prompt fica acima da conversa no contexto do Claude. Ele mantém a mesma autoridade em todos os turnos — instruções de papel, regras de formatação e restrições de domínio definidas ali persistem sem precisar repeti-las em cada mensagem.

Streaming de respostas

Para requisições em que o Claude pode levar alguns segundos, o streaming permite exibir o texto conforme ele chega, em vez de esperar a resposta completa. A SDK oferece isso via client.messages.stream(), usado como gerenciador de contexto:

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explique o que é RAG"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

final_message = stream.get_final_message()
print(f"\nTokens usados: {final_message.usage.input_tokens} + {final_message.usage.output_tokens}")

O iterador text_stream produz fragmentos de texto individuais em tempo real. Use end="" e flush=True para que a saída apareça continuamente sem buffer. O gerenciador de contexto garante que a conexão HTTP seja fechada corretamente. Se precisar do objeto Message completo após o streaming — incluindo contagem de tokens — chame stream.get_final_message() antes do bloco fechar.

Próximos passos

Com esses blocos fundamentais — requisições, respostas estruturadas, system prompts e streaming — você tem a base para integrar o Claude em aplicações Python. Os próximos tópicos incluem tratamento de erros, gerenciamento de tokens e conversas multi-turno. Como a API é stateless, você precisa enviar o histórico da conversa a cada requisição. A documentação da SDK mostra a abordagem recomendada e a referência da API inclui recursos como saídas estruturadas e uso de ferramentas (tool use).