--- title: Ruby SDK url: https://platform.claude.com/docs/ru/cli-sdks-libraries/sdks/ruby description: Установка и настройка Anthropic Ruby SDK с типами Sorbet, вспомогательными средствами потоковой передачи и пулом соединений --- Библиотека Anthropic Ruby обеспечивает удобный доступ к Claude API из любого приложения на Ruby 3.2.0+. Она поставляется с исчерпывающими типами и строками документации в форматах YARD, RBS и RBI. В качестве HTTP-транспорта используется `net/http` из стандартной библиотеки, а пул соединений реализован через gem `connection_pool`. Документацию по функциям API с примерами кода см. в [справочнике API](https://platform.claude.com/docs/ru/api/overview). На этой странице рассматриваются специфичные для Ruby функции и настройка SDK. ## Установка Добавьте gem в `Gemfile` вашего приложения с помощью Bundler: ```bash bundle add anthropic ``` ## Требования Ruby 3.2.0 или выше. ## Использование ```ruby 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, описаны в разделе [Аутентификация](https://platform.claude.com/docs/ru/manage-claude/authentication). Если ваш ключ API является [персональным ключом или ключом сервисного аккаунта](https://platform.claude.com/docs/ru/manage-claude/authentication#key-types) с доступом к нескольким рабочим пространствам, укажите идентификатор рабочего пространства в заголовке запроса `anthropic-workspace-id`; в разделе [Выбор рабочего пространства](https://platform.claude.com/docs/ru/manage-claude/authentication#select-a-workspace) показан вариант настройки для отдельного запроса в этом SDK. ## Потоковая передача SDK поддерживает «streaming» (потоковую передачу) ответов с использованием Server-Sent Events (SSE). ```ruby 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 ``` ### Вспомогательные средства потоковой передачи Эта библиотека предоставляет несколько удобных средств для потоковой передачи сообщений, например: ```ruby 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» (использования инструментов), включая средство запуска инструментов, см. в разделе [Средство запуска инструментов (SDK)](https://platform.claude.com/docs/ru/agents-and-tools/tool-use/tool-runner). ```ruby 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, см. в разделе [Структурированные выходные данные](https://platform.claude.com/docs/ru/build-with-claude/structured-outputs). ## Обработка ошибок Когда библиотека не может подключиться к API или API возвращает код состояния, отличный от успешного (то есть ответ 4xx или 5xx), выбрасывается подкласс `Anthropic::Errors::APIError`: ```ruby 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 ``` Коды ошибок следующие: | Причина | Тип ошибки | | ------------------ | -------------------------- | | 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`, чтобы настроить или отключить это поведение: ```ruby # Настройка значения по умолчанию для всех запросов: 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`: ```ruby # Настройте значение по умолчанию для всех запросов: 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 поддерживают пагинацию. Эта библиотека предоставляет итераторы с автоматической пагинацией для каждого ответа со списком, поэтому вам не нужно вручную запрашивать последующие страницы: ```ruby 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` для более детального управления работой со страницами. ```ruby 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`](https://rubyapi.org/3.2/o/pathname), [`StringIO`](https://rubyapi.org/3.2/o/stringio) и других вариантов. ```ruby 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](https://sorbet.org/docs/rbi) и не зависит от sorbet-runtime. Вы можете передавать типобезопасные параметры запроса следующим образом: ```ruby anthropic = Anthropic::Client.new anthropic.messages.create( max_tokens: 1024, messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")], model: :"claude-opus-5-5" ) ``` Или, что эквивалентно: ```ruby 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`](https://sorbet.org/docs/tenum). Вместо этого SDK предоставляет «тегированные символы», которые во время выполнения всегда являются примитивами: ```ruby # :auto puts(Anthropic::MessageCreateParams::ServiceTier::AUTO) # Выявленный тип: `T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)` T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO) ``` Параметры-перечисления имеют «ослабленный» тип, поэтому вы можете передавать либо константы перечисления, либо их литеральные значения: ```ruby anthropic = Anthropic::Client.new # Использование констант enum сохраняет информацию о тегированном типе: 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 не имеют блокировок, защищающих их внутренние структуры данных. ## Выполнение пользовательских или недокументированных запросов ### Недокументированные свойства Вы можете отправлять недокументированные параметры на любую конечную точку и читать недокументированные свойства ответа следующим образом: Параметры `extra_` с тем же именем переопределяют документированные параметры. В целях безопасности убедитесь, что эти методы используются только с доверенными входными данными. ```ruby 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` следующим образом: ```ruby response = anthropic.request( method: :post, path: '/undocumented/endpoint', query: {"dog": "woof"}, headers: {"useful-header": "interesting-value"}, body: {"hello": "world"} ) ``` ## Интеграции с платформами Подробные руководства по настройке платформ с примерами кода см. в разделах: * [Amazon Bedrock](https://platform.claude.com/docs/ru/build-with-claude/claude-in-amazon-bedrock) * [Amazon Bedrock (Opus 4.6 и более ранние)](https://platform.claude.com/docs/ru/build-with-claude/claude-on-amazon-bedrock-legacy) * [Claude Platform на AWS](https://platform.claude.com/docs/ru/build-with-claude/claude-platform-on-aws) * [Google Cloud](https://platform.claude.com/docs/ru/build-with-claude/claude-on-vertex-ai) 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` (см. [Рабочие пространства](https://platform.claude.com/docs/ru/build-with-claude/claude-platform-on-aws#workspaces)). Доступно в бета-версии. * **Foundry:** В настоящее время не поддерживается в Ruby SDK. Поддерживаемые SDK см. в разделе [Claude в Microsoft Foundry](https://platform.claude.com/docs/ru/build-with-claude/claude-in-microsoft-foundry). Используйте `Anthropic::BedrockMantleClient` для новых проектов; `Anthropic::BedrockClient` остаётся для существующих приложений, использующих API Bedrock `InvokeModel`. ## Семантическое версионирование Этот пакет следует соглашениям [SemVer](https://semver.org/spec/v2.0.0.html). Этот пакет рассматривает улучшения определений типов `*.rbi` и `*.rbs` (не используемых во время выполнения) как изменения, не нарушающие обратную совместимость. ## Дополнительные ресурсы * [Репозиторий GitHub](https://github.com/anthropics/anthropic-sdk-ruby) * [Документация YARD](https://gemdocs.org/gems/anthropic) * [Справочник API](https://platform.claude.com/docs/ru/api/overview) * [Потоковая передача сообщений](https://platform.claude.com/docs/ru/build-with-claude/streaming)