Melhores Práticas do SDK TypeScript/JavaScript

Um checklist prático para tipagem, streaming, retentativas e implantação em edge com @anthropic-ai/sdk. Use-o ao configurar uma nova integração ou ao revisar uma existente para segurança de tipos e prontidão para produção.

Como Usar Esta Lista

• Percorra cada grupo com letras em ordem: configuração primeiro, depois tipagem, e então as preocupações de tempo de execução (streaming, retentativas, erros, implantação).
• Trate cada item como uma caixa de seleção durante a revisão de código, não apenas como uma leitura única.
• Releia os grupos de retentativa/timeout e tratamento de erros sempre que adicionar um novo local de chamada ou mover um recurso para um runtime de edge.
• Combine esta lista com a Referência de Tipos para Blocos de Conteúdo e a Referência de Classes de Erro para os tipos exatos por trás de cada regra.

A - Configuração e Ajustes

• Instale com npm install @anthropic-ai/sdk e fixe uma versão em produção. O SDK é baseado em fetch, então ele roda sem modificações no Node.js e em runtimes de edge como Vercel Edge, Cloudflare Workers e Deno Deploy.
• Use TypeScript 5 ou mais recente. O SDK envia seus próprios tipos, e compiladores mais antigos podem resolver incorretamente as uniões discriminadas que ele exporta.
• Leia a chave de API de uma variável de ambiente, nunca a codifique. Defina ANTHROPIC_API_KEY e deixe o cliente pegá-la automaticamente.
• Confirme o runtime de destino antes de escrever código específico da plataforma. Runtimes Node e de edge funcionam, mas apenas o Node tem acesso a APIs exclusivas do Node; mantenha o código de integração agnóstico ao runtime sempre que possível.

B - Segurança de Tipos Acima de any

• Use os tipos exportados pelo SDK em vez de interfaces criadas manualmente. Digitar requisições e respostas por conta própria convida a desvios no momento em que o SDK adiciona um campo.
• Estreite os blocos de conteúdo por .type antes de tocar em campos específicos do bloco. TextBlock, ToolUseBlock e ThinkingBlock são uniões discriminadas; um switch ou if em .type é o que torna os campos mais estreitos seguros para acesso.
• Nunca faça um cast do input de um bloco tool_use para any. Analise-o através do mesmo schema que você usou para definir a ferramenta, para que uma entrada malformada falhe em uma verificação de tempo de execução em vez de passar silenciosamente.
• Deixe a inferência carregar os tipos de conteúdo da mensagem através de suas próprias funções. Redigitar MessageParam ou ContentBlock manualmente é uma fonte comum de erros de tipo que só aparecem no local da chamada, não na definição.

C - Streaming com Iteradores Assíncronos

• Consuma respostas transmitidas com um loop for await, não com listeners de eventos manuais. client.messages.stream() retorna um iterador assíncrono; iterar sobre ele é mais simples de ler e mais simples de cancelar do que configurar manipuladores .on().
• Saia do loop de forma limpa quando tiver o que precisa. Um loop for await sai e limpa com break, o que é mais previsível do que desmontar múltiplos listeners de eventos manualmente.
• Chame stream.finalMessage() quando precisar da resposta totalmente montada. Use isso após o loop quando sua UI quiser tanto os deltas token a token quanto a mensagem final combinada.

D - Definições de Ferramentas Baseadas em Zod

• Defina schemas de entrada de ferramentas como objetos Zod e gere JSON Schema a partir deles. Isso mantém uma única fonte de verdade em vez de manter um JSON Schema escrito manualmente ao lado de um tipo TypeScript escrito manualmente.
• Reutilize o mesmo schema Zod para validar tool_use.input em tempo de execução. O tipo em tempo de compilação e a verificação em tempo de execução vêm da mesma definição, então eles não podem se desviar.
• Mantenha os schemas de ferramentas pequenos e de propósito único. Um objeto Zod de escopo estreito é mais fácil de validar corretamente e mais fácil para o modelo preencher com precisão.

E - Retentativa, Timeout e Cancelamento

• Defina timeout em milissegundos, não em segundos. A opção timeout do SDK TypeScript está em milissegundos, diferente dos SDKs Python e Ruby, que usam segundos; misturar isso silenciosamente produz um timeout que é 1000x muito curto ou muito longo.
• Configure retentativas deliberadamente em vez de aceitar um padrão em todos os lugares. Defina maxRetries no nível do cliente para chamadas típicas e substitua-o por requisição para chamadas que são caras de repetir.
• Conecte um AbortController a qualquer requisição que o usuário possa cancelar. Passar seu signal para uma requisição permite cancelar chamadas em andamento de forma limpa, e funciona da mesma maneira no Node e no navegador.
• Defina overrides de timeout e retentativa por requisição para chamadas de longa duração ou de streaming. Uma única configuração global do cliente raramente se encaixa tanto em uma chamada de classificação rápida quanto em uma resposta transmitida longa.

F - Tratamento de Erros Tipado

• Capture a classe de erro mais específica primeiro. Verifique BadRequestError, RateLimitError e classes específicas semelhantes antes de recorrer ao APIError base.
• Verifique APIConnectionError antes da verificação base APIError. APIConnectionError é uma subclasse de APIError no SDK TypeScript, então um bloco catch que verifica a classe base primeiro engolirá erros de conexão no branch errado.
• Use verificações instanceof contra as classes de erro do SDK, não correspondência de strings em error.message. Isso dá ao bloco catch acesso tipado a campos como .status e .error em vez de analisar texto livre.
• Registre o nome da classe de erro junto com a mensagem. Ao triar incidentes, saber se uma falha foi RateLimitError versus APIConnectionError muda a correção.

G - Implantação em Runtime de Edge

• Implante em Vercel Edge, Cloudflare Workers ou Deno Deploy sem um shim de compatibilidade. O cliente é baseado em fetch, então ele funciona nesses runtimes da mesma forma que funciona no Node.
• Conecte client.messages.stream() a um manipulador de rota para UIs de chat token a token. Este é o padrão comum para um endpoint de chat de streaming Next.js: o manipulador de rota transmite deltas diretamente para o cliente.
• Mantenha ANTHROPIC_API_KEY apenas no lado do servidor. Funções de edge ainda rodam no servidor; nunca envie a chave para um bundle do cliente ou a exponha através de um endpoint público sem uma camada de proxy na frente dela.
• Teste o comportamento de cold-start em sua plataforma de edge escolhida antes de confiar nela para endpoints sensíveis à latência. Runtimes de edge trocam algumas APIs exclusivas do Node por cold starts mais rápidos; confirme se a troca funciona para seu padrão de tráfego.

FAQs

Relacionados

• Noções Básicas do SDK TypeScript/JavaScript - instale e envie sua primeira chamada tipada
• O Modelo Mental do SDK Anthropic TypeScript - como streaming, tipagem e erros se encaixam
• Referência de Tipos do SDK TypeScript para Blocos de Conteúdo - a união discriminada em detalhe
• Referência de Classes de Erro do SDK TypeScript - a hierarquia completa de classes de erro
• Padrões de Retentativa, Timeout e AbortController no SDK TypeScript - cobertura mais aprofundada do grupo E
• Construindo um Endpoint de Chat de Streaming com Next.js e o SDK TypeScript - o padrão por trás do grupo G

Versões de 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-ai/sdk TypeScript (último lançamento). 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.