//
Busque em todas as páginas da documentação
anthropic-sdk-go é o cliente Go oficial para a API de Mensagens do Claude, oferecendo aos serviços Go requisições tipadas, um iterador de streaming e suporte estruturado a tool_use sem chamadas HTTP manuais.
anthropic-sdk-go encapsula a mesma API de Mensagens usada por todos os outros SDKs oficiais do Claude, mas construída em torno das convenções do Go: structs tipadas para requisição e resposta, opções funcionais para configuração do cliente e erros retornados como valores em vez de exceções.
Um cliente é um único objeto de longa duração que você constrói uma vez por processo e reutiliza entre as requisições, pois ele contém o transporte HTTP e a chave de API.
As três coisas que a maioria dos serviços Go precisa do Claude são uma chamada simples de requisição/resposta, uma chamada de streaming para saída incremental e um loop tool_use para permitir que o Claude chame funções no seu serviço.
Todos os três ficam na mesma interface client.Messages, diferindo apenas em qual método você chama e como consome o resultado.
Esta página cobre todos os três, na ordem em que a maioria dos serviços Go os adota.
Cartão de receita de referência rápida - pronto para copiar e colar.
client := anthropic.NewClient(
option.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
)
message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeSonnet5,
MaxTokens: 1024,
System: anthropic.String("Você é um assistente conciso."),
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Resuma o scheduler do Go em duas frases.")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(message.Content[0].Text)Quando usar isso:
tool_use.Um único programa Go que constrói um cliente, envia uma requisição de streaming e imprime tokens à medida que chegam.
package main
import (
"context"
"fmt"
"log"
"os"
"github.com/anthropics/anthropic-sdk-go"
"github.com/anthropics/anthropic-sdk-go/option"
)
func main() {
O que isso demonstra:
client.Messages.NewStreaming retorna um iterador que você controla com stream.Next() e stream.Current(), o formato padrão de iterador do Go.message.Accumulate constrói a Message final e completa à medida que os eventos chegam, para que você obtenha tanto o texto incremental quanto um objeto completo no final.ContentBlockDeltaEvent nos quais você usa type switch, correspondendo a como os eventos subjacentes enviados pelo servidor são estruturados.stream.Err() deve ser verificado após o loop terminar, pois uma falha no meio do stream não necessariamente aparece dentro do próprio loop.client.Messages.New emite uma única requisição HTTP bloqueante e retorna uma Message totalmente populada.client.Messages.NewStreaming abre uma conexão de eventos enviados pelo servidor (server-sent events) e expõe cada evento através do iterador; a conexão permanece aberta até message_stop ou um erro.tool_use é apenas outro stop_reason na resposta: quando o Claude decide chamar uma ferramenta, o Content da resposta inclui um bloco tool_use em vez de (ou ao lado de) texto, e StopReason é "tool_use".Definir uma ferramenta significa descrever seu esquema de entrada como uma struct tipada, e então verificar a resposta em busca de um bloco tool_use.
type WeatherInput struct {
City string `json:"city"`
}
weatherTool := anthropic.ToolParam{
Name: anthropic.String("get_weather"),
Description: anthropic.String("Obtém o clima atual para uma cidade."),
InputSchema: anthropic.ToolInputSchemaParam
| Opção | Propósito |
|---|---|
option.WithAPIKey(key) | Define a chave de API explicitamente em vez de ler ANTHROPIC_API_KEY |
option.WithBaseURL(url) | Aponta o cliente para uma URL base diferente (raro; principalmente para proxies ou testes) |
option.WithHTTPClient(httpClient) | Fornece um *http.Client personalizado, útil para pooling de conexão compartilhado ou timeouts personalizados |
option.WithMaxRetries(n) | Substitui a contagem padrão de retentativas do SDK para falhas transitórias |
// Reutilize um cliente em todo o seu serviço; é seguro para uso concorrente.
var claudeClient = anthropic.NewClient(
option.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
)
func handleRequest(ctx context.Context, prompt string) (string, error
context.Context para que os timeouts e cancelamentos de requisição se propaguem corretamente sob carga.%w ao retorná-los na pilha de chamadas, para que os chamadores ainda possam usar errors.As para acessar o tipo de erro subjacente do SDK.anthropic.NewClient dentro de um manipulador de requisição descarta o pooling de conexão e adiciona latência. Correção: construa um cliente na inicialização e reutilize-o.stream.Err() após o loop - um stream que termina cedo devido a um erro de rede ainda sai do loop for stream.Next() normalmente. Correção: sempre verifique stream.Err() após o loop, não apenas dentro dele.Content[0] é sempre texto - uma resposta com tool_use coloca um ToolUseBlock em Content, não um bloco de texto, e indexar cegamente causa um pânico. Correção: verifique o tipo de block.AsAny(), ou verifique StopReason antes de ler Content[0].Text.MaxTokens é obrigatório - omiti-lo produz um erro de validação no momento da requisição em vez de um padrão sensato. Correção: sempre defina um MaxTokens explícito dimensionado para sua resposta esperada.context.Background() em todos os lugares significa que uma requisição lenta ou travada não pode ser cancelada por um timeout upstream. Correção: passe um context.Context com escopo de requisição e um deadline através de cada chamada.tool_use como a resposta final - receber um bloco tool_use significa que o Claude está esperando por um tool_result, não que a tarefa esteja concluída. Correção: execute a ferramenta e, em seguida, envie o resultado de volta em uma chamada Messages.New de acompanhamento antes de tratar a conversa como completa.| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Camada de compatibilidade OpenAI com um cliente Go no formato OpenAI | Você está migrando rapidamente um serviço Go existente integrado com OpenAI e pode tolerar uma superfície de parâmetros mais restrita | Você precisa de recursos completos da API de Mensagens, como tool_use estendido ou os tipos de bloco de conteúdo mais recentes |
Chamadas net/http brutas para a API de Mensagens | Você precisa de algo sem dependências em um binário mínimo | Você deseja requisições tipadas, retentativas e análise de streaming tratadas para você |
| Um SDK oficial diferente (Java, C#, PHP, Ruby) | Seu serviço não é realmente escrito em Go | Você está especificamente trabalhando em uma base de código Go |
Não. Construa anthropic.NewClient uma vez na inicialização e reutilize-o entre as requisições; é seguro para uso concorrente.
client.Messages.NewStreaming retorna um iterador. Chame stream.Next() em um loop, leia stream.Current() para cada evento e verifique stream.Err() após o loop terminar para capturar falhas no meio do stream.
Verifique message.StopReason para "tool_use", depois procure por um ToolUseBlock dentro de message.Content. O bloco carrega o nome da ferramenta e uma entrada codificada em JSON que você desserializa em sua própria struct.
Sim, por padrão ele tenta novamente falhas transitórias como limites de taxa e erros de rede um número limitado de vezes. Você pode substituir a contagem com option.WithMaxRetries(n).
A requisição falha na validação, pois MaxTokens não tem um padrão implícito. Sempre defina-o explicitamente para um valor dimensionado para o seu comprimento de resposta esperado.
Sim. Passe option.WithHTTPClient(httpClient) ao construir o cliente para fornecer seu próprio *http.Client, útil para pools de conexão compartilhados ou comportamento de timeout personalizado.
Sim, um único anthropic.Client é seguro para uso concorrente, razão pela qual você deve construí-lo uma vez e compartilhá-lo em vez de criar um por requisição.
Erros retornam como um valor error normal do Go de cada método, seguindo a convenção do Go. Não há pânico ou exceção; verifique err != nil após cada chamada da mesma forma que faria para qualquer outra API Go.
Apenas em scripts descartáveis. Em um serviço real, passe um context.Context com escopo de requisição e um deadline ou cancelamento, para que uma chamada lenta do Claude possa ser cancelada da mesma forma que qualquer outra chamada downstream seria.
Sim. Model é um campo por requisição, não uma configuração em nível de cliente, então um único cliente pode enviar requisições para Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 ou Claude Haiku 4.5 conforme necessário.
tool_use com os outros quatro SDKsVersõ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 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.