Ruby SDK

Библиотека Anthropic Ruby обеспечивает удобный доступ к Anthropic REST 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"
)

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

Информацию о вариантах аутентификации, включая Workload Identity Federation, см. в разделе Аутентификация.



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

SDK поддерживает потоковую передачу ответов с использованием «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 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",
  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.beta.files.upload(file: Pathname("/path/to/file"))

# Либо передайте содержимое файла или объект `StringIO` напрямую:
file_metadata = anthropic.beta.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.beta.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 предоставляет «помеченные символы» (tagged symbols), которые во время выполнения всегда являются примитивами:

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

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

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

# Использование констант перечисления сохраняет информацию о типе с тегом:
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. Как экземпляры, так и сами классы могут быть красиво выведены на печать.

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. Требуется гем googleauth.
• Bedrock: Anthropic::BedrockMantleClient или Anthropic::BedrockClient для пути bedrock-runtime. Для Anthropic::BedrockMantleClient требуется гем aws-sdk-core; для Anthropic::BedrockClient требуется гем aws-sdk-bedrockruntime.
• Claude Platform на AWS: Входит в основной гем anthropic (требуется гем aws-sdk-core). Предоставляет Anthropic::AWSClient. Передайте workspace_id: в конструктор или установите переменную окружения ANTHROPIC_AWS_WORKSPACE_ID (см. Рабочие пространства). Доступно в бета-версии.
• Foundry: В настоящее время не поддерживается в Ruby SDK. Поддерживаемые SDK см. в разделе Claude в Microsoft Foundry.

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



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

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

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



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

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