CLI, SDKs e bibliotecasSDKs de cliente

SDK Go

Instale e configure o SDK Go da Anthropic com cancelamento baseado em contexto e opções funcionais

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

Para documentação de recursos da API com exemplos de código, consulte a referência da API. Esta página cobre recursos e configurações do SDK específicos de 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.ModelClaudeOpus5,
	})
	if err != nil {
		panic(err.Error())
	}
	for _, block := range message.Content {
		if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
			fmt.Println(textBlock.Text)
		}
	}
}

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

Campos de requisição

A biblioteca anthropic usa a semântica de 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 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.

Por razões de segurança, use SetExtraFields apenas com dados confiáveis.

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)).

// Nos casos em que a API especifica um determinado tipo,
// mas você quer enviar outra coisa, 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 por meio 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

param.SetJSON requer o SDK v1.20.0 ou posterior.

Tipos param (tipos terminados em Param, como MessageNewParams ou ToolUnionParam) são projetados apenas para requisições de saída. Eles são serializados corretamente para JSON, mas não oferecem suporte completo à 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 a re-serialização correta:

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

// Depois, reconstrói os params 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 da 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 à função mais geral param.Override[T](any) porque não exige 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 será 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

Nas respostas, unions são representadas por uma struct achatada contendo todos os campos possíveis de cada uma das variantes do 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 ao lado das propriedades, mas prefixados com Of e com 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")
}

// Faz o switch 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 com o 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 da resposta, o 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.ModelClaudeOpus5,
})
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.ModelClaudeOpus5,
		},
		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 tempo limite da solicitaçã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.ModelClaudeOpus5,
		},
		// Isso define o tempo limite por tentativa
		option.WithRequestTimeout(20*time.Second),
	)

Requisições longas

Considere usar a API de Messages com streaming para requisições de execução mais longa.

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 mais de aproximadamente 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", portanto 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 do io.Reader. Observe que os.File implementa Name() string, então um arquivo retornado por os.Open será enviado com o nome do arquivo em disco.

Paginação

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

Você pode usar os métodos .ListAutoPaging() para iterar pelos 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 os 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 um 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.

Consulte 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

Para guias detalhados de configuração de plataforma com exemplos de código, consulte:

O SDK Go oferece suporte às seguintes plataformas:

Agent Platform: import "github.com/anthropics/anthropic-sdk-go/vertex". Use vertex.WithGoogleAuth(ctx, region, projectID) ou vertex.WithCredentials(ctx, region, projectID, creds).
Bedrock: import "github.com/anthropics/anthropic-sdk-go/bedrock". Use bedrock.NewMantleClient para o endpoint Bedrock da Messages-API (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 (por meio do init() do pacote). Isso se aplica tanto se você usar o caminho bedrock-runtime WithConfig/WithLoadDefaultConfig quanto NewMantleClient.
Claude Platform na AWS: import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws". Use anthropicaws.NewClient(ctx, cfg) com um valor anthropicaws.ClientConfig para construir um cliente; defina WorkspaceID na configuração ou a variável de ambiente ANTHROPIC_AWS_WORKSPACE_ID. O alias de importação anthropicaws evita uma colisão de nomes com github.com/aws/aws-sdk-go-v2/aws quando ambos são importados. Disponível em beta.
Foundry: Atualmente não suportado no SDK Go. Consulte Claude no Microsoft Foundry para os 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 da 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.

// Cria 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.ModelClaudeOpus5,
	},
	option.WithResponseInto(&response),
)
if err != nil {
	// trata 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, params 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. As 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 com encoding/json,
	// ou uma struct "...Params" definida nesta biblioteca.
	params map[string]any

	// result pode ser um []byte, *http.Response, um objeto desserializável com 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 por meio 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 menores:

Mudanças em componentes internos da biblioteca que são tecnicamente públicos, mas não destinados ou documentados para uso externo.
Mudanças que não se espera que impactem 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

Was this page helpful?

CLI, SDKs e bibliotecasSDKs de cliente

SDK Go

Instale e configure o SDK Go da Anthropic com cancelamento baseado em contexto e opções funcionais

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

Para documentação de recursos da API com exemplos de código, consulte a referência da API. Esta página cobre recursos e configurações do SDK específicos de 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.ModelClaudeOpus5,
	})
	if err != nil {
		panic(err.Error())
	}
	for _, block := range message.Content {
		if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
			fmt.Println(textBlock.Text)
		}
	}
}

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

Campos de requisição

A biblioteca anthropic usa a semântica de 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 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

Por razões de segurança, use SetExtraFields apenas com dados confiáveis.

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)).

// Nos casos em que a API especifica um determinado tipo,
// mas você quer enviar outra coisa, 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 por meio 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

param.SetJSON requer o SDK v1.20.0 ou posterior.

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

// Depois, reconstrói os params 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 da 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

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 será 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

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

Unions de resposta

Se uma union de valor de resposta contiver valores primitivos, os campos primitivos estarão ao lado das propriedades, mas prefixados com Of e com 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")
}

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

Tratamento de erros

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.ModelClaudeOpus5,
})
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

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.ModelClaudeOpus5,
		},
		option.WithMaxRetries(5),
	)

Timeouts

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 tempo limite da solicitaçã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.ModelClaudeOpus5,
		},
		// Isso define o tempo limite por tentativa
		option.WithRequestTimeout(20*time.Second),
	)

Requisições longas

Considere usar a API de Messages com streaming para requisições de execução mais longa.

Upload de arquivos

// 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"),
}

Paginação

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

Você pode usar os métodos .ListAutoPaging() para iterar pelos 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 os 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

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.

Consulte 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

Para guias detalhados de configuração de plataforma com exemplos de código, consulte:

O SDK Go oferece suporte às seguintes plataformas:

Agent Platform: import "github.com/anthropics/anthropic-sdk-go/vertex". Use vertex.WithGoogleAuth(ctx, region, projectID) ou vertex.WithCredentials(ctx, region, projectID, creds).
Bedrock: import "github.com/anthropics/anthropic-sdk-go/bedrock". Use bedrock.NewMantleClient para o endpoint Bedrock da Messages-API (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 (por meio do init() do pacote). Isso se aplica tanto se você usar o caminho bedrock-runtime WithConfig/WithLoadDefaultConfig quanto NewMantleClient.
Claude Platform na AWS: import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws". Use anthropicaws.NewClient(ctx, cfg) com um valor anthropicaws.ClientConfig para construir um cliente; defina WorkspaceID na configuração ou a variável de ambiente ANTHROPIC_AWS_WORKSPACE_ID. O alias de importação anthropicaws evita uma colisão de nomes com github.com/aws/aws-sdk-go-v2/aws quando ambos são importados. Disponível em beta.
Foundry: Atualmente não suportado no SDK Go. Consulte Claude no Microsoft Foundry para os 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 da resposta (por exemplo, cabeçalhos de resposta)

// Cria 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.ModelClaudeOpus5,
	},
	option.WithResponseInto(&response),
)
if err != nil {
	// trata 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, params ou propriedades de resposta não documentados, a biblioteca ainda pode ser usada.

Endpoints não documentados

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

	// result pode ser um []byte, *http.Response, um objeto desserializável com 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

Quaisquer campos que não estejam presentes na struct de resposta são salvos e podem ser acessados por meio 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 menores:

Mudanças em componentes internos da biblioteca que são tecnicamente públicos, mas não destinados ou documentados para uso externo.
Mudanças que não se espera que impactem 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

Was this page helpful?

Instalação

Requisitos

Uso

Conversas

Prompts do sistema

Streaming

Chamada de ferramentas

Campos de requisição

Unions de requisição

Desserializando params

Objetos de resposta

Unions de resposta

Tratamento de erros

Novas tentativas

Timeouts

Requisições longas

Upload de arquivos

Paginação

RequestOptions

Personalização do cliente HTTP

Integrações de plataforma

Uso avançado

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

Fazendo requisições personalizadas/não documentadas

Endpoints não documentados

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

Propriedades de resposta não documentadas

Versionamento semântico

Recursos adicionais

Instalação

Requisitos

Uso

Conversas

Prompts do sistema

Streaming

Chamada de ferramentas

Campos de requisição

Unions de requisição

Desserializando params

Objetos de resposta

Unions de resposta

Tratamento de erros

Novas tentativas

Timeouts

Requisições longas

Upload de arquivos

Paginação

RequestOptions

Personalização do cliente HTTP

Integrações de plataforma

Uso avançado

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

Fazendo requisições personalizadas/não documentadas

Endpoints não documentados

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

Propriedades de resposta não documentadas

Versionamento semântico

Recursos adicionais

Instalação

Requisitos

Uso

Campos de requisição

Unions de requisição

Desserializando params

Objetos de resposta

Unions de resposta

Tratamento de erros

Novas tentativas

Timeouts

Requisições longas

Upload de arquivos

Paginação

RequestOptions

Personalização do cliente HTTP

Integrações de plataforma

Uso avançado

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

Fazendo requisições personalizadas/não documentadas

Endpoints não documentados

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

Propriedades de resposta não documentadas

Versionamento semântico

Recursos adicionais

Instalação

Requisitos

Uso

Campos de requisição

Unions de requisição

Desserializando params

Objetos de resposta

Unions de resposta

Tratamento de erros

Novas tentativas

Timeouts

Requisições longas

Upload de arquivos

Paginação

RequestOptions

Personalização do cliente HTTP

Integrações de plataforma

Uso avançado

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

Fazendo requisições personalizadas/não documentadas

Endpoints não documentados

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

Propriedades de resposta não documentadas

Versionamento semântico

Recursos adicionais