Ruby SDK

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

Установка

Добавьте gem в 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"
)

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

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

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

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

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

SDK предоставляет вспомогательные механизмы для определения структурированных классов данных для инструментов и позволяет Claude автоматически их выполнять. Подробную документацию по шаблонам «tool use» (использования инструментов), включая средство запуска инструментов, см. в разделе Средство запуска инструментов (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",
  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"
  )
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",
  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",
  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"
)

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

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

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

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

Поскольку эта библиотека не зависит от sorbet-runtime, она не может предоставлять экземпляры T::Enum. Вместо этого SDK предоставляет «тегированные символы», которые во время выполнения всегда являются примитивами:

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

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

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

# Использование констант enum сохраняет информацию о тегированном типе:
anthropic.messages.create(
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
  # ...
)

# Литеральные значения также допустимы:
anthropic.messages.create(
  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 не имеют блокировок, защищающих их внутренние структуры данных.

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

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

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

anthropic = Anthropic::Client.new
value = "example"
message =
  anthropic.messages.create(
    max_tokens: 1024,
    messages: [{role: "user", content: "Hello, Claude"}],
    model: :"claude-opus-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. Требуется gem googleauth.
• Bedrock: Anthropic::BedrockMantleClient или Anthropic::BedrockClient для пути bedrock-runtime. Для Anthropic::BedrockMantleClient требуется gem aws-sdk-core; для Anthropic::BedrockClient требуется gem aws-sdk-bedrockruntime.
• Claude Platform на AWS: Входит в основной gem anthropic (требуется gem 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.

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

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

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

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

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