Go SDK

Die Anthropic Go-Bibliothek bietet bequemen Zugriff auf die Anthropic REST API aus Anwendungen, die in Go geschrieben sind.



Installation

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

Installiere mit go get:

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



Anforderungen

Diese Bibliothek erfordert Go 1.23+.



Verwendung

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

Für Authentifizierungsoptionen einschließlich Workload Identity Federation siehe Authentifizierung.



Request-Felder

Die anthropic-Bibliothek verwendet die omitzero-Semantik aus dem Go 1.24+ encoding/json-Release für Request-Felder.

Erforderliche primitive Felder (int64, string, usw.) tragen das Tag `json:"...,required"`. Diese Felder werden immer serialisiert, auch ihre Nullwerte.

Optionale primitive Typen sind in ein param.Opt[T] verpackt. Diese Felder können mit den bereitgestellten Konstruktoren gesetzt werden, anthropic.String(string), anthropic.Int(int64), usw.

Jedes param.Opt[T], Map, Slice, Struct oder String-Enum verwendet das Tag `json:"...,omitzero"`. Sein Nullwert gilt als ausgelassen.

Die Funktion param.IsOmitted(any) kann das Vorhandensein eines beliebigen omitzero-Feldes bestätigen.

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
		// ... ausgelassene, nicht erforderliche Felder werden nicht serialisiert
	},

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

Um null anstelle eines param.Opt[T] zu senden, verwende param.Null[T](). Um null anstelle eines Structs T zu senden, verwende 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

Request-Structs enthalten eine Methode .SetExtraFields(map[string]any), die nicht-konforme Felder im Request-Body senden kann. Extra-Felder überschreiben alle Struct-Felder mit einem passenden Schlüssel.

Um einen benutzerdefinierten Wert anstelle eines Structs zu senden, verwende die generische Funktion param.Override (zum Beispiel param.Override[anthropic.FooParams](12)).

// In Fällen, in denen die API einen bestimmten Typ vorgibt,
// du aber etwas anderes senden möchtest, verwende [SetExtraFields]:
p.SetExtraFields(map[string]any{
	"x": 0.01, // send "x" as a float instead of int
})

// Sende eine Zahl anstelle eines Objekts
custom := param.Override[anthropic.FooParams](12)



Request-Unions

Unions werden als Struct mit Feldern dargestellt, die für jede ihrer Varianten mit „Of" beginnen, wobei nur ein Feld ungleich null sein kann. Das Feld ungleich null wird serialisiert.

Auf Untereigenschaften der Union kann über Methoden auf dem Union-Struct zugegriffen werden. Diese Methoden geben einen veränderbaren Zeiger auf die zugrunde liegenden Daten zurück, falls vorhanden.

// Nur ein Feld darf ungleich null sein, verwende param.IsOmitted(), um zu prüfen, ob ein Feld gesetzt ist
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},
		},
	},
}

// Ein Feld verändern
if address := animal.GetOwner().GetAddress(); address != nil {
	address.ZipCode = 94304
}



Deserialisierung von Params

Param-Typen (Typen, die auf Param enden, wie MessageNewParams oder ToolUnionParam) sind nur für ausgehende Requests konzipiert. Sie werden korrekt nach JSON serialisiert, unterstützen aber keine vollständige Round-Trip-Deserialisierung. Wenn du rohes JSON in ein Param-Struct deserialisierst, sind typisierte Union-Felder wie OfBashTool20250124 nil, selbst wenn das zugrunde liegende JSON gültig ist.

Wenn du Params aus rohem JSON rekonstruieren musst (zum Beispiel aus einer Datenbank, Middleware oder einem vorherigen Request), rufe UnmarshalJSON auf, um Nicht-Union-Felder zu befüllen, und verwende dann param.SetJSON, um die rohen Bytes für eine korrekte Re-Serialisierung anzuhängen:

// Serialisiere params (z. B. zur Speicherung oder Weiterleitung)
b, err := json.Marshal(original)
if err != nil {
	panic(err)
}

// Rekonstruiere params später aus dem gespeicherten JSON
var params anthropic.MessageNewParams
if err := params.UnmarshalJSON(b); err != nil {
	panic(err)
}
param.SetJSON(b, &params)

// params.Model und andere skalare Felder werden durch UnmarshalJSON befüllt.
// params.Tools[0].OfBashTool20250124 ist nil (die Union-Einschränkung),
// aber das rohe JSON bleibt erhalten. Wenn params für den
// API-Aufruf erneut gemarshalt wird, werden die Tools korrekt serialisiert.
b2, _ := json.Marshal(params)
fmt.Println(string(b) == string(b2)) // true

Für diesen Anwendungsfall ist param.SetJSON (verfügbar seit v1.20.0) gegenüber dem allgemeineren param.Override[T](any) zu bevorzugen, da es nicht erfordert, den Typparameter auszuschreiben, und die Round-Trip-Absicht explizit macht.



Response-Objekte

Alle Felder in Response-Structs sind gewöhnliche Werttypen (keine Zeiger oder Wrapper). Response-Structs enthalten außerdem ein spezielles JSON-Feld mit Metadaten über jede Eigenschaft.

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

Um optionale Daten zu behandeln, verwende die Methode .Valid() auf dem JSON-Feld. .Valid() gibt true zurück, wenn das Feld vorhanden, nicht-null und erfolgreich deserialisiert wurde.

Wenn .Valid() false ist, hat das entsprechende Feld seinen Nullwert.

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

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

// Zugriff auf reguläre Felder

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

// Prüfung optionaler Felder

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

// Rohe JSON-Werte

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

Diese .JSON-Structs enthalten auch eine ExtraFields-Map, die alle Eigenschaften in der JSON-Response enthält, die nicht im Struct angegeben wurden. Dies kann für API-Funktionen nützlich sein, die noch nicht im SDK vorhanden sind.

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



Response-Unions

In Responses werden Unions durch ein abgeflachtes Struct dargestellt, das alle möglichen Felder aus jeder der Objektvarianten enthält. Um es in eine Variante zu konvertieren, verwende die Methode .AsFooVariant() oder die Methode .AsAny(), falls vorhanden.

Wenn eine Response-Wert-Union primitive Werte enthält, stehen die primitiven Felder neben den Eigenschaften, sind aber mit Of vorangestellt und tragen das Tag json:"...,inline".

type AnimalUnion struct {
	// Aus den Varianten [Dog], [Cat]
	Owner Person `json:"owner"`
	// Aus der Variante [Dog]
	DogBreed string `json:"dog_breed"`
	// Aus der Variante [Cat]
	CatBreed string `json:"cat_breed"`
	// ...

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

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

// Verzweige anhand der Variante
switch variant := animal.AsAny().(type) {
case Dog:
case Cat:
default:
	panic("unexpected type")
}



Fehlerbehandlung

Wenn die API einen nicht erfolgreichen Statuscode zurückgibt, gibt das SDK einen Fehler vom Typ *anthropic.Error zurück. Dieser enthält die Werte StatusCode, *http.Request und *http.Response des Requests sowie das JSON des Fehler-Bodys (ähnlich wie andere Response-Objekte im SDK). Der Fehler enthält auch die RequestID aus den Response-Headern, was für die Fehlerbehebung mit dem Anthropic-Support nützlich ist.

Um Fehler zu behandeln, verwende das errors.As-Muster:

_, 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) { ... }
}

Wenn andere Fehler auftreten, werden sie unverpackt zurückgegeben; zum Beispiel könntest du bei einem HTTP-Transportfehler ein *url.Error erhalten, das ein *net.OpError umschließt.



Wiederholungsversuche

Bestimmte Fehler werden standardmäßig 2-mal automatisch wiederholt, mit einem kurzen exponentiellen Backoff. Das SDK wiederholt standardmäßig alle Verbindungsfehler, 408 Request Timeout, 409 Conflict, 429 Rate Limit und >=500 Internal-Fehler.

Du kannst die Option WithMaxRetries verwenden, um dies zu konfigurieren oder zu deaktivieren:

// Konfiguriere den Standard für alle Anfragen:
client := anthropic.NewClient(
	option.WithMaxRetries(0), // default is 2
)

// Überschreibe pro Anfrage:
// ...
	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),
	)



Timeouts

Nicht-Streaming-Messages-Requests laufen standardmäßig nach 10 Minuten ab; andere Requests haben kein Standard-Timeout. Verwende Context, um ein Timeout für einen Request-Lebenszyklus zu konfigurieren.

Beachte, dass bei einem wiederholten Request das Context-Timeout nicht von vorne beginnt. Um ein Timeout pro Wiederholungsversuch festzulegen, verwende option.WithRequestTimeout().

// Dies setzt das Timeout für die Anfrage, einschließlich aller Wiederholungsversuche.
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,
		},
		// Dies setzt das Timeout pro Wiederholungsversuch
		option.WithRequestTimeout(20*time.Second),
	)



Lange Requests

Vermeide es, einen großen MaxTokens-Wert ohne Streaming zu setzen, da einige Netzwerke inaktive Verbindungen nach einer bestimmten Zeit trennen können, was dazu führen kann, dass der Request fehlschlägt oder ein Timeout auftritt, ohne eine Antwort von Anthropic zu erhalten.

Dieses SDK gibt auch einen Fehler zurück, wenn erwartet wird, dass ein Nicht-Streaming-Request länger als etwa 10 Minuten dauert. Der Aufruf von .Messages.NewStreaming() oder das Setzen eines benutzerdefinierten Timeouts deaktiviert diesen Fehler.



Datei-Uploads

Request-Parameter, die Datei-Uploads in Multipart-Requests entsprechen, sind als io.Reader typisiert. Der Inhalt des io.Reader wird standardmäßig als Multipart-Formular-Teil mit dem Dateinamen „anonymous_file" und dem Content-Type „application/octet-stream" gesendet. Der empfohlene Ansatz ist daher, einen benutzerdefinierten Content-Type mit dem Helper anthropic.File(reader io.Reader, filename string, contentType string) anzugeben, der jeden io.Reader mit dem entsprechenden Dateinamen und Content-Type umschließt.

// Eine Datei aus dem Dateisystem
file, err := os.Open("/path/to/file.json")
anthropic.BetaFileUploadParams{
	File: anthropic.File(file, "custom-name.json", "application/json"),
}

// Eine Datei aus einem String
anthropic.BetaFileUploadParams{
	File: anthropic.File(strings.NewReader("my file contents"), "custom-name.json", "application/json"),
}

Der Dateiname und der Content-Type können auch angepasst werden, indem Name() string oder ContentType() string auf dem Laufzeittyp des io.Reader implementiert wird. Beachte, dass os.File Name() string implementiert, sodass eine von os.Open zurückgegebene Datei mit dem Dateinamen auf der Festplatte gesendet wird.



Paginierung

Diese Bibliothek bietet einige Annehmlichkeiten für die Arbeit mit paginierten Listen-Endpunkten.

Du kannst .ListAutoPaging()-Methoden verwenden, um über Elemente auf allen Seiten zu iterieren:

iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
	Limit: anthropic.Int(20),
})
// Ruft bei Bedarf automatisch weitere Seiten ab.
for iter.Next() {
	messageBatch := iter.Current()
	fmt.Printf("%+v\n", messageBatch)
}
if err := iter.Err(); err != nil {
	panic(err.Error())
}

Oder du kannst einfache .List()-Methoden verwenden, um eine einzelne Seite abzurufen und ein Standard-Response-Objekt mit zusätzlichen Helper-Methoden wie .GetNextPage() zu erhalten:

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

Diese Bibliothek verwendet das Muster der funktionalen Optionen. Funktionen, die im option-Paket definiert sind, geben eine RequestOption zurück, die eine Closure ist, die eine RequestConfig verändert. Diese Optionen können dem Client oder bei einzelnen Requests übergeben werden. Zum Beispiel:

client := anthropic.NewClient(
	// Fügt jeder Anfrage des Clients einen Header hinzu
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.Messages.New(context.TODO(), // ...,
	// Überschreibe den Header
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Füge dem Request-Body ein undokumentiertes Feld hinzu, mit sjson-Syntax
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

Die Request-Option option.WithDebugLog(nil) kann beim Debuggen hilfreich sein.

Siehe die vollständige Liste der Request-Optionen.



HTTP-Client-Anpassung

Für Request-Middleware (option.WithMiddleware) und das Ersetzen des Standard-http.Client (option.WithHTTPClient) siehe SDK-Middleware.



Plattform-Integrationen

Das Go SDK unterstützt die folgenden Plattformen:

• Agent Platform: import "github.com/anthropics/anthropic-sdk-go/vertex". Verwende vertex.WithGoogleAuth(ctx, region, projectID) oder vertex.WithCredentials(ctx, region, projectID, creds).
• Bedrock: import "github.com/anthropics/anthropic-sdk-go/bedrock". Verwende bedrock.NewMantleClient für den Messages-API-Bedrock-Endpunkt (streamt über SSE) oder bedrock.WithLoadDefaultConfig(ctx) / bedrock.WithConfig(cfg) (bedrock-runtime-Pfad). Das Importieren des bedrock-Pakets registriert global einen Decoder für application/vnd.amazon.eventstream bei der Streaming-Schicht des SDK (über das Paket-init()). Dies gilt unabhängig davon, ob du den bedrock-runtime-Pfad WithConfig/WithLoadDefaultConfig oder NewMantleClient verwendest.
• Claude Platform auf AWS: import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws". Verwende anthropicaws.NewClient(ctx, cfg) mit einem anthropicaws.ClientConfig-Wert, um einen Client zu erstellen; setze WorkspaceID in der Konfiguration oder die Umgebungsvariable ANTHROPIC_AWS_WORKSPACE_ID. Der Import-Alias anthropicaws vermeidet eine Namenskollision mit github.com/aws/aws-sdk-go-v2/aws, wenn beide importiert werden. Verfügbar in der Beta.
• Foundry: Derzeit nicht im Go SDK unterstützt. Siehe Claude in Microsoft Foundry für unterstützte SDKs.

Verwende bedrock.NewMantleClient für neue Projekte; bedrock.WithLoadDefaultConfig/WithConfig bleiben für bestehende Anwendungen erhalten, die die Bedrock InvokeModel API verwenden.



Erweiterte Verwendung



Zugriff auf rohe Response-Daten (zum Beispiel Response-Header)

Du kannst auf die rohen HTTP-Response-Daten zugreifen, indem du die Request-Option option.WithResponseInto() verwendest. Dies ist nützlich, wenn du Response-Header, Statuscodes oder andere Details untersuchen musst.

// Erstelle eine Variable zum Speichern der HTTP-Antwort
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 {
	// Fehler behandeln
}
fmt.Printf("%+v\n", message)

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



Benutzerdefinierte/undokumentierte Requests erstellen

Diese Bibliothek ist für den bequemen Zugriff auf die dokumentierte API typisiert. Wenn du auf undokumentierte Endpunkte, Params oder Response-Eigenschaften zugreifen musst, kann die Bibliothek dennoch verwendet werden.



Undokumentierte Endpunkte

Um Requests an undokumentierte Endpunkte zu stellen, kannst du client.Get, client.Post und andere HTTP-Verben verwenden. RequestOptions auf dem Client, wie z. B. Wiederholungsversuche, werden bei diesen Requests berücksichtigt.

var (
	// params kann ein io.Reader, ein []byte, ein mit encoding/json serialisierbares Objekt
	// oder ein in dieser Bibliothek definiertes "...Params"-Struct sein.
	params map[string]any

	// result kann ein []byte, *http.Response, ein mit encoding/json deserialisierbares Objekt
	// oder ein in dieser Bibliothek definiertes Modell sein.
	result *http.Response
)
err := client.Post(context.Background(), "/unspecified", params, &result)
if err != nil {
	// ...
}



Undokumentierte Request-Params

Um Requests mit undokumentierten Parametern zu stellen, kannst du entweder die Methode option.WithQuerySet() oder die Methode option.WithJSONSet() verwenden.

params := FooNewParams{
	ID: "id_xxxx",
	Data: FooNewParamsData{
		FirstName: anthropic.String("John"),
	},
}
client.Foo.New(context.Background(), params, option.WithJSONSet("data.last_name", "Doe"))



Undokumentierte Response-Eigenschaften

Um auf undokumentierte Response-Eigenschaften zuzugreifen, kannst du entweder auf das rohe JSON der Response als String mit result.JSON.RawJSON() zugreifen oder das rohe JSON eines bestimmten Feldes im Ergebnis mit result.JSON.Foo.Raw() abrufen.

Alle Felder, die nicht im Response-Struct vorhanden sind, werden gespeichert und können über result.JSON.ExtraFields abgerufen werden, das eine map[string]respjson.Field ist.



Semantische Versionierung

Dieses Paket folgt im Allgemeinen den SemVer-Konventionen, obwohl bestimmte rückwärtsinkompatible Änderungen als Minor-Versionen veröffentlicht werden können:

1. Änderungen an Bibliotheks-Interna, die technisch öffentlich, aber nicht für die externe Verwendung vorgesehen oder dokumentiert sind.
2. Änderungen, von denen nicht erwartet wird, dass sie die überwiegende Mehrheit der Nutzer in der Praxis beeinträchtigen.

Rückwärtskompatibilität wird ernst genommen, um sicherzustellen, dass du dich auf ein reibungsloses Upgrade-Erlebnis verlassen kannst.

Dein Feedback ist willkommen; eröffne ein Issue mit Fragen, Bugs oder Vorschlägen.



Zusätzliche Ressourcen

• GitHub-Repository
• Go-Paketdokumentation
• API-Referenz
• Streaming Messages