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

É seguro pular a configuração de retentativa e usar os padrões do SDK?

Geralmente, sim.

Os padrões (max_retries=2, timeout=600.0 segundos) são valores razoáveis de propósito geral; substitua-os apenas quando um cenário específico (UI interativa, job de lote em background) exigir algo mais restrito ou mais flexível.

Qual item nesta lista é mais importante para um novo serviço de produção?

Construir o cliente uma vez na inicialização (item A1) e escolher síncrono vs assíncrono para corresponder ao modelo de concorrência real do seu programa (item B1) - ambos são fundamentais, e errar em qualquer um deles se agrava em todos os outros itens desta lista.

Preciso seguir as regras de streaming se minhas respostas forem sempre curtas?

Não estritamente - uma resposta curta e limitada dificilmente atingirá um timeout do lado do cliente sem streaming. O streaming se torna importante à medida que max_tokens cresce ou quando você deseja feedback incremental na UI.

Por que a seção assíncrona adverte contra chamar o cliente síncrono dentro de async def?

Porque isso bloqueia todo o loop de eventos, não apenas a requisição atual - toda outra requisição sendo servida por esse mesmo processo assíncrono para durante a duração da chamada bloqueante, não apenas a que a fez.

Capturar uma única exceção ampla é aceitável alguma vez?

Para um script genuinamente descartável onde qualquer falha significa apenas "parar e imprimir um erro", uma captura ampla é aceitável. Em qualquer código que se destina a rodar sem supervisão ou servir tráfego, a cadeia específica-primeiro na seção D vale as linhas extras.

Qual é o erro mais comum que as equipes cometem com este SDK?

Aguardar chamadas de ferramenta assíncronas ou requisições sequencialmente em um loop em vez de usar asyncio.gather - compila, funciona e renuncia silenciosamente à concorrência que foi o motivo inteiro para escolher o cliente assíncrono.

Devo sempre adicionar um http_client customizado para implantações de produção?

Não.

Adicione um apenas quando houver um requisito concreto (um proxy, um pacote CA privado, ajuste de pool de conexões) - é um ponto de personalização avançado, não um passo de endurecimento de produção padrão.

Essas práticas diferem entre Anthropic() e AsyncAnthropic()?

As práticas subjacentes (tratamento de retentativas, disciplina de streaming, respostas tipadas) são idênticas; apenas a sintaxe (await, async with, async for) difere entre as duas classes de cliente.

Com que frequência devo revisitar este checklist?

Sempre que você adicionar um novo local de chamada com requisitos de confiabilidade ou latência diferentes dos seus existentes, ou após um incidente de produção que rastreou até o tratamento de erros ou configuração de timeout.

Fixar a versão do SDK é realmente necessário para um projeto pequeno?

É de menor risco para um projeto pequeno, mas ainda vale a pena fazer - uma dependência não fixada pode introduzir um novo campo de resposta ou tipo de bloco entre deploys sem aviso, o que é um bug mais difícil de rastrear do que um aumento de versão que você escolheu deliberadamente.

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.