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

Go SDK

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

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

Документацию по функциям API с примерами кода см. в справочнике API. Эта страница охватывает специфичные для Go функции SDK и его конфигурацию.

Установка

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.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, см. в разделе Аутентификация.

Поля запроса

Библиотека 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, структура или строковое перечисление использует тег `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), который может отправлять несоответствующие схеме поля в теле запроса. Дополнительные поля перезаписывают любые поля структуры с совпадающим ключом.

Из соображений безопасности используйте SetExtraFields только с доверенными данными.

Чтобы отправить пользовательское значение вместо структуры, используйте обобщённую функцию 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.SetJSON требует SDK версии v1.20.0 или новее.

Типы параметров (типы, оканчивающиеся на 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 (ограничение 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 также включают 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.

Вы можете использовать опцию 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 минут; другие запросы не имеют тайм-аута по умолчанию. Используйте context для настройки тайм-аута жизненного цикла запроса.

Обратите внимание, что если запрос повторяется, тайм-аут контекста не начинается заново. Чтобы задать тайм-аут для каждой повторной попытки, используйте 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),
	)

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

Рассмотрите возможность использования потокового Messages API для более длительных запросов.

Избегайте установки большого значения 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 поддерживает следующие платформы:

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 остаются для существующих приложений, использующих API Bedrock InvokeModel.

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

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

Вы можете получить доступ к сырым данным 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)

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, хотя определённые обратно несовместимые изменения могут быть выпущены как минорные версии:

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

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

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

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

Was this page helpful?

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

Go SDK

Установите и настройте Anthropic 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.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, см. в разделе Аутентификация.

Поля запроса

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

Функция 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
}

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 только с доверенными данными.

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

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

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

// Только одно поле может быть ненулевым, используйте 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.SetJSON требует SDK версии v1.20.0 или новее.

// Сериализуем 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 (ограничение union-типа),
// но исходный JSON сохраняется. Когда params снова маршалится
// для вызова API, инструменты сериализуются корректно.
b2, _ := json.Marshal(params)
fmt.Println(string(b) == string(b2)) // true

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

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() равно 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

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

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

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

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

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

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

Вы можете использовать опцию 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),
	)

Тайм-ауты

// Это устанавливает тайм-аут для запроса, включая все повторные попытки.
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),
	)

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

Рассмотрите возможность использования потокового Messages API для более длительных запросов.

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

// Файл из файловой системы
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"),
}

Пагинация

Эта библиотека предоставляет некоторые удобства для работы с конечными точками списков с пагинацией.

Вы можете использовать методы .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())
}

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

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-клиента

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

Подробные руководства по настройке платформ с примерами кода см. в:

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.

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

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

// Создаём переменную для хранения 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)

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

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

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

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 {
	// ...
}

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

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

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

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

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

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

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

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

Was this page helpful?

Установка

Требования

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

Диалоги

Системные подсказки

Потоковая передача

Вызов инструментов

Поля запроса

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

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

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

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

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

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

Тайм-ауты

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

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

Пагинация

RequestOptions

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

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

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

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

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

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

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

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

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

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

Установка

Требования

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

Диалоги

Системные подсказки

Потоковая передача

Вызов инструментов

Поля запроса

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

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

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

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

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

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

Тайм-ауты

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

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

Пагинация

RequestOptions

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

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

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

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

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

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

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

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

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

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

Установка

Требования

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

Поля запроса

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

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

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

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

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

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

Тайм-ауты

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

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

Пагинация

RequestOptions

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

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

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

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

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

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

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

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

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

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

Установка

Требования

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

Поля запроса

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

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

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

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

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

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

Тайм-ауты

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

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

Пагинация

RequestOptions

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

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

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

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

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

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

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

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

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

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