---
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による「connection pooling」（コネクションプーリング）が行われます。

<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を設定してください。[ワークスペースを選択する](https://platform.claude.com/docs/ja/manage-claude/authentication#select-a-workspace)では、このSDKにおけるリクエストごとのオプションを示しています。

## ストリーミング

SDKは、Server-Sent Events（SSE）を使用した「streaming」（ストリーミング）レスポンスをサポートしています。

```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にそれらを自動的に実行させるためのヘルパーメカニズムを提供します。ツールランナーを含むツール使用パターンの詳細なドキュメントについては、[ツールランナー（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 Internalエラー、およびタイムアウトは、すべてデフォルトでリトライされます。

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

### Enum

このライブラリは`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)
```

Enumパラメータは「緩和された」型を持つため、enum定数またはそのリテラル値のどちらでも渡すことができます。

```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. インスタンスとクラス自体の両方をpretty-printできます。

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

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

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

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

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

特に明記されていない限り、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)
  * [Google Cloud](https://platform.claude.com/docs/ja/build-with-claude/claude-on-vertex-ai)
</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を使用する既存のアプリケーション向けに引き続き提供されます。

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

このパッケージは[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)