Ruby SDK

Библиотека Anthropic для Ruby обеспечивает удобный доступ к REST API Anthropic из любого приложения на 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-4-8"
)

puts(message.content)

Варианты аутентификации, включая 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-4-8"
)

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

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

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

Входная схема и вызов инструментов

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

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

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

# Вы также можете развернуть полный класс Params через splat:
params = Anthropic::MessageCreateParams.new(
  max_tokens: 1024,
  messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
  model: :"claude-opus-4-8"
)
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)

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

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

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

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

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

Этот пакет следует соглашениям SemVer. Поскольку библиотека находится на начальном этапе разработки и имеет мажорную версию 0, API могут измениться в любое время.

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

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

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