---
title: Ruby SDK
url: https://platform.claude.com/docs/ru/cli-sdks-libraries/sdks/ruby
description: Установка и настройка Anthropic Ruby SDK с типами Sorbet, вспомогательными средствами для потоковой передачи и пулом соединений
---

Библиотека Anthropic для Ruby обеспечивает удобный доступ к Claude API из любого приложения на Ruby 3.2.0+. Она поставляется с исчерпывающими типами и строками документации в форматах YARD, RBS и RBI. В качестве HTTP-транспорта используется `net/http` из стандартной библиотеки, а пул соединений реализован с помощью гема `connection_pool`.

<Info>
  Документацию по функциям API с примерами кода см. в [справочнике API](https://platform.claude.com/docs/ru/api/overview). На этой странице описаны функции и настройка SDK, специфичные для Ruby.
</Info>

## Установка

Добавьте гем в `Gemfile` вашего приложения с помощью Bundler:

```bash
bundle add anthropic
```

## Требования

Ruby 3.2.0 или выше.

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

```ruby
anthropic = Anthropic::Client.new(
  api_key: ENV["ANTHROPIC_API_KEY"] # This is the default and can be omitted
)

message = anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5"
)

message.content.each do |block|
  puts block.text if block.type == :text
end
```

Сведения о вариантах аутентификации, включая Workload Identity Federation, см. в разделе [Аутентификация](https://platform.claude.com/docs/ru/manage-claude/authentication). Если ваш ключ API является [ключом персональной или сервисной учётной записи](https://platform.claude.com/docs/ru/manage-claude/authentication#key-types), который не привязан к рабочему пространству, укажите идентификатор рабочего пространства в заголовке запроса `anthropic-workspace-id`; в разделе [Выбор рабочего пространства](https://platform.claude.com/docs/ru/manage-claude/authentication#select-a-workspace) показан вариант указания для каждого запроса в этом SDK.

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

SDK поддерживает «streaming» (потоковая передача) ответов с использованием Server-Sent Events (SSE).

```ruby
anthropic = Anthropic::Client.new
stream = anthropic.messages.stream(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5"
)

stream.each do |message|
  puts(message.type)
end
```

### Вспомогательные средства для потоковой передачи

Эта библиотека предоставляет несколько удобных средств для потоковой передачи сообщений, например:

```ruby
anthropic = Anthropic::Client.new
stream = anthropic.messages.stream(
  max_tokens: 1024,
  messages: [{role: :user, content: "Say hello there!"}],
  model: :"claude-opus-5-5"
)

stream.text.each do |text|
  print(text)
end
```

Потоковая передача с помощью `anthropic.messages.stream(...)` предоставляет различные вспомогательные средства, включая накопление и события, специфичные для SDK.

## Схема входных данных и вызов инструментов

SDK предоставляет вспомогательные механизмы для определения классов структурированных данных для инструментов и позволяет Claude автоматически выполнять их. Подробную документацию по шаблонам «tool use» (использование инструментов), включая средство запуска инструментов, см. в разделе [Tool Runner (SDK)](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-runner).

```ruby
anthropic = Anthropic::Client.new
class CalculatorInput < Anthropic::BaseModel
  required :lhs, Float
  required :rhs, Float
  required :operator, Anthropic::InputSchema::EnumOf[:+, :-, :*, :/]
end

class Calculator < Anthropic::BaseTool
  input_schema CalculatorInput

  def call(expr)
    expr.lhs.public_send(expr.operator, expr.rhs)
  end
end

# Автоматически обрабатывает цикл выполнения инструментов
anthropic.beta.messages.tool_runner(
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [{role: "user", content: "What's 15 * 7?"}],
  tools: [Calculator.new]
).each_message { |message| puts message.content }
```

## Структурированные выходные данные

Полную документацию по структурированным выходным данным, включая примеры на Ruby, см. в разделе [Структурированные выходные данные](https://platform.claude.com/docs/ru/build-with-claude/structured-outputs).

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

Если библиотеке не удаётся подключиться к API или API возвращает код состояния, отличный от успешного (то есть ответ 4xx или 5xx), выбрасывается подкласс `Anthropic::Errors::APIError`:

```ruby
anthropic = Anthropic::Client.new
begin
  message = anthropic.messages.create(
    max_tokens: 1024,
    messages: [{role: "user", content: "Hello, Claude"}],
    model: :"claude-opus-5-5"
  )
rescue Anthropic::Errors::APIConnectionError => e
  puts("The server could not be reached")
  puts(e.cause)  # an underlying Exception, likely raised within `net/http`
rescue Anthropic::Errors::RateLimitError => e
  puts("A 429 status code was received; we should back off a bit.")
rescue Anthropic::Errors::APIStatusError => e
  puts("Another non-200-range status code was received")
  puts(e.status)
end
```

Коды ошибок следующие:

| Причина            | Тип ошибки                 |
| ------------------ | -------------------------- |
| HTTP 400           | `BadRequestError`          |
| HTTP 401           | `AuthenticationError`      |
| HTTP 403           | `PermissionDeniedError`    |
| HTTP 404           | `NotFoundError`            |
| HTTP 409           | `ConflictError`            |
| HTTP 422           | `UnprocessableEntityError` |
| HTTP 429           | `RateLimitError`           |
| HTTP >= 500        | `InternalServerError`      |
| Другая ошибка HTTP | `APIStatusError`           |
| Тайм-аут           | `APITimeoutError`          |
| Сетевая ошибка     | `APIConnectionError`       |

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

Некоторые ошибки по умолчанию автоматически повторяются 2 раза с короткой экспоненциальной задержкой.

Ошибки соединения (например, из-за проблем с сетевым подключением), 408 Request Timeout, 409 Conflict, 429 Rate Limit, внутренние ошибки >=500 и тайм-ауты по умолчанию повторяются.

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

```ruby
# Настройте значение по умолчанию для всех запросов:
anthropic = Anthropic::Client.new(
  max_retries: 0 # default is 2
)

# Или настройте для отдельного запроса:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5",
  request_options: {max_retries: 5}
)
```

## Тайм-ауты

По умолчанию время ожидания запросов истекает через 10 минут. Вы можете использовать параметр `timeout`, чтобы настроить это:

```ruby
# Настройка значения по умолчанию для всех запросов:
anthropic = Anthropic::Client.new(
  timeout: 20 # 20 seconds (default is 10 minutes)
)

# Или настройка для отдельного запроса:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5",
  request_options: {timeout: 5}
)
```

При тайм-ауте выбрасывается `Anthropic::Errors::APITimeoutError`.

Обратите внимание, что запросы, завершившиеся по тайм-ауту, по умолчанию повторяются.

## Пагинация

Методы получения списков в Claude API поддерживают пагинацию.

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

```ruby
anthropic = Anthropic::Client.new
page = anthropic.messages.batches.list(limit: 20)

# Получить один элемент со страницы.
batch = page.data[0]
puts(batch.id)

# Автоматически загружает дополнительные страницы по мере необходимости.
page.auto_paging_each do |batch|
  puts(batch.id)
end
```

В качестве альтернативы вы можете использовать методы `#next_page?` и `#next_page` для более детального управления работой со страницами.

```ruby
anthropic = Anthropic::Client.new
page = anthropic.messages.batches.list(limit: 20)
loop do
  page.data&.each { |batch| puts(batch.id) }
  break unless page.next_page?
  page = page.next_page
end
```

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

Параметры запроса, соответствующие загрузке файлов, можно передавать в виде необработанного содержимого, экземпляра [`Pathname`](https://rubyapi.org/3.2/o/pathname), [`StringIO`](https://rubyapi.org/3.2/o/stringio) и других.

```ruby
anthropic = Anthropic::Client.new
require "pathname"

# Используйте `Pathname`, чтобы передать имя файла и/или не загружать большой файл в память целиком:
file_metadata = anthropic.files.upload(file: Pathname("/path/to/file"))

# Либо передайте содержимое файла или `StringIO` напрямую:
file_metadata = anthropic.files.upload(file: File.read("/path/to/file"))

# Или, чтобы задать имя файла и/или тип содержимого:
file = Anthropic::FilePart.new(File.read("/path/to/file"), filename: "/path/to/file", content_type: "...")
file_metadata = anthropic.files.upload(file: file)

puts(file_metadata.id)
```

Обратите внимание, что вы также можете передать необработанный дескриптор `IO`, но это отключает повторные попытки, поскольку библиотека не может быть уверена, является ли дескриптор файлом или каналом (который нельзя перемотать).

## Sorbet

Эта библиотека предоставляет исчерпывающие определения [RBI](https://sorbet.org/docs/rbi) и не зависит от sorbet-runtime.

Вы можете передавать типобезопасные параметры запроса следующим образом:

```ruby
anthropic = Anthropic::Client.new
anthropic.messages.create(
  max_tokens: 1024,
  messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
  model: :"claude-opus-5-5"
)
```

Или, что эквивалентно:

```ruby
anthropic = Anthropic::Client.new
# Хэши работают, но не обеспечивают типобезопасность:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5"
)

# Также можно развернуть (splat) целый класс Params:
params = Anthropic::MessageCreateParams.new(
  max_tokens: 1024,
  messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
  model: :"claude-opus-5-5"
)
anthropic.messages.create(**params)
```

### Перечисления

Поскольку эта библиотека не зависит от `sorbet-runtime`, она не может предоставлять экземпляры [`T::Enum`](https://sorbet.org/docs/tenum). Вместо этого SDK предоставляет «помеченные символы» (tagged symbols), которые во время выполнения всегда являются примитивами:

```ruby
# :auto
puts(Anthropic::MessageCreateParams::ServiceTier::AUTO)

# Выведенный тип: `T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)`
T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO)
```

Параметры-перечисления имеют «ослабленный» тип, поэтому вы можете передавать либо константы перечисления, либо их литеральные значения:

```ruby
anthropic = Anthropic::Client.new
# Использование констант перечисления сохраняет информацию о тегированном типе:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: Anthropic::Model::CLAUDE_OPUS_5_5,
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO
)

# Литеральные значения также допустимы:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5",
  service_tier: :auto
)
```

## BaseModel

Все объекты параметров и ответов наследуются от `Anthropic::Internal::Type::BaseModel`, который предоставляет ряд удобств, в том числе:

1. Все поля, включая неизвестные, доступны с помощью синтаксиса `obj[:prop]` и могут быть деструктурированы с помощью `obj => {prop: prop}` или синтаксиса сопоставления с образцом.

2. Структурная эквивалентность при сравнении на равенство. Если два вызова API возвращают одинаковые значения, сравнение ответов с помощью == вернёт true.

3. Как экземпляры, так и сами классы можно выводить в удобочитаемом формате (pretty-print).

4. Вспомогательные методы, такие как `#to_h`, `#deep_to_h`, `#to_json` и `#to_yaml`.

## Параллелизм и пул соединений

Экземпляры `Anthropic::Client` потокобезопасны, но безопасны при fork только тогда, когда нет выполняющихся HTTP-запросов.

Каждый экземпляр `Anthropic::Client` имеет собственный пул HTTP-соединений с размером по умолчанию 99. Поэтому в большинстве случаев рекомендуется создавать клиент один раз на приложение.

Когда все доступные соединения из пула заняты, запросы ожидают освобождения нового соединения, причём время ожидания в очереди учитывается в тайм-ауте запроса.

Если не указано иное, другие классы в SDK не имеют блокировок, защищающих их базовые структуры данных.

## Трассировка OpenTelemetry

Когда ваше приложение регистрирует провайдер трассировщика OpenTelemetry, SDK создаёт спан для каждого отправляемого запроса. Чтобы отправлять спаны на вашу платформу наблюдаемости, см. [Настройка OpenTelemetry с Claude SDK](https://platform.claude.com/docs/ru/manage-claude/opentelemetry/sdk).

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

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

Вы можете отправлять недокументированные параметры в любую конечную точку и читать недокументированные свойства ответа следующим образом:

<Warning>
  Параметры `extra_` с тем же именем переопределяют документированные параметры. В целях безопасности убедитесь, что эти методы используются только с доверенными входными данными.
</Warning>

```ruby
anthropic = Anthropic::Client.new
value = "example"
message =
  anthropic.messages.create(
    max_tokens: 1024,
    messages: [{role: "user", content: "Hello, Claude"}],
    model: :"claude-opus-5-5",
    request_options: {
      extra_query: {my_query_parameter: value},
      extra_body: {my_body_parameter: value},
      extra_headers: {"my-header": value}
    }
  )

puts(message[:my_undocumented_property])
```

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

Если вы хотите явно отправить дополнительный параметр, вы можете сделать это с помощью `extra_query`, `extra_body` и `extra_headers` в параметре `request_options:` при выполнении запроса, как показано в предыдущих примерах.

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

Чтобы выполнять запросы к недокументированным конечным точкам, сохраняя преимущества аутентификации, повторных попыток и так далее, вы можете использовать `anthropic.request` следующим образом:

```ruby
response = anthropic.request(
  method: :post,
  path: '/undocumented/endpoint',
  query: {"dog": "woof"},
  headers: {"useful-header": "interesting-value"},
  body: {"hello": "world"}
)
```

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

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

  * [Amazon Bedrock](https://platform.claude.com/docs/ru/build-with-claude/claude-in-amazon-bedrock)
  * [Amazon Bedrock (Opus 4.6 и более ранние версии)](https://platform.claude.com/docs/ru/build-with-claude/claude-on-amazon-bedrock-legacy)
  * [Claude Platform on AWS](https://platform.claude.com/docs/ru/build-with-claude/claude-platform-on-aws)
  * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ru/build-with-claude/claude-models-on-google-cloud/google-managed)

  См. также [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ru/build-with-claude/claude-models-on-google-cloud/anthropic-managed).
</Note>

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

* **Agent Platform:** `Anthropic::VertexClient`. Требуется гем `googleauth`.
* **Bedrock:** `Anthropic::BedrockMantleClient` или `Anthropic::BedrockClient` для пути `bedrock-runtime`. Для `Anthropic::BedrockMantleClient` требуется гем `aws-sdk-core`; для `Anthropic::BedrockClient` требуется гем `aws-sdk-bedrockruntime`.
* **Claude Platform on AWS:** входит в основной гем `anthropic` (требуется гем `aws-sdk-core`). Предоставляет `Anthropic::AWSClient`. Передайте `workspace_id:` в конструктор или задайте переменную окружения `ANTHROPIC_AWS_WORKSPACE_ID` (см. [Рабочие пространства](https://platform.claude.com/docs/ru/build-with-claude/claude-platform-on-aws#workspaces)). Доступно в бета-версии.
* **Foundry:** в настоящее время не поддерживается в Ruby SDK. Поддерживаемые SDK см. в разделе [Claude в Microsoft Foundry](https://platform.claude.com/docs/ru/build-with-claude/claude-in-microsoft-foundry).

Используйте `Anthropic::BedrockMantleClient` для новых проектов; `Anthropic::BedrockClient` сохраняется для существующих приложений, использующих API Bedrock `InvokeModel`.

Ruby SDK также поддерживает Claude Models on Google Cloud (Anthropic managed) через `Anthropic::GoogleCloudClient`. Этот клиент находится в стадии бета-тестирования. Он поставляется в основном геме `anthropic` и требует гем `googleauth`. Передайте `workspace_id:` в конструктор или задайте переменную окружения `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`. О том, как клиент определяет идентификатор рабочего пространства, см. в разделе [Определение проекта, расположения и рабочего пространства](https://platform.claude.com/docs/ru/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution).

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

Каждая мажорная версия этого SDK по умолчанию отправляет одну версию API в заголовке `anthropic-version`, и с каждой новой версией API выходит новая мажорная версия. Первая мажорная версия, отправляющая `2026-10-21`, — это 2.0.0; см. [Миграция на версию API 2026-10-21](https://platform.claude.com/docs/ru/api/migration-2026-10-21#upgrade).

Этот пакет следует соглашениям [SemVer](https://semver.org/spec/v2.0.0.html).

Этот пакет считает улучшения определений типов `*.rbi` и `*.rbs` (не используемых во время выполнения) изменениями, не нарушающими совместимость.

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

* [Репозиторий GitHub](https://github.com/anthropics/anthropic-sdk-ruby)
* [Документация YARD](https://gemdocs.org/gems/anthropic)
* [Справочник API](https://platform.claude.com/docs/ru/api/overview)
* [Потоковая передача сообщений](https://platform.claude.com/docs/ru/build-with-claude/streaming)