Go SDK

Библиотека Anthropic для Go предоставляет удобный доступ к REST API Anthropic из приложений, написанных на Go.

Установка

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

Установите с помощью go get:

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

Требования

Для этой библиотеки требуется Go 1.23+.

Использование

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

Варианты аутентификации, включая Workload Identity Federation, см. в разделе Аутентификация.

Поля запроса

Библиотека anthropic использует семантику omitzero из релиза encoding/json в Go 1.24+ для полей запроса.

Обязательные примитивные поля (int64, string и т. д.) имеют тег `json:"...,required"`. Эти поля всегда сериализуются, даже при нулевых значениях.

Необязательные примитивные типы оборачиваются в param.Opt[T]. Эти поля можно задавать с помощью предоставленных конструкторов: anthropic.String(string), anthropic.Int(int64) и т. д.

Любой param.Opt[T], map, slice, struct или строковый enum использует тег `json:"...,omitzero"`. Его нулевое значение считается опущенным.

Функция param.IsOmitted(any) позволяет проверить наличие любого поля с 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
		// ... пропущенные необязательные поля не будут сериализованы
	},

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

Чтобы отправить null вместо param.Opt[T], используйте param.Null[T](). Чтобы отправить null вместо структуры T, используйте 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

Структуры запросов содержат метод .SetExtraFields(map[string]any), который позволяет отправлять нестандартные поля в теле запроса. Дополнительные поля перезаписывают любые поля структуры с совпадающим ключом.

Чтобы отправить пользовательское значение вместо структуры, используйте обобщённую функцию param.Override (например, param.Override[anthropic.FooParams](12)).

// В случаях, когда API указывает определённый тип,
// но вы хотите отправить что-то другое, используйте [SetExtraFields]:
p.SetExtraFields(map[string]any{
	"x": 0.01, // send "x" as a float instead of int
})

// Отправляем число вместо объекта
custom := param.Override[anthropic.FooParams](12)

Объединения в запросах

Объединения (unions) представлены в виде структуры с полями, имеющими префикс «Of» для каждого из вариантов; только одно поле может быть ненулевым. Ненулевое поле будет сериализовано.

Доступ к подсвойствам объединения можно получить через методы структуры объединения. Эти методы возвращают изменяемый указатель на базовые данные, если они присутствуют.

// Только одно поле может быть ненулевым; используйте param.IsOmitted(), чтобы проверить, задано ли поле
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},
		},
	},
}

// Изменение поля
if address := animal.GetOwner().GetAddress(); address != nil {
	address.ZipCode = 94304
}

Десериализация параметров

Типы параметров (типы, оканчивающиеся на Param, такие как MessageNewParams или ToolUnionParam) предназначены только для исходящих запросов. Они корректно маршалятся в JSON, но не полностью поддерживают двустороннюю десериализацию. Если вы демаршалите необработанный JSON в структуру параметров, типизированные поля объединений, такие как OfBashTool20250124, будут равны nil, даже если базовый JSON корректен.

Если вам нужно восстановить параметры из необработанного JSON (например, из базы данных, промежуточного ПО или предыдущего запроса), вызовите UnmarshalJSON, чтобы заполнить поля, не являющиеся объединениями, а затем используйте param.SetJSON, чтобы прикрепить необработанные байты для корректной повторной сериализации:

// Сериализуем параметры (например, для хранения или пересылки)
b, err := json.Marshal(original)
if err != nil {
	panic(err)
}

// Позже восстанавливаем параметры из сохранённого JSON
var params anthropic.MessageNewParams
if err := params.UnmarshalJSON(b); err != nil {
	panic(err)
}
param.SetJSON(b, &params)

// params.Model и другие скалярные поля заполняются методом UnmarshalJSON.
// params.Tools[0].OfBashTool20250124 равен nil (ограничение union-типов),
// но исходный JSON сохраняется. Когда params снова маршалится
// для вызова API, инструменты сериализуются корректно.
b2, _ := json.Marshal(params)
fmt.Println(string(b) == string(b2)) // true

Для этого сценария использования param.SetJSON (доступен начиная с v1.20.0) предпочтительнее более общей функции param.Override[T](any), поскольку не требует явного указания параметра типа и делает намерение двустороннего преобразования явным.

Объекты ответа

Все поля в структурах ответа являются обычными типами-значениями (не указателями и не обёртками). Структуры ответа также включают специальное поле JSON, содержащее метаданные о каждом свойстве.

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

Для обработки необязательных данных используйте метод .Valid() поля JSON. .Valid() возвращает true, если поле присутствует, не равно null и было успешно демаршалено.

Если .Valid() возвращает false, соответствующее поле будет иметь нулевое значение.

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

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

// Доступ к обычным полям

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

// Проверки необязательных полей

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

// Необработанные значения JSON

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

Эти структуры .JSON также включают карту ExtraFields, содержащую любые свойства из JSON-ответа, которые не были указаны в структуре. Это может быть полезно для функций API, ещё не представленных в SDK.

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

Объединения в ответах

В ответах объединения представлены уплощённой структурой, содержащей все возможные поля из каждого варианта объекта. Чтобы преобразовать её в конкретный вариант, используйте метод .AsFooVariant() или метод .AsAny(), если он присутствует.

Если объединение значений ответа содержит примитивные значения, примитивные поля будут располагаться рядом со свойствами, но с префиксом Of и тегом json:"...,inline".

type AnimalUnion struct {
	// Из вариантов [Dog], [Cat]
	Owner Person `json:"owner"`
	// Из варианта [Dog]
	DogBreed string `json:"dog_breed"`
	// Из варианта [Cat]
	CatBreed string `json:"cat_breed"`
	// ...

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

// Если вариант animal
if animal.Owner.Address.ZipCode == "" {
	panic("missing zip code")
}

// Переключение по варианту
switch variant := animal.AsAny().(type) {
case Dog:
case Cat:
default:
	panic("unexpected type")
}

Обработка ошибок

Когда API возвращает код состояния, отличный от успешного, SDK возвращает ошибку типа *anthropic.Error. Она содержит значения StatusCode, *http.Request и *http.Response запроса, а также JSON тела ошибки (аналогично другим объектам ответа в SDK). Ошибка также включает RequestID из заголовков ответа, что полезно при обращении в службу поддержки Anthropic.

Для обработки ошибок используйте паттерн 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) { ... }
}

Когда возникают другие ошибки, они возвращаются без обёртки; например, если HTTP-транспорт завершается сбоем, вы можете получить *url.Error, оборачивающий *net.OpError.

Повторные попытки

Определённые ошибки по умолчанию автоматически повторяются 2 раза с короткой экспоненциальной задержкой. SDK по умолчанию повторяет все ошибки соединения, 408 Request Timeout, 409 Conflict, 429 Rate Limit и внутренние ошибки >=500.

Вы можете использовать опцию WithMaxRetries, чтобы настроить или отключить это поведение:

// Настройте значение по умолчанию для всех запросов:
client := anthropic.NewClient(
	option.WithMaxRetries(0), // default is 2
)

// Переопределите для отдельного запроса:
// ...
	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),
	)

Тайм-ауты

Непотоковые запросы Messages по умолчанию завершаются по тайм-ауту через 10 минут; для других запросов тайм-аут по умолчанию не установлен. Используйте контекст, чтобы настроить тайм-аут для жизненного цикла запроса.

Обратите внимание, что если запрос повторяется, тайм-аут контекста не начинается заново. Чтобы установить тайм-аут для каждой отдельной попытки, используйте option.WithRequestTimeout().

// Это задаёт тайм-аут для запроса, включая все повторные попытки.
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,
		},
		// Это задаёт тайм-аут для каждой повторной попытки
		option.WithRequestTimeout(20*time.Second),
	)

Длительные запросы

Избегайте установки большого значения MaxTokens без использования потоковой передачи, так как некоторые сети могут разрывать простаивающие соединения через определённый период времени, что может привести к сбою запроса или тайм-ауту без получения ответа от Anthropic.

Этот SDK также вернёт ошибку, если ожидается, что непотоковый запрос займёт примерно более 10 минут. Вызов .Messages.NewStreaming() или установка пользовательского тайм-аута отключает эту ошибку.

Загрузка файлов

Параметры запроса, соответствующие загрузке файлов в multipart-запросах, типизированы как io.Reader. Содержимое io.Reader по умолчанию будет отправлено как часть multipart-формы с именем файла «anonymous_file» и content-type «application/octet-stream», поэтому рекомендуемый подход — указать пользовательский content-type с помощью вспомогательной функции anthropic.File(reader io.Reader, filename string, contentType string), которая оборачивает любой io.Reader с соответствующим именем файла и типом содержимого.

// Файл из файловой системы
file, err := os.Open("/path/to/file.json")
anthropic.BetaFileUploadParams{
	File: anthropic.File(file, "custom-name.json", "application/json"),
}

// Файл из строки
anthropic.BetaFileUploadParams{
	File: anthropic.File(strings.NewReader("my file contents"), "custom-name.json", "application/json"),
}

Имя файла и content-type также можно настроить, реализовав Name() string или ContentType() string для типа времени выполнения io.Reader. Обратите внимание, что os.File реализует Name() string, поэтому файл, возвращённый os.Open, будет отправлен с именем файла на диске.

Пагинация

Эта библиотека предоставляет ряд удобств для работы с конечными точками, возвращающими постраничные списки.

Вы можете использовать методы .ListAutoPaging() для итерации по элементам на всех страницах:

iter := client.Messages.Batches.ListAutoPaging(context.TODO(), anthropic.MessageBatchListParams{
	Limit: anthropic.Int(20),
})
// Автоматически загружает дополнительные страницы по мере необходимости.
for iter.Next() {
	messageBatch := iter.Current()
	fmt.Printf("%+v\n", messageBatch)
}
if err := iter.Err(); err != nil {
	panic(err.Error())
}

Или вы можете использовать простые методы .List(), чтобы получить одну страницу и стандартный объект ответа с дополнительными вспомогательными методами, такими как .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

Эта библиотека использует паттерн функциональных опций. Функции, определённые в пакете option, возвращают RequestOption — замыкание, которое изменяет RequestConfig. Эти опции можно передавать клиенту или отдельным запросам. Например:

client := anthropic.NewClient(
	// Добавляет заголовок к каждому запросу, выполняемому клиентом
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.Messages.New(context.TODO(), // ...,
	// Переопределить заголовок
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Добавить недокументированное поле в тело запроса, используя синтаксис sjson
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

Опция запроса option.WithDebugLog(nil) может быть полезна при отладке.

См. полный список опций запроса.

Настройка HTTP-клиента

О промежуточном ПО для запросов (option.WithMiddleware) и замене http.Client по умолчанию (option.WithHTTPClient) см. в разделе Промежуточное ПО SDK.

Интеграции с платформами

Go SDK поддерживает следующие платформы:

• Bedrock: import "github.com/anthropics/anthropic-sdk-go/bedrock". Используйте bedrock.NewMantleClient для конечной точки Bedrock с Messages API (потоковая передача через SSE) или bedrock.WithLoadDefaultConfig(ctx) / bedrock.WithConfig(cfg) (путь bedrock-runtime). Импорт пакета bedrock глобально регистрирует декодер для application/vnd.amazon.eventstream в слое потоковой передачи SDK (через init() пакета). Это применяется независимо от того, используете ли вы путь bedrock-runtime через WithConfig/WithLoadDefaultConfig или NewMantleClient.
• Vertex AI: import "github.com/anthropics/anthropic-sdk-go/vertex". Используйте vertex.WithGoogleAuth(ctx, region, projectID) или vertex.WithCredentials(ctx, region, projectID, creds).

Используйте bedrock.NewMantleClient для новых проектов; bedrock.WithLoadDefaultConfig/WithConfig остаются для существующих приложений, использующих Bedrock InvokeModel API.

Расширенное использование

Доступ к необработанным данным ответа (например, заголовкам ответа)

Вы можете получить доступ к необработанным данным HTTP-ответа с помощью опции запроса option.WithResponseInto(). Это полезно, когда вам нужно изучить заголовки ответа, коды состояния или другие детали.

// Создайте переменную для хранения 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 {
	// обработать ошибку
}
fmt.Printf("%+v\n", message)

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

Выполнение пользовательских/недокументированных запросов

Эта библиотека типизирована для удобного доступа к документированному API. Если вам нужен доступ к недокументированным конечным точкам, параметрам или свойствам ответа, библиотеку всё равно можно использовать.

Недокументированные конечные точки

Для выполнения запросов к недокументированным конечным точкам вы можете использовать client.Get, client.Post и другие HTTP-глаголы. RequestOptions клиента, такие как повторные попытки, будут учитываться при выполнении этих запросов.

var (
	// params может быть io.Reader, []byte, объектом, сериализуемым через encoding/json,
	// или структурой «...Params», определённой в этой библиотеке.
	params map[string]any

	// result может быть []byte, *http.Response, объектом, десериализуемым через encoding/json,
	// или моделью, определённой в этой библиотеке.
	result *http.Response
)
err := client.Post(context.Background(), "/unspecified", params, &result)
if err != nil {
	// ...
}

Недокументированные параметры запроса

Для выполнения запросов с недокументированными параметрами вы можете использовать методы option.WithQuerySet() или 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"))

Недокументированные свойства ответа

Для доступа к недокументированным свойствам ответа вы можете либо получить необработанный JSON ответа в виде строки с помощью result.JSON.RawJSON(), либо получить необработанный JSON конкретного поля результата с помощью result.JSON.Foo.Raw().

Любые поля, отсутствующие в структуре ответа, сохраняются и доступны через result.JSON.ExtraFields, который представляет собой map[string]respjson.Field.

Семантическое версионирование

Этот пакет в целом следует соглашениям SemVer, хотя некоторые обратно несовместимые изменения могут выпускаться как минорные версии:

1. Изменения во внутренних компонентах библиотеки, которые технически являются публичными, но не предназначены и не документированы для внешнего использования.
2. Изменения, которые, как ожидается, не затронут подавляющее большинство пользователей на практике.

К обратной совместимости относятся серьёзно, чтобы обеспечить вам плавный процесс обновления.

Ваши отзывы приветствуются; откройте issue с вопросами, сообщениями об ошибках или предложениями.

Дополнительные ресурсы

• Репозиторий на GitHub
• Документация пакета Go
• Справочник по API
• Потоковая передача сообщений