Claude Platform Docs
CLI, SDK и библиотекиКлиентские SDK

Go SDK

Установка и настройка Anthropic Go SDK с отменой на основе контекста и функциональными опциями

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

Установка

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

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

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

Требования

Эта библиотека требует Go 1.24+.

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

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

Варианты аутентификации, включая Workload Identity Federation, описаны в разделе Аутентификация. Если ваш ключ API является персональным ключом или ключом сервисного аккаунта с доступом к нескольким рабочим пространствам, укажите идентификатор рабочего пространства в заголовке запроса anthropic-workspace-id; в разделе Выбор рабочего пространства показан вариант настройки для отдельного запроса в этом SDK.

Поля запроса

Библиотека 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)

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

Объединения представлены как структура с полями, имеющими префикс "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, чтобы прикрепить сырые байты для корректной повторной сериализации:

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

// Позже восстановите params из сохранённого 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 (ограничение объединения),
// но исходный 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 также включают map 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.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) { ... }
}

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

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

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

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

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

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

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

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

Параметры запроса, соответствующие загрузке файлов в многочастных запросах, типизированы как io.Reader. Содержимое io.Reader по умолчанию будет отправлено как многочастная часть формы с именем файла "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.FileUploadParams{
	File: anthropic.File(file, "custom-name.json", "application/json"),
}

// Файл из строки
anthropic.FileUploadParams{
	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.Println(messageBatch.ID)
}
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.Println(batch.ID)
	}
	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 поддерживает следующие платформы:

  • Agent Platform: import "github.com/anthropics/anthropic-sdk-go/vertex". Используйте vertex.WithGoogleAuth(ctx, region, projectID) или vertex.WithCredentials(ctx, region, projectID, creds).
  • 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.
  • Claude Platform на AWS: import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws". Используйте anthropicaws.NewClient(ctx, cfg) со значением anthropicaws.ClientConfig для создания клиента; установите WorkspaceID в конфигурации или переменную окружения ANTHROPIC_AWS_WORKSPACE_ID. Псевдоним импорта anthropicaws избегает конфликта имён с github.com/aws/aws-sdk-go-v2/aws, когда оба импортируются. Доступно в бета-версии.
  • Foundry: В настоящее время не поддерживается в Go SDK. См. Claude в Microsoft Foundry для поддерживаемых SDK.

Используйте 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.ModelClaudeOpus5,
	},
	option.WithResponseInto(&response),
)
if err != nil {
	// обработка ошибки
}
fmt.Printf("%+v\n", message.Content)

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 с вопросами, ошибками или предложениями.

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

Was this page helpful?