Ruby SDK

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

Установка

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

bundle add anthropic

Требования

Ruby 3.2.0 или выше.

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

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, см. в разделе Аутентификация. Если ваш ключ API является ключом персональной или сервисной учётной записи, который не привязан к рабочему пространству, укажите идентификатор рабочего пространства в заголовке запроса anthropic-workspace-id; в разделе Выбор рабочего пространства показан вариант указания для каждого запроса в этом SDK.

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

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

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

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

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

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

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, см. в разделе Структурированные выходные данные.

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

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

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

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

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

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

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

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

# Настройте значение по умолчанию для всех запросов:
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, чтобы настроить это:

# Настройка значения по умолчанию для всех запросов:
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 поддерживают пагинацию.

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

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 для более детального управления работой со страницами.

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, StringIO и других.

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 и не зависит от sorbet-runtime.

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

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

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

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. Вместо этого SDK предоставляет «помеченные символы» (tagged symbols), которые во время выполнения всегда являются примитивами:

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

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

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

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.

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

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

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

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 следующим образом:

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

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

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 (см. Рабочие пространства). Доступно в бета-версии.
• Foundry: в настоящее время не поддерживается в Ruby SDK. Поддерживаемые SDK см. в разделе Claude в 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. О том, как клиент определяет идентификатор рабочего пространства, см. в разделе Определение проекта, расположения и рабочего пространства.

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

Каждая мажорная версия этого SDK по умолчанию отправляет одну версию API в заголовке anthropic-version, и с каждой новой версией API выходит новая мажорная версия. Первая мажорная версия, отправляющая 2026-10-21, — это 2.0.0; см. Миграция на версию API 2026-10-21.

Этот пакет следует соглашениям SemVer.

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

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

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