Outras SDKs e Boas Práticas de Compatibilidade com OpenAI

Um checklist para escolher entre um SDK nativo Go, Java, C#, PHP ou Ruby e o atalho de migração compatível com OpenAI, e para usar cada um bem depois de escolhido.

Como Usar Este Checklist

• Trabalhe primeiro na seção A se você ainda não escolheu um caminho de integração; as seções B-D assumem que você já tem um.
• Releia esta lista sempre que adicionar uma nova linguagem a um backend poliglota, ou quando um protótipo de camada de compatibilidade estiver prestes a se tornar uma solução permanente.
• Trate os itens não marcados como perguntas abertas a serem resolvidas antes que uma integração Claude vá para produção, não como polimento opcional.

A - Escolhendo um Caminho de Integração

• Combine o SDK com a linguagem do serviço, não com a preferência pessoal. Um serviço Go deve usar anthropic-sdk-go; um aplicativo Ruby deve usar o SDK Ruby, mesmo que a linguagem favorita da equipe seja outra.
• Use a camada de compatibilidade OpenAI apenas como uma ponte, não como um destino. Ela é construída para migração rápida e testes lado a lado, não como o caminho de integração recomendado a longo prazo.
• Verifique a referência de mapeamento de parâmetros antes de migrar uma base de código que usa parâmetros OpenAI incomuns. Penalidades de amostragem, requisições de múltiplas completações e formatos de chamadas de função são os locais mais prováveis para encontrar uma lacuna.
• Planeje o caminho de graduação da camada de compatibilidade com antecedência. Decida, antes de começar, qual condição ("assim que validarmos a qualidade da saída", "assim que o protótipo receber tráfego real") aciona a mudança para o SDK nativo.
• Aceite que um backend poliglota pode usar vários SDKs oficiais simultaneamente. Não há um imposto de compatibilidade entre SDKs; um gateway Go e um service mesh Java podem chamar Claude nativamente sem qualquer sobrecarga de coordenação entre eles.

B - Trabalhando com um SDK Nativo (Go, Java, C#, PHP, Ruby)

• Construa o cliente uma vez e reutilize-o. Construir um novo cliente por requisição (especialmente em Go, Java e C#) descarta o pooling de conexões e adiciona latência evitável.
• Leia a chave de API da configuração do ambiente, não de strings codificadas. O construtor do cliente de cada SDK aceita uma chave de API originada de ANTHROPIC_API_KEY por convenção; mantenha-a fora do controle de versão.
• Defina um max_tokens explícito para cada requisição. Nenhum dos cinco SDKs fornece um padrão implícito razoável; dimensione-o para o comprimento esperado da sua resposta.
• Combine o tratamento de erros com a convenção própria da linguagem, não com os hábitos de outra linguagem. Verifique os erros retornados em Go, capture exceções tipadas em Java e C#, e trate exceções lançadas em PHP e Ruby, da maneira que o código nativo dessa linguagem normalmente faria.
• Trate um motivo de parada tool_use como "aguardando", não como "concluído". Execute a ferramenta solicitada, então envie um tool_result em uma chamada subsequente antes de considerar a troca como completa.

C - Uso Idiomático de Ferramentas Entre Linguagens

• Use o formato de esquema natural de cada linguagem para definições de ferramentas. Structs em Go, builders em Java, objetos tipados em C#, arrays associativos em PHP, hashes em Ruby; não lute contra os idiomas da linguagem para fazer cinco SDKs parecerem idênticos.
• Lembre-se que o protocolo de rede é idêntico, independentemente da sintaxe. Um esquema de ferramenta construído como uma struct Go e um construído como um hash Ruby produzem o mesmo JSON Schema na rede; depure no nível do protocolo quando algo parecer errado, não apenas no nível da linguagem.
• Combine cada tool_result com seu ID tool_use de origem. Este requisito é idêntico em todos os cinco SDKs; um ID incorreto ou ausente produz uma requisição rejeitada, não importa qual linguagem a enviou.
• Valide o formato de entrada da ferramenta no lado do receptor, especialmente em PHP e Ruby. Nenhuma das linguagens verifica o tipo da requisição ou resposta em tempo de compilação, então adicione sua própria validação antes de confiar em campos como a entrada de uma ferramenta.

D - Streaming em Java e C#

• Consuma o stream do Java através de try-with-resources. StreamResponse mantém uma conexão HTTP aberta; falhar em fechá-la vaza conexões sob carga sustentada.
• Mantenha as chamadas de streaming do C# totalmente assíncronas de ponta a ponta. Use await foreach dentro de uma cadeia de métodos async; chamar .Result ou .Wait() em uma chamada de streaming arrisca deadlocks e derrota o propósito de IAsyncEnumerable.
• Não assuma que os deltas de texto se alinham com os limites de palavras ou frases. Armazene em buffer e renderize incrementalmente em ambas as linguagens sem assumir que um delta termina de forma limpa.
• Acumule JSON parcial para entrada tool_use transmitida antes de analisá-lo. Os argumentos de um bloco tool_use podem chegar como fragmentos JSON incompletos; analise apenas quando o evento de parada do bloco for disparado.
• Verifique o motivo final de parada, não apenas o último delta de texto recebido. Uma resposta que parou cedo devido a max_tokens se parece com uma completa se você estiver apenas observando o texto, então leia explicitamente o motivo de parada do evento terminal.

Quando Você Terminar

Trabalhe na seção A uma vez para cada nova integração, e mantenha B-D como uma referência contínua ao construir contra o SDK que o serviço acabar usando.

Se mais de alguns itens na seção A permanecerem desmarcados para um serviço agora em produção na camada de compatibilidade, isso é um sinal de que a migração para um SDK nativo está atrasada, não opcional.

FAQs

Relacionados

• Além de Python e TypeScript: Os Outros SDKs Oficiais Claude - a visão geral conceitual por trás da orientação da seção A
• Migrando uma Base de Código do SDK OpenAI para Claude - o guia completo de migração por trás das seções A e B
• Referência de Mapeamento de Parâmetros da Camada de Compatibilidade OpenAI - os detalhes parâmetro a parâmetro por trás da orientação de mapeamento da seção A
• Uso Idiomático de Ferramentas em Go, Java, C#, PHP e Ruby - a comparação completa por trás da seção C
• Respostas de Streaming em Java e C# com os SDKs Oficiais - o guia completo 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 os SDKs oficiais atuais para Go, Java, C#, PHP e Ruby. 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.