Claude Platform Docs
CLI, SDKs y bibliotecasSDKs de cliente

SDK de Go

Instala y configura el SDK de Go de Anthropic con cancelación basada en contexto y opciones funcionales

La biblioteca de Go de Anthropic proporciona un acceso conveniente a la Claude API 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.24+.

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 conocer las opciones de autenticación, incluida Workload Identity Federation, consulta Autenticación. Si tu clave de API es una clave personal o de cuenta de servicio con acceso a múltiples espacios de trabajo, establece el ID del espacio de trabajo en el encabezado de solicitud anthropic-workspace-id; Seleccionar un espacio de trabajo muestra la opción por solicitud para este SDK.

Campos de solicitud

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

Los campos primitivos obligatorios (como int64 o string) llevan la etiqueta `json:"...,required"`. Estos campos siempre se serializan, incluso sus valores cero.

Los tipos primitivos opcionales se envuelven en un param.Opt[T]. Estos campos se pueden establecer con los constructores proporcionados, como anthropic.String(string) o anthropic.Int(int64).

Cualquier param.Opt[T], map, slice, struct o enum de cadena 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 extra 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 los casos en que la API especifica un tipo determinado,
// pero quieres enviar otra cosa, 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 de solicitud

Las uniones se representan como un struct con campos con el prefijo "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},
		},
	},
}

// Mutar 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, un middleware o una solicitud anterior), llama a UnmarshalJSON para rellenar los campos que no son uniones y luego usa param.SetJSON para adjuntar los bytes sin procesar para una reserialización correcta:

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

// Más tarde, reconstruye los params 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 se rellenan mediante UnmarshalJSON.
// params.Tools[0].OfBashTool20250124 es nil (la limitación de las uniones),
// 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 escribir explícitamente 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

// Comprobaciones 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 de la respuesta json que no se haya especificado 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 de respuesta

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 valor de respuesta contiene valores primitivos, los campos primitivos estarán junto a las propiedades, pero con el prefijo Of y llevará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 la variante animal
if animal.Owner.Address.ZipCode == "" {
	panic("missing zip code")
}

// Switch 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 que no es de éxito, el SDK devuelve un error de tipo *anthropic.Error. Este contiene los valores StatusCode, *http.Request y *http.Response de la solicitud, junto con el JSON del cuerpo del error (de forma muy 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 la resolución de 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.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) { ... }
}

Cuando ocurren otros errores, se devuelven sin envolver; por ejemplo, si el transporte HTTP falla, podrías recibir un *url.Error que envuelve un *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
)

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

Tiempos de espera

Las solicitudes de Messages sin streaming agotan su tiempo de espera después de 10 minutos de forma predeterminada; las demás solicitudes no tienen un tiempo de espera predeterminado. Usa context 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 context no se reinicia. Para establecer un tiempo de espera por reintento, usa option.WithRequestTimeout().

// Esto establece el tiempo de espera de 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.ModelClaudeOpus5,
		},
		// 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 descartar conexiones inactivas después de cierto período de tiempo, lo que puede hacer que la solicitud falle o agote su 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 más de aproximadamente 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 el tipo de contenido apropiados.

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

// Un archivo desde una cadena
anthropic.FileUploadParams{
	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 comodidades para trabajar con endpoints de lista paginados.

Puedes usar los métodos .ListAutoPaging() para iterar sobre los elementos de 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.Println(messageBatch.ID)
}
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.Println(batch.ID)
	}
	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 la sintaxis de 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 el middleware de solicitudes (option.WithMiddleware) y el reemplazo del http.Client predeterminado (option.WithHTTPClient), consulta Middleware del SDK.

Integraciones con plataformas

El SDK de Go admite las siguientes plataformas:

  • Agent Platform: import "github.com/anthropics/anthropic-sdk-go/vertex". Usa vertex.WithGoogleAuth(ctx, region, projectID) o vertex.WithCredentials(ctx, region, projectID, creds).
  • Bedrock: import "github.com/anthropics/anthropic-sdk-go/bedrock". Usa bedrock.NewMantleClient para el endpoint de Bedrock de la API de Messages (hace streaming sobre 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 del init() del paquete). Esto aplica tanto si usas la ruta WithConfig/WithLoadDefaultConfig de bedrock-runtime como si usas NewMantleClient.
  • 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.
  • Foundry: Actualmente no es compatible con el SDK de Go. Consulta Claude en Microsoft Foundry para ver los SDK compatibles.

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

Uso avanzado

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

Puedes acceder a los datos de la 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.ModelClaudeOpus5,
	},
	option.WithResponseInto(&response),
)
if err != nil {
	// manejar el error
}
fmt.Printf("%+v\n", message.Content)

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, params 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 un struct "...Params" definido en esta biblioteca.
	params map[string]any

	// result puede ser un []byte, *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 {
	// ...
}

Params 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 en particular del resultado con result.JSON.Foo.Raw().

Cualquier campo que no esté presente en el struct de respuesta se guarda y se puede acceder a él 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 técnicamente son públicos pero que 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 contar con una experiencia de actualización fluida.

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

Recursos adicionales

Was this page helpful?