---
title: Ruby SDK
url: https://platform.claude.com/docs/ja/cli-sdks-libraries/sdks/ruby
description: Sorbet型、ストリーミングヘルパー、コネクションプーリングを備えたAnthropic Ruby SDKのインストールと設定
---

Anthropic Rubyライブラリは、Ruby 3.2.0以降の任意のアプリケーションからClaude APIへの便利なアクセスを提供します。YARD、RBS、RBIによる包括的な型とdocstringが同梱されています。HTTPトランスポートには標準ライブラリの`net/http`が使用され、`connection_pool` gemによるコネクションプーリングが行われます。

<Info>
  コード例を含むAPI機能のドキュメントについては、[APIリファレンス](https://platform.claude.com/docs/ja/api/overview)を参照してください。このページでは、Ruby固有のSDK機能と設定について説明します。
</Info>

## インストール

Bundlerを使用して、アプリケーションの`Gemfile`にgemを追加します：

```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/ja/manage-claude/authentication)を参照してください。APIキーがワークスペースにスコープされていない[個人キーまたはサービスアカウントキー](https://platform.claude.com/docs/ja/manage-claude/authentication#key-types)である場合は、`anthropic-workspace-id`リクエストヘッダーにワークスペースIDを設定してください。このSDKでのリクエストごとのオプションについては、[ワークスペースを選択する](https://platform.claude.com/docs/ja/manage-claude/authentication#select-a-workspace)で説明しています。

## ストリーミング

SDKは、「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 Runner (SDK)](https://platform.claude.com/docs/ja/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/ja/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"
)

# Params クラス全体を splat（展開）して渡すこともできます:
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. 等価性の判定に構造的等価性を使用します。2つのAPI呼び出しが同じ値を返す場合、レスポンスを==で比較するとtrueが返されます。

3. インスタンスとクラス自体の両方をプリティプリントできます。

4. `#to_h`、`#deep_to_h`、`#to_json`、`#to_yaml`などのヘルパー。

## 並行性とコネクションプーリング

`Anthropic::Client`インスタンスはスレッドセーフですが、処理中のHTTPリクエストがない場合にのみフォークセーフです。

`Anthropic::Client`の各インスタンスは、デフォルトサイズ99の独自のHTTPコネクションプールを持っています。そのため、ほとんどの環境では、アプリケーションごとにクライアントを1回作成することを推奨します。

プールから利用可能なすべての接続がチェックアウトされている場合、リクエストは新しい接続が利用可能になるまで待機し、キュー待ち時間はリクエストのタイムアウトに含まれます。

特に明記されていない限り、SDK内の他のクラスには、基盤となるデータ構造を保護するロックはありません。

## OpenTelemetryトレーシング

アプリケーションがOpenTelemetryトレーサープロバイダーを登録すると、SDKは送信する各リクエストについてスパンを出力します。スパンをオブザーバビリティプラットフォームに送信するには、[Claude SDKでOpenTelemetryを設定する](https://platform.claude.com/docs/ja/manage-claude/opentelemetry/sdk)を参照してください。

## カスタムリクエストまたはドキュメント化されていないリクエストの作成

### ドキュメント化されていないプロパティ

次のように、任意のエンドポイントにドキュメント化されていないパラメータを送信したり、ドキュメント化されていないレスポンスプロパティを読み取ったりできます：

<Warning>
  同じ名前の`extra_`パラメータは、ドキュメント化されたパラメータを上書きします。セキュリティ上の理由から、これらのメソッドは信頼できる入力データでのみ使用するようにしてください。
</Warning>

```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])
```

### ドキュメント化されていないリクエストパラメータ

追加のパラメータを明示的に送信したい場合は、前の例で示したように、リクエスト時に`request_options:`パラメータの下で`extra_query`、`extra_body`、`extra_headers`を使用して送信できます。

### ドキュメント化されていないエンドポイント

認証やリトライなどの利点を維持しながらドキュメント化されていないエンドポイントにリクエストを送信するには、次のように`anthropic.request`を使用してリクエストを送信できます：

```ruby
response = anthropic.request(
  method: :post,
  path: '/undocumented/endpoint',
  query: {"dog": "woof"},
  headers: {"useful-header": "interesting-value"},
  body: {"hello": "world"}
)
```

## プラットフォーム統合

<Note>
  コード例を含む詳細なプラットフォームセットアップガイドについては、以下を参照してください：

  * [Amazon Bedrock](https://platform.claude.com/docs/ja/build-with-claude/claude-in-amazon-bedrock)
  * [Amazon Bedrock（Opus 4.6以前）](https://platform.claude.com/docs/ja/build-with-claude/claude-on-amazon-bedrock-legacy)
  * [Claude Platform on AWS](https://platform.claude.com/docs/ja/build-with-claude/claude-platform-on-aws)
  * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/ja/build-with-claude/claude-models-on-google-cloud/google-managed)

  [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/ja/build-with-claude/claude-models-on-google-cloud/anthropic-managed)も参照してください。
</Note>

Ruby SDKは次のプラットフォームをサポートしています：

* **Agent Platform：** `Anthropic::VertexClient`。`googleauth` gemが必要です。
* **Bedrock：** `Anthropic::BedrockMantleClient`、または`bedrock-runtime`パス用の`Anthropic::BedrockClient`。`Anthropic::BedrockMantleClient`には`aws-sdk-core` gemが必要です。`Anthropic::BedrockClient`には`aws-sdk-bedrockruntime` gemが必要です。
* **Claude Platform on AWS：** メインの`anthropic` gemの一部です（`aws-sdk-core` gemが必要）。`Anthropic::AWSClient`を提供します。コンストラクタに`workspace_id:`を渡すか、`ANTHROPIC_AWS_WORKSPACE_ID`環境変数を設定してください（[ワークスペース](https://platform.claude.com/docs/ja/build-with-claude/claude-platform-on-aws#workspaces)を参照）。ベータ版で利用可能です。
* **Foundry：** 現在Ruby SDKではサポートされていません。サポートされているSDKについては、[Claude in Microsoft Foundry](https://platform.claude.com/docs/ja/build-with-claude/claude-in-microsoft-foundry)を参照してください。

新しいプロジェクトには`Anthropic::BedrockMantleClient`を使用してください。`Anthropic::BedrockClient`は、Bedrock `InvokeModel` APIを使用する既存のアプリケーション向けに引き続き提供されます。

Ruby SDKは、`Anthropic::GoogleCloudClient`を通じてClaude Models on Google Cloud (Anthropic managed)もサポートしています。このクライアントはベータ版です。メインの`anthropic` gemに含まれており、`googleauth` gemが必要です。コンストラクタに`workspace_id:`を渡すか、`ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`環境変数を設定してください。クライアントがワークスペースIDを解決する方法については、[プロジェクト、ロケーション、およびワークスペースの解決](https://platform.claude.com/docs/ja/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution)を参照してください。

## セマンティックバージョニング

このSDKの各メジャーバージョンは、デフォルトで`anthropic-version`ヘッダーに1つのAPIバージョンを送信し、新しいAPIバージョンごとに新しいメジャーバージョンがリリースされます。`2026-10-21`を送信する最初のメジャーバージョンは2.0.0です。[APIバージョン2026-10-21への移行](https://platform.claude.com/docs/ja/api/migration-2026-10-21#upgrade)を参照してください。

このパッケージは[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/ja/api/overview)
* [メッセージのストリーミング](https://platform.claude.com/docs/ja/build-with-claude/streaming)