SDK Go

La bibliothèque Go d'Anthropic offre un accès pratique à l'API REST d'Anthropic depuis des applications écrites en Go.

Pour la documentation des fonctionnalités de l'API avec des exemples de code, consultez la référence de l'API. Cette page couvre les fonctionnalités et la configuration du SDK spécifiques à Go.

Installation

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

Installez avec go get :

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

Prérequis

Cette bibliothèque nécessite Go 1.23+.

Utilisation

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

Pour les options d'authentification, y compris la « Workload Identity Federation » (fédération d'identité de charge de travail), consultez Authentification.

Champs de requête

La bibliothèque anthropic utilise la sémantique omitzero de la version encoding/json de Go 1.24+ pour les champs de requête.

Les champs primitifs obligatoires (int64, string, etc.) comportent le tag `json:"...,required"`. Ces champs sont toujours sérialisés, même leurs valeurs zéro.

Les types primitifs optionnels sont encapsulés dans un param.Opt[T]. Ces champs peuvent être définis avec les constructeurs fournis, anthropic.String(string), anthropic.Int(int64), etc.

Tout param.Opt[T], map, slice, struct ou enum de type string utilise le tag `json:"...,omitzero"`. Sa valeur zéro est considérée comme omise.

La fonction param.IsOmitted(any) permet de confirmer la présence de tout champ 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
		// ... les champs non obligatoires omis ne seront pas sérialisés
	},

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

Pour envoyer null au lieu d'un param.Opt[T], utilisez param.Null[T](). Pour envoyer null au lieu d'une struct T, utilisez 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

Les structs de requête contiennent une méthode .SetExtraFields(map[string]any) qui permet d'envoyer des champs non conformes dans le corps de la requête. Les champs supplémentaires écrasent tout champ de struct ayant une clé correspondante.

Pour des raisons de sécurité, n'utilisez SetExtraFields qu'avec des données de confiance.

Pour envoyer une valeur personnalisée au lieu d'une struct, utilisez la fonction générique param.Override (par exemple, param.Override[anthropic.FooParams](12)).

// Dans les cas où l'API spécifie un type donné,
// mais que vous souhaitez envoyer autre chose, utilisez [SetExtraFields] :
p.SetExtraFields(map[string]any{
	"x": 0.01, // send "x" as a float instead of int
})

// Envoyer un nombre au lieu d'un objet
custom := param.Override[anthropic.FooParams](12)

Unions de requête

Les unions sont représentées sous forme de struct avec des champs préfixés par « Of » pour chacune de ses variantes ; un seul champ peut être non nul. Le champ non nul sera sérialisé.

Les sous-propriétés de l'union sont accessibles via des méthodes sur la struct d'union. Ces méthodes renvoient un pointeur mutable vers les données sous-jacentes, si elles sont présentes.

// Un seul champ peut être non nul, utilisez param.IsOmitted() pour vérifier si un champ est défini
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},
		},
	},
}

// Modification d'un champ
if address := animal.GetOwner().GetAddress(); address != nil {
	address.ZipCode = 94304
}

Désérialisation des params

param.SetJSON nécessite le SDK v1.20.0 ou une version ultérieure.

Les types param (types se terminant par Param, tels que MessageNewParams ou ToolUnionParam) sont conçus uniquement pour les requêtes sortantes. Ils se sérialisent correctement en JSON mais ne prennent pas entièrement en charge la désérialisation aller-retour. Si vous désérialisez du JSON brut dans une struct param, les champs d'union typés comme OfBashTool20250124 seront nil même lorsque le JSON sous-jacent est valide.

Si vous devez reconstruire des params à partir de JSON brut (par exemple, depuis une base de données, un middleware ou une requête précédente), appelez UnmarshalJSON pour remplir les champs non-union, puis utilisez param.SetJSON pour attacher les octets bruts afin d'obtenir une re-sérialisation correcte :

// Sérialiser les paramètres (par exemple, pour le stockage ou le transfert)
b, err := json.Marshal(original)
if err != nil {
	panic(err)
}

// Plus tard, reconstruire les paramètres à partir du JSON stocké
var params anthropic.MessageNewParams
if err := params.UnmarshalJSON(b); err != nil {
	panic(err)
}
param.SetJSON(b, &params)

// params.Model et les autres champs scalaires sont renseignés par UnmarshalJSON.
// params.Tools[0].OfBashTool20250124 est nil (la limitation des unions),
// mais le JSON brut est préservé. Lorsque params est à nouveau sérialisé
// pour l'appel API, les outils se sérialisent correctement.
b2, _ := json.Marshal(params)
fmt.Println(string(b) == string(b2)) // true

Pour ce cas d'usage, param.SetJSON (disponible depuis la v1.20.0) est préférable à la fonction plus générale param.Override[T](any) car elle ne nécessite pas de spécifier le paramètre de type et rend explicite l'intention d'aller-retour.

Objets de réponse

Tous les champs des structs de réponse sont des types de valeur ordinaires (pas des pointeurs ni des wrappers). Les structs de réponse incluent également un champ spécial JSON contenant des métadonnées sur chaque propriété.

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:"-"`
}

Pour gérer les données optionnelles, utilisez la méthode .Valid() sur le champ JSON. .Valid() renvoie true lorsque le champ est présent, non null, et a été désérialisé avec succès.

Si .Valid() est false, le champ correspondant aura sa valeur zéro.

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

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

// Accès aux champs ordinaires

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

// Vérifications des champs optionnels

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

// Valeurs JSON brutes

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

Ces structs .JSON incluent également une map ExtraFields contenant toutes les propriétés de la réponse JSON qui n'étaient pas spécifiées dans la struct. Cela peut être utile pour les fonctionnalités de l'API qui ne sont pas encore présentes dans le SDK.

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

Unions de réponse

Dans les réponses, les unions sont représentées par une struct aplatie contenant tous les champs possibles de chacune des variantes d'objet. Pour la convertir en une variante, utilisez la méthode .AsFooVariant() ou la méthode .AsAny() si elle est présente.

Si une union de valeur de réponse contient des valeurs primitives, les champs primitifs seront placés à côté des propriétés mais préfixés par Of et comporteront le tag json:"...,inline".

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

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

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

// Sélection selon la variante
switch variant := animal.AsAny().(type) {
case Dog:
case Cat:
default:
	panic("unexpected type")
}

Gestion des erreurs

Lorsque l'API renvoie un code de statut autre qu'un succès, le SDK renvoie une erreur de type *anthropic.Error. Celle-ci contient les valeurs StatusCode, *http.Request et *http.Response de la requête, ainsi que le JSON du corps de l'erreur (comme les autres objets de réponse du SDK). L'erreur inclut également le RequestID provenant des en-têtes de réponse, ce qui est utile pour le dépannage avec le support d'Anthropic.

Pour gérer les erreurs, utilisez le pattern 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) { ... }
}

Lorsque d'autres erreurs se produisent, elles sont renvoyées sans encapsulation ; par exemple, si le transport HTTP échoue, vous pourriez recevoir *url.Error encapsulant *net.OpError.

Nouvelles tentatives

Certaines erreurs feront automatiquement l'objet de 2 nouvelles tentatives par défaut, avec un court délai exponentiel. Le SDK réessaie par défaut toutes les erreurs de connexion, 408 Request Timeout, 409 Conflict, 429 Rate Limit, et les erreurs internes >=500.

Vous pouvez utiliser l'option WithMaxRetries pour configurer ou désactiver ce comportement :

// Configurer la valeur par défaut pour toutes les requêtes :
client := anthropic.NewClient(
	option.WithMaxRetries(0), // default is 2
)

// Remplacer pour une requête spécifique :
// ...
	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),
	)

Délais d'expiration

Les requêtes Messages sans streaming expirent après 10 minutes par défaut ; les autres requêtes n'ont pas de délai d'expiration par défaut. Utilisez le contexte pour configurer un délai d'expiration pour le cycle de vie d'une requête.

Notez que si une requête fait l'objet d'une nouvelle tentative, le délai d'expiration du contexte ne recommence pas. Pour définir un délai d'expiration par tentative, utilisez option.WithRequestTimeout().

// Ceci définit le délai d'expiration pour la requête, incluant toutes les nouvelles tentatives.
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,
		},
		// Ceci définit le délai d'expiration par tentative
		option.WithRequestTimeout(20*time.Second),
	)

Requêtes longues

Envisagez d'utiliser l'API Messages en streaming pour les requêtes de longue durée.

Évitez de définir une valeur MaxTokens élevée sans utiliser le streaming, car certains réseaux peuvent interrompre les connexions inactives après un certain temps, ce qui peut entraîner l'échec de la requête ou son expiration sans recevoir de réponse d'Anthropic.

Ce SDK renverra également une erreur si une requête sans streaming est censée durer plus d'environ 10 minutes. L'appel de .Messages.NewStreaming() ou la définition d'un délai d'expiration personnalisé désactive cette erreur.

Téléversement de fichiers

Les paramètres de requête qui correspondent à des téléversements de fichiers dans des requêtes multipart sont typés comme io.Reader. Le contenu du io.Reader sera par défaut envoyé comme une partie de formulaire multipart avec le nom de fichier « anonymous_file » et le content-type « application/octet-stream ». L'approche recommandée consiste donc à spécifier un content-type personnalisé avec l'assistant anthropic.File(reader io.Reader, filename string, contentType string), qui encapsule tout io.Reader avec le nom de fichier et le content-type appropriés.

// Un fichier provenant du système de fichiers
file, err := os.Open("/path/to/file.json")
anthropic.BetaFileUploadParams{
	File: anthropic.File(file, "custom-name.json", "application/json"),
}

// Un fichier provenant d'une chaîne de caractères
anthropic.BetaFileUploadParams{
	File: anthropic.File(strings.NewReader("my file contents"), "custom-name.json", "application/json"),
}

Le nom de fichier et le content-type peuvent également être personnalisés en implémentant Name() string ou ContentType() string sur le type d'exécution de io.Reader. Notez que os.File implémente Name() string, donc un fichier renvoyé par os.Open sera envoyé avec le nom de fichier sur le disque.

Pagination

Cette bibliothèque offre quelques commodités pour travailler avec les points de terminaison de liste paginés.

Vous pouvez utiliser les méthodes .ListAutoPaging() pour itérer sur les éléments de toutes les pages :

iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
	Limit: anthropic.Int(20),
})
// Récupère automatiquement des pages supplémentaires selon les besoins.
for iter.Next() {
	messageBatch := iter.Current()
	fmt.Printf("%+v\n", messageBatch)
}
if err := iter.Err(); err != nil {
	panic(err.Error())
}

Ou vous pouvez utiliser les méthodes simples .List() pour récupérer une seule page et recevoir un objet de réponse standard avec des méthodes d'assistance supplémentaires comme .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

Cette bibliothèque utilise le pattern des options fonctionnelles. Les fonctions définies dans le package option renvoient une RequestOption, qui est une closure qui modifie un RequestConfig. Ces options peuvent être fournies au client ou à des requêtes individuelles. Par exemple :

client := anthropic.NewClient(
	// Ajoute un en-tête à chaque requête effectuée par le client
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.Messages.New(context.TODO(), // ...,
	// Remplacer l'en-tête
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Ajouter un champ non documenté au corps de la requête, en utilisant la syntaxe sjson
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

L'option de requête option.WithDebugLog(nil) peut être utile lors du débogage.

Consultez la liste complète des options de requête.

Personnalisation du client HTTP

Pour le middleware de requête (option.WithMiddleware) et le remplacement du http.Client par défaut (option.WithHTTPClient), consultez Middleware du SDK.

Intégrations de plateforme

Pour des guides de configuration de plateforme détaillés avec des exemples de code, consultez :

Le SDK Go prend en charge les plateformes suivantes :

Bedrock : import "github.com/anthropics/anthropic-sdk-go/bedrock". Utilisez bedrock.NewMantleClient pour le point de terminaison Bedrock de l'API Messages (streaming via SSE), ou bedrock.WithLoadDefaultConfig(ctx) / bedrock.WithConfig(cfg) (chemin bedrock-runtime). L'importation du package bedrock enregistre globalement un décodeur pour application/vnd.amazon.eventstream auprès de la couche de streaming du SDK (via le init() du package). Cela s'applique que vous utilisiez le chemin bedrock-runtime WithConfig/WithLoadDefaultConfig ou NewMantleClient.
Vertex AI : import "github.com/anthropics/anthropic-sdk-go/vertex". Utilisez vertex.WithGoogleAuth(ctx, region, projectID) ou vertex.WithCredentials(ctx, region, projectID, creds).

Utilisez bedrock.NewMantleClient pour les nouveaux projets ; bedrock.WithLoadDefaultConfig/WithConfig restent disponibles pour les applications existantes utilisant l'API InvokeModel de Bedrock.

Utilisation avancée

Accès aux données de réponse brutes (par exemple, les en-têtes de réponse)

Vous pouvez accéder aux données de réponse HTTP brutes en utilisant l'option de requête option.WithResponseInto(). Cela est utile lorsque vous devez examiner les en-têtes de réponse, les codes de statut ou d'autres détails.

// Créer une variable pour stocker la réponse 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 {
	// gérer l'erreur
}
fmt.Printf("%+v\n", message)

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

Effectuer des requêtes personnalisées/non documentées

Cette bibliothèque est typée pour un accès pratique à l'API documentée. Si vous devez accéder à des points de terminaison, des paramètres ou des propriétés de réponse non documentés, la bibliothèque peut toujours être utilisée.

Points de terminaison non documentés

Pour effectuer des requêtes vers des points de terminaison non documentés, vous pouvez utiliser client.Get, client.Post et d'autres verbes HTTP. Les RequestOptions sur le client, telles que les nouvelles tentatives, seront respectées lors de ces requêtes.

var (
	// params peut être un io.Reader, un []byte, un objet sérialisable via encoding/json,
	// ou une struct « ...Params » définie dans cette bibliothèque.
	params map[string]any

	// result peut être un []byte, un *http.Response, un objet désérialisable via encoding/json,
	// ou un modèle défini dans cette bibliothèque.
	result *http.Response
)
err := client.Post(context.Background(), "/unspecified", params, &result)
if err != nil {
	// ...
}

Paramètres de requête non documentés

Pour effectuer des requêtes utilisant des paramètres non documentés, vous pouvez utiliser les méthodes 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"))

Propriétés de réponse non documentées

Pour accéder aux propriétés de réponse non documentées, vous pouvez soit accéder au JSON brut de la réponse sous forme de chaîne avec result.JSON.RawJSON(), soit obtenir le JSON brut d'un champ particulier du résultat avec result.JSON.Foo.Raw().

Tous les champs qui ne sont pas présents dans la struct de réponse sont enregistrés et accessibles via result.JSON.ExtraFields, qui est une map[string]respjson.Field.

Versionnement sémantique

Ce package suit généralement les conventions SemVer, bien que certaines modifications rétro-incompatibles puissent être publiées en tant que versions mineures :

Modifications des éléments internes de la bibliothèque qui sont techniquement publics mais non destinés ni documentés pour un usage externe.
Modifications qui ne devraient pas affecter la grande majorité des utilisateurs en pratique.

La rétrocompatibilité est prise au sérieux afin de vous garantir une expérience de mise à niveau fluide.

Vos commentaires sont les bienvenus ; ouvrez une issue pour vos questions, bugs ou suggestions.

Installation

Prérequis

Utilisation

Conversations

Champs de requête

Unions de requête

Désérialisation des params

Objets de réponse

Unions de réponse

Gestion des erreurs

Nouvelles tentatives

Délais d'expiration

Requêtes longues

Téléversement de fichiers

Pagination

RequestOptions

Personnalisation du client HTTP

Intégrations de plateforme

Utilisation avancée

Accès aux données de réponse brutes (par exemple, les en-têtes de réponse)

Effectuer des requêtes personnalisées/non documentées

Points de terminaison non documentés

Paramètres de requête non documentés

Propriétés de réponse non documentées

Versionnement sémantique

Ressources supplémentaires

Invites système

Streaming

Appel d'outils