SDK de Go

La biblioteca de Go de Anthropic proporciona acceso conveniente a la API REST de Anthropic desde aplicaciones escritas en Go.

Instalación

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

Instala con go get:

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

Requisitos

Esta biblioteca requiere 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 conocer las opciones de autenticación, incluida Workload Identity Federation, consulta Autenticación.

Campos de solicitud

La biblioteca de anthropic usa la semántica de omitzero de la versión encoding/json de Go 1.24+ para los campos de solicitud.

Los campos primitivos requeridos (int64, string, etc.) incluyen la etiqueta `json:"...,required"`. Estos campos siempre se serializan, incluso sus valores cero.

Los tipos primitivos opcionales están envueltos en un param.Opt[T]. Estos campos se pueden establecer con los constructores proporcionados, anthropic.String(string), anthropic.Int(int64), etc.

Cualquier param.Opt[T], map, slice, struct o enum de tipo string usa la etiqueta `json:"...,omitzero"`. Su valor cero se considera omitido.

La función param.IsOmitted(any) puede confirmar la presencia de cualquier 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
		// ... los campos no obligatorios omitidos no se serializarán
	},

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

Para enviar null en lugar de un param.Opt[T], usa param.Null[T](). Para enviar null en lugar de un struct T, usa 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

Los structs de solicitud contienen un método .SetExtraFields(map[string]any) que puede enviar campos no conformes en el cuerpo de la solicitud. Los campos adicionales sobrescriben cualquier campo del struct con una clave coincidente.

Para enviar un valor personalizado en lugar de un struct, usa la función genérica param.Override (por ejemplo, param.Override[anthropic.FooParams](12)).

// En casos donde la API especifica un tipo determinado,
// pero quieres enviar algo diferente, usa [SetExtraFields]:
p.SetExtraFields(map[string]any{
	"x": 0.01, // send "x" as a float instead of int
})

// Envía un número en lugar de un objeto
custom := param.Override[anthropic.FooParams](12)

Uniones en solicitudes

Las uniones se representan como un struct con campos prefijados con "Of" para cada una de sus variantes; solo un campo puede ser distinto de cero. El campo distinto de cero será serializado.

Se puede acceder a las subpropiedades de la unión a través de métodos en el struct de la unión. Estos métodos devuelven un puntero mutable a los datos subyacentes, si están presentes.

// Solo un campo puede ser distinto de cero; usa param.IsOmitted() para verificar si un 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},
		},
	},
}

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

Deserialización de params

Los tipos param (tipos que terminan en Param, como MessageNewParams o ToolUnionParam) están diseñados únicamente para solicitudes salientes. Se serializan correctamente a JSON pero no admiten completamente la deserialización de ida y vuelta. Si deserializas JSON sin procesar en un struct param, los campos de unión tipados como OfBashTool20250124 serán nil incluso cuando el JSON subyacente sea válido.

Si necesitas reconstruir params a partir de JSON sin procesar (por ejemplo, desde una base de datos, middleware o una solicitud anterior), llama a UnmarshalJSON para rellenar los campos que no son de unión, y luego usa param.SetJSON para adjuntar los bytes sin procesar para una reserialización correcta:

// Serializa los parámetros (por ejemplo, para almacenarlos o reenviarlos)
b, err := json.Marshal(original)
if err != nil {
	panic(err)
}

// Más adelante, reconstruye los parámetros a partir del JSON almacenado
var params anthropic.MessageNewParams
if err := params.UnmarshalJSON(b); err != nil {
	panic(err)
}
param.SetJSON(b, &params)

// params.Model y otros campos escalares son rellenados por UnmarshalJSON.
// params.Tools[0].OfBashTool20250124 es nil (la limitación de la unión),
// pero el JSON sin procesar se conserva. Cuando params se serializa de nuevo
// para la llamada a la API, las herramientas se serializan correctamente.
b2, _ := json.Marshal(params)
fmt.Println(string(b) == string(b2)) // true

Para este caso de uso, se prefiere param.SetJSON (disponible desde v1.20.0) sobre el más general param.Override[T](any) porque no requiere especificar el parámetro de tipo y hace explícita la intención de ida y vuelta.

Objetos de respuesta

Todos los campos en los structs de respuesta son tipos de valor ordinarios (no punteros ni envoltorios). Los structs de respuesta también incluyen un campo especial JSON que contiene metadatos sobre cada propiedad.

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 manejar datos opcionales, usa el método .Valid() en el campo JSON. .Valid() devuelve true cuando el campo está presente, no es null y se deserializó correctamente.

Si .Valid() es false, el campo correspondiente tendrá su valor cero.

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

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

// Acceso a campos regulares

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

// Verificaciones de campos opcionales

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

// Valores JSON sin procesar

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

Estos structs .JSON también incluyen un map ExtraFields que contiene cualquier propiedad en la respuesta json que no se especificó en el struct. Esto puede ser útil para funcionalidades de la API que aún no están presentes en el SDK.

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

Uniones en respuestas

En las respuestas, las uniones se representan mediante un struct aplanado que contiene todos los campos posibles de cada una de las variantes de objeto. Para convertirlo a una variante, usa el método .AsFooVariant() o el método .AsAny() si está presente.

Si una unión de valores de respuesta contiene valores primitivos, los campos primitivos estarán junto a las propiedades pero con el prefijo Of e incluirán la etiqueta json:"...,inline".

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

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

// Si es variante de animal
if animal.Owner.Address.ZipCode == "" {
	panic("missing zip code")
}

// Bifurcar según la variante
switch variant := animal.AsAny().(type) {
case Dog:
case Cat:
default:
	panic("unexpected type")
}

Manejo de errores

Cuando la API devuelve un código de estado no exitoso, el SDK devuelve un error de tipo *anthropic.Error. Este contiene los valores StatusCode, *http.Request y *http.Response de la solicitud, así como el JSON del cuerpo del error (de forma similar a otros objetos de respuesta en el SDK). El error también incluye el RequestID de los encabezados de respuesta, lo cual es útil para solucionar problemas con el soporte de Anthropic.

Para manejar errores, usa el patrón 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) { ... }
}

Cuando ocurren otros errores, se devuelven sin envolver; por ejemplo, si el transporte HTTP falla, podrías recibir *url.Error envolviendo *net.OpError.

Reintentos

Ciertos errores se reintentarán automáticamente 2 veces de forma predeterminada, con un breve retroceso exponencial. El SDK reintenta de forma predeterminada todos los errores de conexión, 408 Request Timeout, 409 Conflict, 429 Rate Limit y errores internos >=500.

Puedes usar la opción WithMaxRetries para configurar o deshabilitar esto:

// Configura el valor predeterminado para todas las solicitudes:
client := anthropic.NewClient(
	option.WithMaxRetries(0), // default is 2
)

// Anula por solicitud:
// ...
	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),
	)

Tiempos de espera

Las solicitudes de Messages sin streaming tienen un tiempo de espera de 10 minutos de forma predeterminada; otras solicitudes no tienen tiempo de espera predeterminado. Usa el contexto para configurar un tiempo de espera para el ciclo de vida de una solicitud.

Ten en cuenta que si una solicitud se reintenta, el tiempo de espera del contexto no se reinicia. Para establecer un tiempo de espera por reintento, usa option.WithRequestTimeout().

// Esto establece el tiempo de espera para la solicitud, incluidos todos los reintentos.
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,
		},
		// Esto establece el tiempo de espera por reintento
		option.WithRequestTimeout(20*time.Second),
	)

Solicitudes largas

Evita establecer un valor grande de MaxTokens sin usar streaming, ya que algunas redes pueden cerrar conexiones inactivas después de cierto período de tiempo, lo que puede causar que la solicitud falle o agote el tiempo de espera sin recibir una respuesta de Anthropic.

Este SDK también devolverá un error si se espera que una solicitud sin streaming dure aproximadamente más de 10 minutos. Llamar a .Messages.NewStreaming() o establecer un tiempo de espera personalizado deshabilita este error.

Carga de archivos

Los parámetros de solicitud que corresponden a cargas de archivos en solicitudes multipart tienen el tipo io.Reader. El contenido del io.Reader se enviará de forma predeterminada como una parte de formulario multipart con el nombre de archivo "anonymous_file" y el content-type "application/octet-stream", por lo que el enfoque recomendado es especificar un content-type personalizado con el helper anthropic.File(reader io.Reader, filename string, contentType string), que envuelve cualquier io.Reader con el nombre de archivo y content-type apropiados.

// Un archivo del sistema de archivos
file, err := os.Open("/path/to/file.json")
anthropic.BetaFileUploadParams{
	File: anthropic.File(file, "custom-name.json", "application/json"),
}

// Un archivo a partir de una cadena
anthropic.BetaFileUploadParams{
	File: anthropic.File(strings.NewReader("my file contents"), "custom-name.json", "application/json"),
}

El nombre de archivo y el content-type también se pueden personalizar implementando Name() string o ContentType() string en el tipo en tiempo de ejecución de io.Reader. Ten en cuenta que os.File implementa Name() string, por lo que un archivo devuelto por os.Open se enviará con el nombre de archivo en disco.

Paginación

Esta biblioteca proporciona algunas facilidades para trabajar con endpoints de lista paginados.

Puedes usar los métodos .ListAutoPaging() para iterar a través de elementos en todas las páginas:

iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
	Limit: anthropic.Int(20),
})
// Obtiene automáticamente más páginas según sea necesario.
for iter.Next() {
	messageBatch := iter.Current()
	fmt.Printf("%+v\n", messageBatch)
}
if err := iter.Err(); err != nil {
	panic(err.Error())
}

O puedes usar los métodos simples .List() para obtener una sola página y recibir un objeto de respuesta estándar con métodos auxiliares adicionales 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 el patrón de opciones funcionales. Las funciones definidas en el paquete option devuelven un RequestOption, que es un closure que muta un RequestConfig. Estas opciones se pueden proporcionar al cliente o en solicitudes individuales. Por ejemplo:

client := anthropic.NewClient(
	// Agrega un encabezado a cada solicitud realizada por el cliente
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.Messages.New(context.TODO(), // ...,
	// Sobrescribe el encabezado
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Agrega un campo no documentado al cuerpo de la solicitud, usando sintaxis sjson
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

La opción de solicitud option.WithDebugLog(nil) puede ser útil durante la depuración.

Consulta la lista completa de opciones de solicitud.

Personalización del cliente HTTP

Para middleware de solicitudes (option.WithMiddleware) y reemplazar el http.Client predeterminado (option.WithHTTPClient), consulta Middleware del SDK.

Integraciones de plataforma

El SDK de Go admite las siguientes plataformas:

• Bedrock: import "github.com/anthropics/anthropic-sdk-go/bedrock". Usa bedrock.NewMantleClient para el endpoint de Bedrock de la API de Messages (transmite mediante SSE), o bedrock.WithLoadDefaultConfig(ctx) / bedrock.WithConfig(cfg) (ruta bedrock-runtime). Importar el paquete bedrock registra globalmente un decodificador para application/vnd.amazon.eventstream en la capa de streaming del SDK (a través de init() del paquete). Esto aplica tanto si usas la ruta WithConfig/WithLoadDefaultConfig de bedrock-runtime como si usas NewMantleClient.
• Vertex AI: import "github.com/anthropics/anthropic-sdk-go/vertex". Usa vertex.WithGoogleAuth(ctx, region, projectID) o vertex.WithCredentials(ctx, region, projectID, creds).
• Foundry: Actualmente no es compatible con el SDK de Go. Consulta Claude en Microsoft Foundry para ver los SDK compatibles.
• Claude Platform en AWS: import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws". Usa anthropicaws.NewClient(ctx, cfg) con un valor anthropicaws.ClientConfig para construir un cliente; establece WorkspaceID en la configuración o la variable de entorno ANTHROPIC_AWS_WORKSPACE_ID. El alias de importación anthropicaws evita una colisión de nombres con github.com/aws/aws-sdk-go-v2/aws cuando ambos se importan. Disponible en beta.

Usa bedrock.NewMantleClient para proyectos nuevos; bedrock.WithLoadDefaultConfig/WithConfig permanecen disponibles para aplicaciones existentes que usan la API InvokeModel de Bedrock.

Uso avanzado

Acceso a datos de respuesta sin procesar (por ejemplo, encabezados de respuesta)

Puedes acceder a los datos de respuesta HTTP sin procesar usando la opción de solicitud option.WithResponseInto(). Esto es útil cuando necesitas examinar encabezados de respuesta, códigos de estado u otros detalles.

// Crea una variable para almacenar la respuesta 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 {
	// maneja el error
}
fmt.Printf("%+v\n", message)

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

Realizar solicitudes personalizadas/no documentadas

Esta biblioteca está tipada para un acceso conveniente a la API documentada. Si necesitas acceder a endpoints, parámetros o propiedades de respuesta no documentados, la biblioteca aún se puede usar.

Endpoints no documentados

Para realizar solicitudes a endpoints no documentados, puedes usar client.Get, client.Post y otros verbos HTTP. Las RequestOptions del cliente, como los reintentos, se respetarán al realizar estas solicitudes.

var (
	// params puede ser un io.Reader, un []byte, un objeto serializable con encoding/json,
	// o una struct "...Params" definida en esta biblioteca.
	params map[string]any

	// result puede ser un []byte, un *http.Response, un objeto deserializable con encoding/json,
	// o un modelo definido en esta biblioteca.
	result *http.Response
)
err := client.Post(context.Background(), "/unspecified", params, &result)
if err != nil {
	// ...
}

Parámetros de solicitud no documentados

Para realizar solicitudes usando parámetros no documentados, puedes usar los métodos option.WithQuerySet() u 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"))

Propiedades de respuesta no documentadas

Para acceder a propiedades de respuesta no documentadas, puedes acceder al JSON sin procesar de la respuesta como una cadena con result.JSON.RawJSON(), u obtener el JSON sin procesar de un campo particular en el resultado con result.JSON.Foo.Raw().

Cualquier campo que no esté presente en el struct de respuesta se guarda y se puede acceder a través de result.JSON.ExtraFields, que es un map[string]respjson.Field.

Versionado semántico

Este paquete generalmente sigue las convenciones de SemVer, aunque ciertos cambios incompatibles con versiones anteriores pueden publicarse como versiones menores:

1. Cambios en los componentes internos de la biblioteca que son técnicamente públicos pero no están destinados ni documentados para uso externo.
2. Cambios que no se espera que afecten a la gran mayoría de los usuarios en la práctica.

La compatibilidad con versiones anteriores se toma en serio para garantizar que puedas confiar en una experiencia de actualización fluida.

Tus comentarios son bienvenidos; abre un issue con preguntas, errores o sugerencias.

Recursos adicionales

• Repositorio de GitHub
• Documentación del paquete de Go
• Referencia de la API
• Streaming de Messages