Claude Platform Docs

SDK Go

Installez et configurez le SDK Go d'Anthropic avec l'annulation basée sur le contexte et les options fonctionnelles

La bibliothèque Go d'Anthropic offre un accès pratique à l'API Claude 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.24+.

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. Si votre clé API est une clé personnelle ou de compte de service ayant accès à plusieurs espaces de travail, définissez l'identifiant de l'espace de travail dans l'en-tête de requête anthropic-workspace-id ; Sélectionner un espace de travail présente l'option par requête pour ce SDK.

Champs de requête

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

Les champs primitifs obligatoires (tels que int64 ou string) portent le tag `json:"...,required"`. Ces champs sont toujours sérialisés, même avec 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, tels que anthropic.String(string) ou anthropic.Int(int64).

Tout param.Opt[T], map, slice, struct ou énumération de chaînes 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 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 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 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 dont les champs sont préfixés par « Of » pour chacune de leurs 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 hors union, puis utilisez param.SetJSON pour attacher les octets bruts afin d'assurer une re-sérialisation correcte :

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

// Plus tard, reconstruire 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 renseignés par UnmarshalJSON.
// params.Tools[0].OfBashTool20250124 vaut nil (la limitation des unions),
// mais le JSON brut est conservé. Lorsque params est à nouveau sérialisé
// pour l'appel à l'API, les outils sont sérialisés 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 explicite l'intention d'aller-retour.

Objets de réponse

Tous les champs des structs de réponse sont des types valeur ordinaires (ni pointeurs ni 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 figureront aux côtés des propriétés mais seront préfixés par Of et porteront 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 la variante est 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 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 (tout comme les autres objets de réponse du SDK). L'erreur inclut également le RequestID issu 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 surviennent, elles sont renvoyées sans encapsulation ; par exemple, si le transport HTTP échoue, vous pourriez recevoir un *url.Error encapsulant un *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 (limite de débit), 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 donnée :

	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 redémarre 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, toutes les tentatives comprises.
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 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. 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 correspondant à des téléversements de fichiers dans des requêtes multipart sont typés 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 » ; 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 type de contenu appropriés.

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

// Un fichier depuis une chaîne de caractères
anthropic.FileUploadParams{
	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 l'io.Reader. Notez que os.File implémente Name() string, de sorte qu'un fichier renvoyé par os.Open sera envoyé avec son 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 d'autres pages selon les besoins.
for iter.Next() {
	messageBatch := iter.Current()
	fmt.Println(messageBatch.ID)
}
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.Println(batch.ID)
	}
	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 modifiant une 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(), // ...,
	// Remplace l'en-tête
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Ajoute 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 la fonction 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 dans 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(). 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.ModelClaudeOpus5,
	},
	option.WithResponseInto(&response),
)
if err != nil {
	// gérer l'erreur
}
fmt.Printf("%+v\n", message.Content)

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, params ou propriétés de réponse non documentés, la bibliothèque peut tout de même ê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 du 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 {
	// ...
}

Params de requête non documentés

Pour effectuer des requêtes avec 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 absents de la struct de réponse sont conservés et accessibles via result.JSON.ExtraFields, qui est une map[string]respjson.Field.

Gestion sémantique des versions

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

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

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

Vos retours sont les bienvenus ; ouvrez une issue pour toute question, bug ou suggestion.

Ressources supplémentaires

Was this page helpful?