Библиотека Anthropic Ruby предоставляет удобный доступ к REST API Anthropic из любого приложения на Ruby 3.2.0+. Она поставляется с полными типами и докстрингами в Yard, RBS и RBI. В качестве HTTP-транспорта используется net/http из стандартной библиотеки, а пул соединений реализован через гем connection_pool.
Документацию по функциям API с примерами кода см. в справочнике API. Эта страница охватывает специфичные для Ruby функции и конфигурацию SDK.
Добавьте гем в Gemfile вашего приложения с помощью Bundler:
bundle add anthropicRuby 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 поддерживает «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 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Коды ошибок следующие:
| Причина | Тип ошибки |
|---|---|
| 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, чтобы настроить или отключить это:
# Настройте значение по умолчанию для всех запросов:
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, но это отключает повторные попытки, так как библиотека не может быть уверена, является ли дескриптор файлом или каналом (который нельзя перемотать).
Эта библиотека предоставляет полные определения 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"
)
# Вы также можете развернуть (splat) полный класс Params:
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,
# ...
)Все объекты параметров и ответов наследуются от Anthropic::Internal::Type::BaseModel, который предоставляет несколько удобств, включая:
Все поля, включая неизвестные, доступны через синтаксис obj[:prop] и могут быть деструктурированы с помощью obj => {prop: prop} или синтаксиса сопоставления с образцом.
Структурная эквивалентность для равенства; если два вызова API возвращают одинаковые значения, сравнение ответов с помощью == вернёт true.
Как экземпляры, так и сами классы могут быть красиво напечатаны (pretty-printed).
Помощники, такие как #to_h, #deep_to_h, #to_json и #to_yaml.
Экземпляры Anthropic::Client потокобезопасны, но безопасны при форке только тогда, когда нет выполняющихся HTTP-запросов.
Каждый экземпляр Anthropic::Client имеет собственный пул HTTP-соединений с размером по умолчанию 99. Поэтому в большинстве случаев рекомендуется создавать клиент один раз на приложение.
Когда все доступные соединения из пула заняты, запросы ожидают, пока новое соединение станет доступным, при этом время ожидания в очереди учитывается в тайм-ауте запроса.
Если не указано иное, другие классы в SDK не имеют блокировок, защищающих их базовую структуру данных.
Вы можете отправлять недокументированные параметры на любую конечную точку и читать недокументированные свойства ответа следующим образом:
Параметры extra_ с тем же именем переопределяют документированные параметры. В целях безопасности убедитесь, что эти методы используются только с доверенными входными данными.
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 поддерживает следующие платформы:
Anthropic::VertexClient. Требуется гем googleauth.Anthropic::BedrockMantleClient или Anthropic::BedrockClient для пути bedrock-runtime. Для Anthropic::BedrockMantleClient требуется гем aws-sdk-core; для Anthropic::BedrockClient требуется гем aws-sdk-bedrockruntime.anthropic (требуется гем aws-sdk-core). Предоставляет Anthropic::AWSClient. Передайте workspace_id: в конструктор или установите переменную окружения ANTHROPIC_AWS_WORKSPACE_ID (см. Рабочие пространства). Доступно в бета-версии.Используйте Anthropic::BedrockMantleClient для новых проектов; Anthropic::BedrockClient остаётся для существующих приложений, использующих API Bedrock InvokeModel.
Этот пакет следует соглашениям SemVer. Поскольку библиотека находится в начальной стадии разработки и имеет основную версию 0, API могут измениться в любое время.
Этот пакет рассматривает улучшения определений типов *.rbi и *.rbs (не влияющих на время выполнения) как изменения, не нарушающие обратную совместимость.
Was this page helpful?