Melhores Práticas do SDK Python

Um checklist testado em produção para usar bem o SDK Python anthropic em produção: configuração do cliente, escolha síncrona/assíncrona, retentativas, streaming e tratamento de erros.

Como Usar Este Checklist

• Trate cada item como uma regra positiva - a coisa a fazer, não apenas um erro a evitar.
• Percorra-o uma vez ao configurar um novo serviço que chama Claude, depois revise a seção D sempre que adicionar um novo modo de falha em produção.
• Emparelhe isso com as páginas dedicadas vinculadas em "Relacionado" para a explicação completa por trás de qualquer regra individual.

A - Configuração do Cliente

• Construa o cliente uma vez e reutilize-o. Crie Anthropic() ou AsyncAnthropic() na inicialização do módulo ou da aplicação, não dentro de um manipulador de requisição ou corpo de loop - reconstruí-lo a cada chamada descarta o pooling de conexões.
• Leia a chave de API do ambiente por padrão. Deixe Anthropic() pegar ANTHROPIC_API_KEY automaticamente em vez de codificar uma string de chave em código fonte; passe api_key=... explicitamente apenas quando a chave vier de um gerenciador de segredos em tempo de execução.
• Fixe a versão do SDK no seu arquivo de dependências. Uma dependência anthropic não fixada pode introduzir novos campos de resposta ou tipos de bloco entre deploys; fixe-a e atualize deliberadamente.
• Defina max_retries e timeout deliberadamente, não por acidente. Decida os valores com base se a chamada é interativa (timeout curto, poucas retentativas) ou um job em background (timeout mais longo, mais retentativas), em vez de deixar cada local de chamada com os mesmos padrões.
• Apenas recorra a um http_client customizado quando tiver um requisito real de infraestrutura. Proxies, pacotes CA customizados e ajuste de pool de conexões são razões válidas; não adicione complexidade especulativamente.

B - Síncrono vs Assíncrono

• Combine o cliente com o modelo de concorrência do seu programa, não o contrário. Use Anthropic() em scripts, CLIs e frameworks síncronos; use AsyncAnthropic() em serviços web assíncronos e em qualquer lugar onde você faça chamadas concorrentes em leque.
• Nunca chame o cliente síncrono diretamente dentro de uma rota async def. Isso bloqueia todo o loop de eventos durante a duração da chamada; use AsyncAnthropic() em manipuladores assíncronos, ou envolva chamadas síncronas inevitáveis em um pool de threads.
• Use asyncio.gather para realmente obter concorrência do cliente assíncrono. Aguardar cada chamada sequencialmente dentro de um loop abre mão do benefício de throughput que motivou a escolha de AsyncAnthropic() em primeiro lugar.
• Limite o fan-out concorrente com um semáforo. asyncio.gather ilimitado sobre muitas requisições pode sobrecarregar seus próprios limites de taxa; limite-o a um limite de concorrência sensato para a carga de trabalho.
• Não mude para assíncrono apenas por razões de latência. Uma única requisição leva o mesmo tempo de relógio em qualquer cliente; assíncrono compensa apenas quando múltiplas requisições se sobrepõem.

C - Streaming

• Faça streaming de qualquer requisição onde max_tokens for grande. Acima de aproximadamente 16.000 tokens de saída, uma chamada não-streaming corre o risco de um timeout HTTP do lado do cliente; client.messages.stream() evita esse risco independentemente do tamanho da saída.
• Use text_stream para o caso comum, eventos brutos apenas quando precisar deles. text_stream cuida da análise para texto puro; desça para iteração de eventos brutos apenas quando precisar de eventos de tool-use ou thinking no meio do stream.
• Chame get_final_message() após o loop, não antes. Ele retorna a mesma Message completa e tipada que uma chamada não-streaming retornaria, incluindo stop_reason e usage - não reconstrua essa informação manualmente a partir de pedaços acumulados.
• Combine with/async with com o cliente que você está usando. O streaming de Anthropic() usa with e for; o streaming de AsyncAnthropic() usa async with e async for. Misturá-los levanta um TypeError.
• Envolva chamadas de streaming no mesmo tratamento de erros que as não-streaming. Uma conexão perdida surge como uma exceção de dentro da iteração, não antes de começar; não assuma que chamadas de streaming estão isentas dos padrões de retentativa/exceção que você usa em outros lugares.

D - Tratamento de Erros

• Capture exceções tipadas, as mais específicas primeiro. Encadeie except anthropic.NotFoundError, except anthropic.RateLimitError, except anthropic.APIStatusError, except anthropic.APIConnectionError em vez de um except Exception amplo.
• Não crie lógica de retentativa customizada para o que o SDK já retenta. Erros de rede, 429, 5xx, 408 e 409 são retentados automaticamente até max_retries; adicione seu próprio tratamento para o que acontece após as retentativas serem esgotadas, não para duplicá-las.
• Nunca retente um 400, 401, 403, 404, ou 422 sem alteração. Estes não são retentáveis por design - a requisição em si precisa mudar, não apenas ser reenviada.
• Registre e.status_code, e.message, e e.type em APIStatusError, não a string bruta da exceção. O campo .type fornece uma classificação mais granular do que apenas o status HTTP (distinguindo rate_limit_error de overloaded_error, por exemplo).
• Falhe rapidamente em AuthenticationError. Uma chave de API inválida ou ausente não se resolve com retentativa; exponha-a ruidosamente em vez de entrar em loop.
• Tipifique suas próprias funções contra Message e ContentBlock, não dict ou Any. Isso é o que permite a um verificador de tipos capturar um local de chamada malformado antes de executar o código, e o que torna o estreitamento isinstance() em blocos de conteúdo realmente útil.

FAQs

Relacionado

• O Modelo Mental do SDK Python da Anthropic - a base conceitual por trás deste checklist
• Escolhendo Entre Anthropic() e AsyncAnthropic() em Código de Produção - a decisão completa síncrona/assíncrona, expandida da seção B
• Referência de Configuração de Retentativa e Timeout do SDK Python - todas as configurações por trás da regra de retentativa/timeout da seção A
• Tipos de Exceção do SDK Python em Destaque - a hierarquia completa de exceções por trás da seção D

Versões da Stack: Escrito contra a linha de modelos Claude atual em ~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 Python (último release 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.