Go SDK

Pustaka Anthropic Go menyediakan akses yang mudah ke Anthropic REST API dari aplikasi yang ditulis dalam Go.

Instalasi

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

Instal dengan go get:

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

Persyaratan

Pustaka ini memerlukan Go 1.23+.

Penggunaan

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

Untuk opsi autentikasi termasuk Workload Identity Federation, lihat Autentikasi.

Field permintaan

Pustaka anthropic menggunakan semantik omitzero dari rilis encoding/json Go 1.24+ untuk field permintaan.

Field primitif yang wajib (int64, string, dll.) memiliki tag `json:"...,required"`. Field ini selalu diserialisasi, bahkan nilai nolnya.

Tipe primitif opsional dibungkus dalam param.Opt[T]. Field ini dapat diatur dengan konstruktor yang disediakan, anthropic.String(string), anthropic.Int(int64), dll.

Setiap param.Opt[T], map, slice, struct, atau enum string menggunakan tag `json:"...,omitzero"`. Nilai nolnya dianggap dihilangkan.

Fungsi param.IsOmitted(any) dapat mengonfirmasi keberadaan field omitzero apa pun.

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
		// ... field yang tidak wajib dan dihilangkan tidak akan diserialisasi
	},

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

Untuk mengirim null alih-alih param.Opt[T], gunakan param.Null[T](). Untuk mengirim null alih-alih struct T, gunakan 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

Struct permintaan berisi metode .SetExtraFields(map[string]any) yang dapat mengirim field yang tidak sesuai dalam body permintaan. Field tambahan akan menimpa field struct apa pun dengan key yang cocok.

Untuk mengirim nilai kustom alih-alih struct, gunakan fungsi generik param.Override (misalnya, param.Override[anthropic.FooParams](12)).

// Dalam kasus di mana API menentukan tipe tertentu,
// tetapi Anda ingin mengirim sesuatu yang lain, gunakan [SetExtraFields]:
p.SetExtraFields(map[string]any{
	"x": 0.01, // send "x" as a float instead of int
})

// Kirim angka alih-alih objek
custom := param.Override[anthropic.FooParams](12)

Union permintaan

Union direpresentasikan sebagai struct dengan field yang diawali dengan "Of" untuk setiap variannya, hanya satu field yang boleh bernilai non-zero. Field non-zero tersebut yang akan diserialisasi.

Subproperti dari union dapat diakses melalui metode pada struct union. Metode ini mengembalikan pointer yang dapat diubah ke data yang mendasarinya, jika ada.

// Hanya satu field yang boleh bernilai non-zero, gunakan param.IsOmitted() untuk memeriksa apakah field telah diatur
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},
		},
	},
}

// Memodifikasi sebuah field
if address := animal.GetOwner().GetAddress(); address != nil {
	address.ZipCode = 94304
}

Deserialisasi params

Tipe param (tipe yang diakhiri dengan Param, seperti MessageNewParams atau ToolUnionParam) dirancang hanya untuk permintaan keluar. Tipe ini melakukan marshal ke JSON dengan benar tetapi tidak sepenuhnya mendukung deserialisasi bolak-balik (round-trip). Jika Anda melakukan unmarshal JSON mentah ke dalam struct param, field union bertipe seperti OfBashTool20250124 akan bernilai nil meskipun JSON yang mendasarinya valid.

Jika Anda perlu merekonstruksi params dari JSON mentah (misalnya, dari database, middleware, atau permintaan sebelumnya), panggil UnmarshalJSON untuk mengisi field non-union, lalu gunakan param.SetJSON untuk melampirkan byte mentah agar serialisasi ulang dilakukan dengan benar:

// Serialisasi params (misalnya, untuk penyimpanan atau penerusan)
b, err := json.Marshal(original)
if err != nil {
	panic(err)
}

// Kemudian, rekonstruksi params dari JSON yang tersimpan
var params anthropic.MessageNewParams
if err := params.UnmarshalJSON(b); err != nil {
	panic(err)
}
param.SetJSON(b, &params)

// params.Model dan field skalar lainnya diisi oleh UnmarshalJSON.
// params.Tools[0].OfBashTool20250124 bernilai nil (keterbatasan union),
// tetapi JSON mentahnya tetap dipertahankan. Ketika params di-marshal lagi
// untuk panggilan API, tools akan diserialisasi dengan benar.
b2, _ := json.Marshal(params)
fmt.Println(string(b) == string(b2)) // true

Untuk kasus penggunaan ini, param.SetJSON (tersedia sejak v1.20.0) lebih disarankan daripada param.Override[T](any) yang lebih umum karena tidak memerlukan penulisan parameter tipe secara eksplisit dan membuat maksud round-trip menjadi jelas.

Objek respons

Semua field dalam struct respons adalah tipe nilai biasa (bukan pointer atau wrapper). Struct respons juga menyertakan field JSON khusus yang berisi metadata tentang setiap properti.

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

Untuk menangani data opsional, gunakan metode .Valid() pada field JSON. .Valid() mengembalikan true ketika field tersebut ada, bukan null, dan berhasil di-unmarshal.

Jika .Valid() bernilai false, field yang bersangkutan akan bernilai nol.

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

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

// Mengakses field biasa

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

// Pemeriksaan field opsional

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

// Nilai JSON mentah

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

Struct .JSON ini juga menyertakan map ExtraFields yang berisi properti apa pun dalam respons json yang tidak ditentukan dalam struct. Ini dapat berguna untuk fitur API yang belum tersedia di SDK.

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

Union respons

Dalam respons, union direpresentasikan oleh struct yang diratakan yang berisi semua field yang mungkin dari setiap varian objek. Untuk mengonversinya ke varian, gunakan metode .AsFooVariant() atau metode .AsAny() jika tersedia.

Jika union nilai respons berisi nilai primitif, field primitif akan berada di samping properti lainnya tetapi diawali dengan Of dan memiliki tag json:"...,inline".

type AnimalUnion struct {
	// Dari varian [Dog], [Cat]
	Owner Person `json:"owner"`
	// Dari varian [Dog]
	DogBreed string `json:"dog_breed"`
	// Dari varian [Cat]
	CatBreed string `json:"cat_breed"`
	// ...

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

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

// Switch berdasarkan varian
switch variant := animal.AsAny().(type) {
case Dog:
case Cat:
default:
	panic("unexpected type")
}

Penanganan error

Ketika API mengembalikan kode status non-sukses, SDK mengembalikan error dengan tipe *anthropic.Error. Ini berisi nilai StatusCode, *http.Request, dan *http.Response dari permintaan, serta JSON dari body error (seperti objek respons lainnya di SDK). Error ini juga menyertakan RequestID dari header respons, yang berguna untuk pemecahan masalah dengan dukungan Anthropic.

Untuk menangani error, gunakan pola 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) { ... }
}

Ketika error lain terjadi, error tersebut dikembalikan tanpa dibungkus; misalnya, jika transport HTTP gagal, Anda mungkin menerima *url.Error yang membungkus *net.OpError.

Percobaan ulang

Error tertentu akan secara otomatis dicoba ulang 2 kali secara default, dengan exponential backoff singkat. SDK secara default mencoba ulang semua error koneksi, 408 Request Timeout, 409 Conflict, 429 Rate Limit, dan error Internal >=500.

Anda dapat menggunakan opsi WithMaxRetries untuk mengonfigurasi atau menonaktifkan ini:

// Konfigurasikan default untuk semua permintaan:
client := anthropic.NewClient(
	option.WithMaxRetries(0), // default is 2
)

// Timpa per permintaan:
// ...
	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),
	)

Timeout

Permintaan Messages non-streaming memiliki timeout 10 menit secara default; permintaan lainnya tidak memiliki timeout default. Gunakan context untuk mengonfigurasi timeout untuk siklus hidup permintaan.

Perhatikan bahwa jika permintaan dicoba ulang, timeout context tidak dimulai dari awal. Untuk mengatur timeout per percobaan ulang, gunakan option.WithRequestTimeout().

// Ini mengatur batas waktu untuk permintaan, termasuk semua percobaan ulang.
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,
		},
		// Ini mengatur batas waktu per percobaan ulang
		option.WithRequestTimeout(20*time.Second),
	)

Permintaan panjang

Hindari mengatur nilai MaxTokens yang besar tanpa menggunakan streaming karena beberapa jaringan mungkin memutus koneksi idle setelah periode waktu tertentu, yang dapat menyebabkan permintaan gagal atau timeout tanpa menerima respons dari Anthropic.

SDK ini juga akan mengembalikan error jika permintaan non-streaming diperkirakan akan berlangsung lebih dari sekitar 10 menit. Memanggil .Messages.NewStreaming() atau mengatur timeout kustom akan menonaktifkan error ini.

Unggahan file

Parameter permintaan yang berkaitan dengan unggahan file dalam permintaan multipart bertipe io.Reader. Konten dari io.Reader secara default akan dikirim sebagai bagian form multipart dengan nama file "anonymous_file" dan content-type "application/octet-stream", sehingga pendekatan yang direkomendasikan adalah menentukan content-type kustom dengan helper anthropic.File(reader io.Reader, filename string, contentType string), yang membungkus io.Reader apa pun dengan nama file dan content type yang sesuai.

// File dari sistem file
file, err := os.Open("/path/to/file.json")
anthropic.BetaFileUploadParams{
	File: anthropic.File(file, "custom-name.json", "application/json"),
}

// File dari string
anthropic.BetaFileUploadParams{
	File: anthropic.File(strings.NewReader("my file contents"), "custom-name.json", "application/json"),
}

Nama file dan content-type juga dapat dikustomisasi dengan mengimplementasikan Name() string atau ContentType() string pada tipe run-time dari io.Reader. Perhatikan bahwa os.File mengimplementasikan Name() string, sehingga file yang dikembalikan oleh os.Open akan dikirim dengan nama file di disk.

Paginasi

Pustaka ini menyediakan beberapa kemudahan untuk bekerja dengan endpoint daftar yang dipaginasi.

Anda dapat menggunakan metode .ListAutoPaging() untuk melakukan iterasi melalui item di semua halaman:

iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
	Limit: anthropic.Int(20),
})
// Secara otomatis mengambil lebih banyak halaman sesuai kebutuhan.
for iter.Next() {
	messageBatch := iter.Current()
	fmt.Printf("%+v\n", messageBatch)
}
if err := iter.Err(); err != nil {
	panic(err.Error())
}

Atau Anda dapat menggunakan metode .List() sederhana untuk mengambil satu halaman dan menerima objek respons standar dengan metode helper tambahan seperti .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

Pustaka ini menggunakan pola opsi fungsional. Fungsi yang didefinisikan dalam paket option mengembalikan RequestOption, yang merupakan closure yang memutasi RequestConfig. Opsi ini dapat diberikan ke client atau pada permintaan individual. Misalnya:

client := anthropic.NewClient(
	// Menambahkan header ke setiap permintaan yang dibuat oleh klien
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.Messages.New(context.TODO(), // ...,
	// Menimpa header tersebut
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Menambahkan field yang tidak terdokumentasi ke body permintaan, menggunakan sintaks sjson
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

Opsi permintaan option.WithDebugLog(nil) mungkin berguna saat melakukan debugging.

Lihat daftar lengkap opsi permintaan.

Kustomisasi HTTP client

Untuk middleware permintaan (option.WithMiddleware) dan mengganti http.Client default (option.WithHTTPClient), lihat middleware SDK.

Integrasi platform

Go SDK mendukung platform berikut:

• Bedrock: import "github.com/anthropics/anthropic-sdk-go/bedrock". Gunakan bedrock.NewMantleClient untuk endpoint Bedrock Messages-API (melakukan streaming melalui SSE), atau bedrock.WithLoadDefaultConfig(ctx) / bedrock.WithConfig(cfg) (jalur bedrock-runtime). Mengimpor paket bedrock secara global mendaftarkan decoder untuk application/vnd.amazon.eventstream dengan lapisan streaming SDK (melalui init() paket). Ini berlaku baik Anda menggunakan jalur bedrock-runtime WithConfig/WithLoadDefaultConfig maupun NewMantleClient.
• Vertex AI: import "github.com/anthropics/anthropic-sdk-go/vertex". Gunakan vertex.WithGoogleAuth(ctx, region, projectID) atau vertex.WithCredentials(ctx, region, projectID, creds).
• Saat ini tidak didukung di Go SDK. Lihat untuk SDK yang didukung.

Gunakan bedrock.NewMantleClient untuk proyek baru; bedrock.WithLoadDefaultConfig/WithConfig tetap tersedia untuk aplikasi yang sudah ada yang menggunakan Bedrock InvokeModel API.

Penggunaan lanjutan

Mengakses data respons mentah (misalnya, header respons)

Anda dapat mengakses data respons HTTP mentah dengan menggunakan opsi permintaan option.WithResponseInto(). Ini berguna ketika Anda perlu memeriksa header respons, kode status, atau detail lainnya.

// Buat variabel untuk menyimpan respons 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 {
	// tangani error
}
fmt.Printf("%+v\n", message)

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

Membuat permintaan kustom/tidak terdokumentasi

Pustaka ini diberi tipe untuk akses yang mudah ke API yang terdokumentasi. Jika Anda perlu mengakses endpoint, params, atau properti respons yang tidak terdokumentasi, pustaka ini tetap dapat digunakan.

Endpoint tidak terdokumentasi

Untuk membuat permintaan ke endpoint yang tidak terdokumentasi, Anda dapat menggunakan client.Get, client.Post, dan verb HTTP lainnya. RequestOptions pada client, seperti percobaan ulang, akan dihormati saat membuat permintaan ini.

var (
	// params dapat berupa io.Reader, []byte, objek yang dapat diserialisasi encoding/json,
	// atau struct "...Params" yang didefinisikan dalam pustaka ini.
	params map[string]any

	// result dapat berupa []byte, *http.Response, objek yang dapat dideserialisasi encoding/json,
	// atau model yang didefinisikan dalam pustaka ini.
	result *http.Response
)
err := client.Post(context.Background(), "/unspecified", params, &result)
if err != nil {
	// ...
}

Params permintaan tidak terdokumentasi

Untuk membuat permintaan menggunakan parameter yang tidak terdokumentasi, Anda dapat menggunakan metode option.WithQuerySet() atau 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"))

Properti respons tidak terdokumentasi

Untuk mengakses properti respons yang tidak terdokumentasi, Anda dapat mengakses JSON mentah dari respons sebagai string dengan result.JSON.RawJSON(), atau mendapatkan JSON mentah dari field tertentu pada hasil dengan result.JSON.Foo.Raw().

Field apa pun yang tidak ada pada struct respons akan disimpan dan dapat diakses melalui result.JSON.ExtraFields, yang merupakan map[string]respjson.Field.

Semantic versioning

Paket ini secara umum mengikuti konvensi SemVer, meskipun perubahan tertentu yang tidak kompatibel ke belakang dapat dirilis sebagai versi minor:

1. Perubahan pada internal pustaka yang secara teknis publik tetapi tidak dimaksudkan atau didokumentasikan untuk penggunaan eksternal.
2. Perubahan yang tidak diperkirakan akan memengaruhi sebagian besar pengguna dalam praktiknya.

Kompatibilitas ke belakang ditangani dengan serius untuk memastikan Anda dapat mengandalkan pengalaman upgrade yang lancar.

Umpan balik Anda sangat diharapkan; buka issue dengan pertanyaan, bug, atau saran.

Sumber daya tambahan

• Repositori GitHub
• Dokumentasi paket Go
• Referensi API
• Streaming Messages