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.ModelClaudeOpus4_8,
	})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", message.Content)
}

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] eingebettet. Diese Felder können mit den bereitgestellten Konstruktoren gesetzt werden, anthropic.String(string), anthropic.Int(int64) usw.

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

Die Funktion param.IsOmitted(any) kann das Vorhandensein eines beliebigen omitzero-Felds 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 .SetExtraFields(map[string]any)-Methode, die nicht-konforme Felder im Request-Body senden kann. Zusätzliche Felder überschreiben alle Struct-Felder mit einem übereinstimmenden 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 statt 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" präfigiert sind; nur ein Feld kann ungleich null sein. Das Feld, das ungleich null ist, wird serialisiert.

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

// Nur ein Feld kann 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. zum Speichern oder Weiterleiten)
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 von 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 serialisiert wird, werden die Tools korrekt serialisiert.
b2, _ := json.Marshal(params)
fmt.Println(string(b) == string(b2)) // true

Für diesen Anwendungsfall wird param.SetJSON (verfügbar seit v1.20.0) gegenüber dem allgemeineren param.Override[T](any) bevorzugt, 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 Pointer oder Wrapper). Response-Structs enthalten außerdem ein spezielles JSON-Feld mit Metadaten zu jeder 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 verarbeiten, verwende die .Valid()-Methode 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üfungen 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 außerdem eine ExtraFields-Map mit allen Eigenschaften in der JSON-Response, die nicht im Struct spezifiziert 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 .AsFooVariant()-Methode oder die .AsAny()-Methode, falls vorhanden.

Wenn eine Response-Wert-Union primitive Werte enthält, stehen primitive Felder neben den Eigenschaften, sind aber mit Of präfigiert 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 animal-Variante
if animal.Owner.Address.ZipCode == "" {
	panic("missing zip code")
}

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

Fehlerbehandlung

Wenn die API einen Nicht-Erfolgs-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 außerdem die RequestID aus den Response-Headern, die für die Fehlersuche mit dem Anthropic-Support nützlich ist.

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

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

Wenn andere Fehler auftreten, werden sie ungewrappt zurückgegeben; zum Beispiel könntest du bei einem Fehler im HTTP-Transport einen *url.Error erhalten, der einen *net.OpError umschließt.

Wiederholungsversuche

Bestimmte Fehler werden standardmäßig automatisch 2-mal 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.ModelClaudeOpus4_8,
		},
		option.WithMaxRetries(5),
	)

Timeouts

Nicht-Streaming-Messages-Requests haben standardmäßig ein Timeout von 10 Minuten; andere Requests haben kein Standard-Timeout. Verwende den Context, um ein Timeout für den Lebenszyklus eines Requests zu konfigurieren.

Beachte, dass bei einem Wiederholungsversuch das Context-Timeout nicht neu startet. 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.ModelClaudeOpus4_8,
		},
		// 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 außerdem einen Fehler zurück, wenn erwartet wird, dass ein Nicht-Streaming-Request ungefähr länger als 10 Minuten dauert. Der Aufruf von .Messages.NewStreaming() oder das Festlegen 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-Form-Part 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 von 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 Hilfsmittel 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 Hilfsmethoden 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 „functional options"-Pattern (funktionale Optionen). Funktionen, die im option-Package definiert sind, geben eine RequestOption zurück, eine Closure, die eine RequestConfig verändert. Diese Optionen können dem Client oder einzelnen Requests übergeben werden. Zum Beispiel:

client := anthropic.NewClient(
	// Fügt jeder vom Client gesendeten Anfrage 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 Anfrage-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.

Anpassung des HTTP-Clients

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:

• 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-Packages registriert global einen Decoder für application/vnd.amazon.eventstream in der Streaming-Schicht des SDK (über Package-init()). Dies gilt unabhängig davon, ob du den bedrock-runtime-Pfad mit WithConfig/WithLoadDefaultConfig oder NewMantleClient verwendest.
• Vertex AI: import "github.com/anthropics/anthropic-sdk-go/vertex". Verwende vertex.WithGoogleAuth(ctx, region, projectID) oder vertex.WithCredentials(ctx, region, projectID, creds).

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.ModelClaudeOpus4_8,
	},
	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, Parameter oder Response-Eigenschaften zugreifen musst, kann die Bibliothek trotzdem verwendet werden.

Undokumentierte Endpunkte

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

var (
	// params kann ein io.Reader, ein []byte, ein mit encoding/json serialisierbares Objekt
	// oder eine in dieser Bibliothek definierte "...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-Parameter

Um Requests mit undokumentierten Parametern zu senden, kannst du entweder die Methode option.WithQuerySet() oder 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 Felds 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, eine map[string]respjson.Field.

Semantische Versionierung

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

1. Änderungen an Bibliotheksinterna, die technisch öffentlich sind, 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 betreffen.

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

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

Zusätzliche Ressourcen

• GitHub-Repository
• Go-Package-Dokumentation
• API-Referenz
• Streaming-Messages