SDK Go

La bibliothèque Go d'Anthropic offre un accès pratique à l'API REST d'Anthropic depuis des applications écrites en 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.ModelClaudeOpus5,
	})
	if err != nil {
		panic(err.Error())
	}
	for _, block := range message.Content {
		if textBlock, ok := block.AsAny().(anthropic.TextBlock); ok {
			fmt.Println(textBlock.Text)
		}
	}
}

Pour les options d'authentification, y compris Workload Identity Federation, 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 requis (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 chaîne utilise le tag `json:"...,omitzero"`. Sa valeur zéro est considérée comme omise.

La fonction param.IsOmitted(any) peut 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 requis 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 peut envoyer des champs non conformes dans le corps de la requête. Les champs supplémentaires écrasent tous les champs de struct ayant une clé correspondante.

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 comme une 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

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 params (par exemple, pour le stockage ou la transmission)
b, err := json.Marshal(original)
if err != nil {
	panic(err)
}

// Plus tard, reconstruire les params à 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 remplis par UnmarshalJSON.
// params.Tools[0].OfBashTool20250124 est nil (la limitation de l'union),
// 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 d'expliciter le paramètre de type et rend l'intention d'aller-retour explicite.



Objets de réponse

Tous les champs des structs de réponse sont des types 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 classiques

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

// Vérification 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 {
	// Depuis les variantes [Dog], [Cat]
	Owner Person `json:"owner"`
	// Depuis la variante [Dog]
	DogBreed string `json:"dog_breed"`
	// Depuis 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")
}

// Switch sur 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 de non-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 (tout 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 modèle 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) { ... }
}

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 backoff 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 :

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

// Remplacez par requête :
// ...
	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),
	)



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 de la requête, y compris 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.ModelClaudeOpus5,
		},
		// Ceci définit le délai d'expiration par tentative
		option.WithRequestTimeout(20*time.Second),
	)



Requêtes longues

Évitez de définir une grande valeur MaxTokens sans utiliser le streaming, car certains réseaux peuvent interrompre les connexions inactives après un certain temps, ce qui peut faire échouer la requête ou provoquer un délai d'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. Appeler .Messages.NewStreaming() ou définir 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 les requêtes multipart sont typés comme io.Reader. Le contenu de l'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 », donc l'approche recommandée est de 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 type de contenu 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 à partir 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 à l'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 fournit 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 modèle des options fonctionnelles. Les fonctions définies dans le package option renvoient une RequestOption, qui est une closure qui modifie une RequestConfig. Ces options peuvent être fournies au client ou lors de 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 plateformes

Le SDK Go prend en charge les plateformes suivantes :

• Agent Platform : import "github.com/anthropics/anthropic-sdk-go/vertex". Utilisez vertex.WithGoogleAuth(ctx, region, projectID) ou vertex.WithCredentials(ctx, region, projectID, creds).
• 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.
• Claude Platform sur AWS : import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws". Utilisez anthropicaws.NewClient(ctx, cfg) avec une valeur anthropicaws.ClientConfig pour construire un client ; définissez WorkspaceID sur la configuration ou la variable d'environnement ANTHROPIC_AWS_WORKSPACE_ID. L'alias d'importation anthropicaws évite une collision de noms avec github.com/aws/aws-sdk-go-v2/aws lorsque les deux sont importés. Disponible en bêta.
• Foundry : Non pris en charge actuellement dans le SDK Go. Consultez Claude dans Microsoft Foundry pour les SDK pris en charge.

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



Utilisation avancée



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

Vous pouvez accéder aux données brutes de la réponse HTTP en utilisant l'option de requête option.WithResponseInto(). Ceci 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.ModelClaudeOpus5,
	},
	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 params 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 avec 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 avec 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 en utilisant des paramètres non documentés, vous pouvez utiliser soit la méthode option.WithQuerySet(), soit la méthode 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 sur la struct de réponse sont sauvegardés et accessibles via result.JSON.ExtraFields, qui est une map[string]respjson.Field.



Versionnage sémantique

Ce package suit généralement les conventions SemVer, bien que certains changements incompatibles avec les versions antérieures puissent être publiés en tant que versions mineures :

1. Les changements apportés aux éléments internes de la bibliothèque qui sont techniquement publics mais qui ne sont pas destinés ou documentés pour un usage externe.
2. Les changements qui ne devraient pas avoir d'impact sur la grande majorité des utilisateurs en pratique.

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

Vos retours sont les bienvenus ; ouvrez une issue avec vos questions, bugs ou suggestions.



Ressources supplémentaires

• Dépôt GitHub
• Documentation du package Go
• Référence API
• Streaming Messages