SDK para Go

A biblioteca Go da Anthropic fornece acesso conveniente à API REST da Anthropic a partir de aplicações escritas em Go.

Instalação

import (
	"github.com/anthropics/anthropic-sdk-go" // imported as anthropic
)

Instale com go get:

go get github.com/anthropics/anthropic-sdk-go

Requisitos

Esta biblioteca requer Go 1.23+.

Uso

package main

import (
	"context"
	"fmt"

	"github.com/anthropics/anthropic-sdk-go"
	"github.com/anthropics/anthropic-sdk-go/option"
)

func main() {
	client := anthropic.NewClient(
		option.WithAPIKey("my-anthropic-api-key"), // defaults to os.LookupEnv("ANTHROPIC_API_KEY")
	)
	message, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
		MaxTokens: 1024,
		Messages: []anthropic.MessageParam{
			anthropic.NewUserMessage(anthropic.NewTextBlock("What is a quaternion?")),
		},
		Model: anthropic.ModelClaudeOpus4_8,
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", message.Content)
}

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação.

Campos de requisição

A biblioteca anthropic usa a semântica omitzero da versão encoding/json do Go 1.24+ para campos de requisição.

Campos primitivos obrigatórios (int64, string, etc.) apresentam a tag `json:"...,required"`. Esses campos são sempre serializados, mesmo com seus valores zero.

Tipos primitivos opcionais são encapsulados em um param.Opt[T]. Esses campos podem ser definidos com os construtores fornecidos, anthropic.String(string), anthropic.Int(int64), etc.

Qualquer param.Opt[T], map, slice, struct ou enum de string usa a tag `json:"...,omitzero"`. Seu valor zero é considerado omitido.

A função param.IsOmitted(any) pode confirmar a presença de qualquer campo omitzero.

p := anthropic.ExampleParams{
	ID:   "id_xxx",                // required property
	Name: anthropic.String("..."), // optional property

	Point: anthropic.Point{
		X: 0,                // required field will serialize as 0
		Y: anthropic.Int(1), // optional field will serialize as 1
		// ... campos não obrigatórios omitidos não serão serializados
	},

	Origin: anthropic.Origin{}, // the zero value of [Origin] is considered omitted
}

Para enviar null em vez de um param.Opt[T], use param.Null[T](). Para enviar null em vez de uma struct T, use param.NullStruct[T]().

p.Name = param.Null[string]()       // 'null' instead of string
p.Point = param.NullStruct[Point]() // 'null' instead of struct

param.IsNull(p.Name)  // true
param.IsNull(p.Point) // true

Structs de requisição contêm um método .SetExtraFields(map[string]any) que pode enviar campos não conformes no corpo da requisição. Campos extras sobrescrevem quaisquer campos da struct com uma chave correspondente.

Para enviar um valor personalizado em vez de uma struct, use a função genérica param.Override (por exemplo, param.Override[anthropic.FooParams](12)).

// Em casos em que a API especifica um determinado tipo,
// mas você quer enviar algo diferente, use [SetExtraFields]:
p.SetExtraFields(map[string]any{
	"x": 0.01, // send "x" as a float instead of int
})

// Envia um número em vez de um objeto
custom := param.Override[anthropic.FooParams](12)

Unions de requisição

Unions são representadas como uma struct com campos prefixados por "Of" para cada uma de suas variantes; apenas um campo pode ser diferente de zero. O campo diferente de zero será serializado.

Subpropriedades da union podem ser acessadas através de métodos na struct da union. Esses métodos retornam um ponteiro mutável para os dados subjacentes, se presentes.

// Apenas um campo pode ser diferente de zero, use param.IsOmitted() para verificar se um campo está definido
type AnimalUnionParam struct {
	OfCat *Cat `json:",omitzero,inline"`
	OfDog *Dog `json:",omitzero,inline"`
}

animal := AnimalUnionParam{
	OfCat: &Cat{
		Name: "Whiskers",
		Owner: PersonParam{
			Address: AddressParam{Street: "3333 Coyote Hill Rd", ZipCode: 0},
		},
	},
}

// Modificando um campo
if address := animal.GetOwner().GetAddress(); address != nil {
	address.ZipCode = 94304
}

Desserializando params

Tipos param (tipos que terminam em Param, como MessageNewParams ou ToolUnionParam) são projetados apenas para requisições de saída. Eles serializam corretamente para JSON, mas não suportam totalmente a desserialização de ida e volta. Se você desserializar JSON bruto em uma struct param, campos de union tipados como OfBashTool20250124 serão nil mesmo quando o JSON subjacente for válido.

Se você precisar reconstruir params a partir de JSON bruto (por exemplo, de um banco de dados, middleware ou uma requisição anterior), chame UnmarshalJSON para preencher campos que não são union e, em seguida, use param.SetJSON para anexar os bytes brutos para uma re-serialização correta:

// Serializa os parâmetros (por exemplo, para armazenamento ou encaminhamento)
b, err := json.Marshal(original)
if err != nil {
	panic(err)
}

// Depois, reconstrói os parâmetros a partir do JSON armazenado
var params anthropic.MessageNewParams
if err := params.UnmarshalJSON(b); err != nil {
	panic(err)
}
param.SetJSON(b, &params)

// params.Model e outros campos escalares são preenchidos por UnmarshalJSON.
// params.Tools[0].OfBashTool20250124 é nil (a limitação do union),
// mas o JSON bruto é preservado. Quando params é serializado novamente
// para a chamada de API, as ferramentas são serializadas corretamente.
b2, _ := json.Marshal(params)
fmt.Println(string(b) == string(b2)) // true

Para este caso de uso, param.SetJSON (disponível desde a v1.20.0) é preferível em relação ao mais genérico param.Override[T](any) porque não requer especificar o parâmetro de tipo e torna explícita a intenção de ida e volta.

Objetos de resposta

Todos os campos em structs de resposta são tipos de valor comuns (não ponteiros ou wrappers). Structs de resposta também incluem um campo especial JSON contendo metadados sobre cada propriedade.

type Animal struct {
	Name   string `json:"name,nullable"`
	Owners int    `json:"owners"`
	Age    int    `json:"age"`
	JSON   struct {
		Name        respjson.Field
		Owners      respjson.Field
		Age         respjson.Field
		ExtraFields map[string]respjson.Field
	} `json:"-"`
}

Para lidar com dados opcionais, use o método .Valid() no campo JSON. .Valid() retorna true quando o campo está presente, não é null e foi desserializado com sucesso.

Se .Valid() for false, o campo correspondente terá seu valor zero.

raw := `{"owners": 1, "name": null}`

var res Animal
json.Unmarshal([]byte(raw), &res)

// Acessando campos regulares

res.Owners // 1
res.Name   // ""
res.Age    // 0

// Verificações de campos opcionais

res.JSON.Owners.Valid() // true
res.JSON.Name.Valid()   // false
res.JSON.Age.Valid()    // false

// Valores JSON brutos

res.JSON.Owners.Raw()                  // "1"
res.JSON.Name.Raw() == "null"          // true
res.JSON.Name.Raw() == respjson.Null   // true
res.JSON.Age.Raw() == ""               // true
res.JSON.Age.Raw() == respjson.Omitted // true

Essas structs .JSON também incluem um map ExtraFields contendo quaisquer propriedades na resposta json que não foram especificadas na struct. Isso pode ser útil para recursos da API ainda não presentes no SDK.

body := res.JSON.ExtraFields["my_unexpected_field"].Raw()

Unions de resposta

Em respostas, unions são representadas por uma struct achatada contendo todos os campos possíveis de cada uma das variantes de objeto. Para convertê-la em uma variante, use o método .AsFooVariant() ou o método .AsAny(), se presente.

Se uma union de valor de resposta contiver valores primitivos, os campos primitivos estarão junto das propriedades, mas prefixados com Of e apresentarão a tag json:"...,inline".

type AnimalUnion struct {
	// Das variantes [Dog], [Cat]
	Owner Person `json:"owner"`
	// Da variante [Dog]
	DogBreed string `json:"dog_breed"`
	// Da variante [Cat]
	CatBreed string `json:"cat_breed"`
	// ...

	JSON struct {
		Owner respjson.Field
		// ...
	} `json:"-"`
}

// Se for a variante animal
if animal.Owner.Address.ZipCode == "" {
	panic("missing zip code")
}

// Alterna com base na variante
switch variant := animal.AsAny().(type) {
case Dog:
case Cat:
default:
	panic("unexpected type")
}

Tratamento de erros

Quando a API retorna um código de status de não sucesso, o SDK retorna um erro do tipo *anthropic.Error. Ele contém os valores StatusCode, *http.Request e *http.Response da requisição, bem como o JSON do corpo do erro (assim como outros objetos de resposta no SDK). O erro também inclui o RequestID dos cabeçalhos de resposta, que é útil para solução de problemas com o suporte da Anthropic.

Para tratar erros, use o padrão errors.As:

_, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
	MaxTokens: 1024,
	Messages: []anthropic.MessageParam{{
		Content: []anthropic.ContentBlockParamUnion{{
			OfText: &anthropic.TextBlockParam{
				Text: "What is a quaternion?",
			},
		}},
		Role: anthropic.MessageParamRoleUser,
	}},
	Model: anthropic.ModelClaudeOpus4_8,
})
if err != nil {
	var apierr *anthropic.Error
	if errors.As(err, &apierr) {
		println("Request ID:", apierr.RequestID)
		println(string(apierr.DumpRequest(true)))  // Prints the serialized HTTP request
		println(string(apierr.DumpResponse(true))) // Prints the serialized HTTP response
	}
	panic(err.Error()) // POST "/v1/messages": 400 Bad Request (Request-ID: req_xxx) { ... }
}

Quando outros erros ocorrem, eles são retornados sem encapsulamento; por exemplo, se o transporte HTTP falhar, você pode receber *url.Error encapsulando *net.OpError.

Novas tentativas

Certos erros serão automaticamente repetidos 2 vezes por padrão, com um curto backoff exponencial. O SDK repete por padrão todos os erros de conexão, 408 Request Timeout, 409 Conflict, 429 Rate Limit e erros internos >=500.

Você pode usar a opção WithMaxRetries para configurar ou desabilitar isso:

// Configure o padrão para todas as requisições:
client := anthropic.NewClient(
	option.WithMaxRetries(0), // default is 2
)

// Substitua por requisição:
// ...
	client.Messages.New(
		context.TODO(),
		anthropic.MessageNewParams{
			MaxTokens: 1024,
			Messages: []anthropic.MessageParam{{
				Content: []anthropic.ContentBlockParamUnion{{
					OfText: &anthropic.TextBlockParam{
						Text: "What is a quaternion?",
					},
				}},
				Role: anthropic.MessageParamRoleUser,
			}},
			Model: anthropic.ModelClaudeOpus4_8,
		},
		option.WithMaxRetries(5),
	)

Timeouts

Requisições de Messages sem streaming expiram após 10 minutos por padrão; outras requisições não têm timeout padrão. Use context para configurar um timeout para o ciclo de vida de uma requisição.

Observe que, se uma requisição for repetida, o timeout do context não recomeça. Para definir um timeout por tentativa, use option.WithRequestTimeout().

// Isso define o timeout para a requisição, incluindo todas as novas tentativas.
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()
// ...
	client.Messages.New(
		ctx,
		anthropic.MessageNewParams{
			MaxTokens: 1024,
			Messages: []anthropic.MessageParam{{
				Content: []anthropic.ContentBlockParamUnion{{
					OfText: &anthropic.TextBlockParam{
						Text: "What is a quaternion?",
					},
				}},
				Role: anthropic.MessageParamRoleUser,
			}},
			Model: anthropic.ModelClaudeOpus4_8,
		},
		// Isso define o timeout por tentativa
		option.WithRequestTimeout(20*time.Second),
	)

Requisições longas

Evite definir um valor grande de MaxTokens sem usar streaming, pois algumas redes podem descartar conexões ociosas após um certo período de tempo, o que pode fazer com que a requisição falhe ou expire sem receber uma resposta da Anthropic.

Este SDK também retornará um erro se for esperado que uma requisição sem streaming dure aproximadamente mais de 10 minutos. Chamar .Messages.NewStreaming() ou definir um timeout personalizado desabilita esse erro.

Upload de arquivos

Parâmetros de requisição que correspondem a uploads de arquivos em requisições multipart são tipados como io.Reader. O conteúdo do io.Reader será, por padrão, enviado como uma parte de formulário multipart com o nome de arquivo "anonymous_file" e content-type "application/octet-stream", então a abordagem recomendada é especificar um content-type personalizado com o helper anthropic.File(reader io.Reader, filename string, contentType string), que encapsula qualquer io.Reader com o nome de arquivo e content-type apropriados.

// Um arquivo do sistema de arquivos
file, err := os.Open("/path/to/file.json")
anthropic.BetaFileUploadParams{
	File: anthropic.File(file, "custom-name.json", "application/json"),
}

// Um arquivo a partir de uma string
anthropic.BetaFileUploadParams{
	File: anthropic.File(strings.NewReader("my file contents"), "custom-name.json", "application/json"),
}

O nome do arquivo e o content-type também podem ser personalizados implementando Name() string ou ContentType() string no tipo em tempo de execução de io.Reader. Observe que os.File implementa Name() string, então um arquivo retornado por os.Open será enviado com o nome do arquivo no disco.

Paginação

Esta biblioteca fornece algumas conveniências para trabalhar com endpoints de lista paginados.

Você pode usar métodos .ListAutoPaging() para iterar por itens em todas as páginas:

iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
	Limit: anthropic.Int(20),
})
// Busca automaticamente mais páginas conforme necessário.
for iter.Next() {
	messageBatch := iter.Current()
	fmt.Printf("%+v\n", messageBatch)
}
if err := iter.Err(); err != nil {
	panic(err.Error())
}

Ou você pode usar métodos simples .List() para buscar uma única página e receber um objeto de resposta padrão com métodos auxiliares adicionais como .GetNextPage():

page, err := client.Messages.Batches.List(context.TODO(), anthropic.MessageBatchListParams{
	Limit: anthropic.Int(20),
})
for page != nil {
	for _, batch := range page.Data {
		fmt.Printf("%+v\n", batch)
	}
	page, err = page.GetNextPage()
}
if err != nil {
	panic(err.Error())
}

RequestOptions

Esta biblioteca usa o padrão de opções funcionais. Funções definidas no pacote option retornam uma RequestOption, que é uma closure que modifica uma RequestConfig. Essas opções podem ser fornecidas ao cliente ou em requisições individuais. Por exemplo:

client := anthropic.NewClient(
	// Adiciona um cabeçalho a cada requisição feita pelo cliente
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.Messages.New(context.TODO(), // ...,
	// Sobrescreve o cabeçalho
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Adiciona um campo não documentado ao corpo da requisição, usando a sintaxe sjson
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

A opção de requisição option.WithDebugLog(nil) pode ser útil durante a depuração.

Veja a lista completa de opções de requisição.

Personalização do cliente HTTP

Para middleware de requisição (option.WithMiddleware) e substituição do http.Client padrão (option.WithHTTPClient), consulte Middleware do SDK.

Integrações de plataforma

O SDK Go suporta as seguintes plataformas:

• Bedrock: import "github.com/anthropics/anthropic-sdk-go/bedrock". Use bedrock.NewMantleClient para o endpoint Bedrock da API de Messages (faz streaming via SSE), ou bedrock.WithLoadDefaultConfig(ctx) / bedrock.WithConfig(cfg) (caminho bedrock-runtime). Importar o pacote bedrock registra globalmente um decodificador para application/vnd.amazon.eventstream na camada de streaming do SDK (através do init() do pacote). Isso se aplica tanto se você usar o caminho WithConfig/WithLoadDefaultConfig do bedrock-runtime quanto NewMantleClient.
• Vertex AI: import "github.com/anthropics/anthropic-sdk-go/vertex". Use vertex.WithGoogleAuth(ctx, region, projectID) ou vertex.WithCredentials(ctx, region, projectID, creds).
• Atualmente não suportado no SDK Go. Consulte para SDKs suportados.

Use bedrock.NewMantleClient para novos projetos; bedrock.WithLoadDefaultConfig/WithConfig permanecem para aplicações existentes que usam a API InvokeModel do Bedrock.

Uso avançado

Acessando dados brutos de resposta (por exemplo, cabeçalhos de resposta)

Você pode acessar os dados brutos da resposta HTTP usando a opção de requisição option.WithResponseInto(). Isso é útil quando você precisa examinar cabeçalhos de resposta, códigos de status ou outros detalhes.

// Crie uma variável para armazenar a resposta HTTP
var response *http.Response
message, err := client.Messages.New(
	context.TODO(),
	anthropic.MessageNewParams{
		MaxTokens: 1024,
		Messages: []anthropic.MessageParam{{
			Content: []anthropic.ContentBlockParamUnion{{
				OfText: &anthropic.TextBlockParam{
					Text: "What is a quaternion?",
				},
			}},
			Role: anthropic.MessageParamRoleUser,
		}},
		Model: anthropic.ModelClaudeOpus4_8,
	},
	option.WithResponseInto(&response),
)
if err != nil {
	// trate o erro
}
fmt.Printf("%+v\n", message)

fmt.Printf("Status Code: %d\n", response.StatusCode)
fmt.Printf("Headers: %+#v\n", response.Header)

Fazendo requisições personalizadas/não documentadas

Esta biblioteca é tipada para acesso conveniente à API documentada. Se você precisar acessar endpoints, parâmetros ou propriedades de resposta não documentados, a biblioteca ainda pode ser usada.

Endpoints não documentados

Para fazer requisições a endpoints não documentados, você pode usar client.Get, client.Post e outros verbos HTTP. RequestOptions no cliente, como novas tentativas, serão respeitadas ao fazer essas requisições.

var (
	// params pode ser um io.Reader, um []byte, um objeto serializável por encoding/json,
	// ou uma struct "...Params" definida nesta biblioteca.
	params map[string]any

	// result pode ser um []byte, *http.Response, um objeto desserializável por encoding/json,
	// ou um modelo definido nesta biblioteca.
	result *http.Response
)
err := client.Post(context.Background(), "/unspecified", params, &result)
if err != nil {
	// ...
}

Parâmetros de requisição não documentados

Para fazer requisições usando parâmetros não documentados, você pode usar os métodos option.WithQuerySet() ou option.WithJSONSet().

params := FooNewParams{
	ID: "id_xxxx",
	Data: FooNewParamsData{
		FirstName: anthropic.String("John"),
	},
}
client.Foo.New(context.Background(), params, option.WithJSONSet("data.last_name", "Doe"))

Propriedades de resposta não documentadas

Para acessar propriedades de resposta não documentadas, você pode acessar o JSON bruto da resposta como uma string com result.JSON.RawJSON(), ou obter o JSON bruto de um campo específico no resultado com result.JSON.Foo.Raw().

Quaisquer campos que não estejam presentes na struct de resposta são salvos e podem ser acessados através de result.JSON.ExtraFields, que é um map[string]respjson.Field.

Versionamento semântico

Este pacote geralmente segue as convenções do SemVer, embora certas mudanças incompatíveis com versões anteriores possam ser lançadas como versões minor:

1. Mudanças em partes internas da biblioteca que são tecnicamente públicas, mas não destinadas ou documentadas para uso externo.
2. Mudanças que não devem impactar a grande maioria dos usuários na prática.

A compatibilidade com versões anteriores é levada a sério para garantir que você possa contar com uma experiência de atualização tranquila.

Seu feedback é bem-vindo; abra uma issue com perguntas, bugs ou sugestões.

Recursos adicionais

• Repositório no GitHub
• Documentação do pacote Go
• Referência da API
• Streaming de Messages