CLI、SDK、ライブラリクライアントSDK

Ruby SDK

Sorbet型、ストリーミングヘルパー、コネクションプーリングを備えたAnthropic Ruby SDKのインストールと設定

Anthropic Rubyライブラリは、Ruby 3.2.0以降のアプリケーションからAnthropic REST APIへの便利なアクセスを提供します。Yard、RBS、RBI形式の包括的な型定義とdocstringが付属しています。HTTPトランスポートには標準ライブラリのnet/httpが使用され、connection_pool gemを通じてコネクションプーリングが実現されています。

コード例付きのAPI機能ドキュメントについては、APIリファレンスを参照してください。このページでは、Ruby固有のSDK機能と設定について説明します。

インストール

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

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

エラーコードは以下のとおりです。

原因	エラータイプ
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-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-runtimへの依存はありません。

以下のように型安全なリクエストパラメータを提供できます。

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クラスをスプラット展開することもできます：
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)

Enum

このライブラリはsorbet-runtimeに依存していないため、T::Enumインスタンスを提供できません。代わりに、SDKは「タグ付きシンボル」を提供しており、これは実行時には常にプリミティブです。

# :auto
puts(Anthropic::MessageCreateParams::ServiceTier::AUTO)

# 判明した型: `T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)`
T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO)

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

# 列挙型定数を使用すると、タグ付き型情報が保持されます：
anthropic.messages.create(
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
  # ...
)

# リテラル値も使用可能です：
anthropic.messages.create(
  service_tier: :auto,
  # ...
)

BaseModel

すべてのパラメータおよびレスポンスオブジェクトはAnthropic::Internal::Type::BaseModelを継承しており、以下のような便利な機能を提供します。

未知のフィールドを含むすべてのフィールドはobj[:prop]構文でアクセス可能で、obj => {prop: prop}またはパターンマッチング構文で分割代入できます。
等価性における構造的等価性。2つのAPI呼び出しが同じ値を返す場合、レスポンスを==で比較するとtrueが返されます。
インスタンスとクラス自体の両方をpretty-printできます。
#to_h、#deep_to_h、#to_json、#to_yamlなどのヘルパー。

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

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

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

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

特に指定がない限り、SDK内の他のクラスには、基礎となるデータ構造を保護するロックはありません。

カスタムまたは未文書化のリクエストの作成

未文書化のプロパティ

以下のように、任意のエンドポイントに未文書化のパラメータを送信し、未文書化のレスポンスプロパティを読み取ることができます。

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

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

未文書化のリクエストパラメータ

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

未文書化のエンドポイント

認証、リトライなどの利点を保持しながら未文書化のエンドポイントにリクエストを送信するには、以下のように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、またはbedrock-runtimeパス用のAnthropic::BedrockClient。Anthropic::BedrockMantleClientにはaws-sdk-core gemが必要です。Anthropic::BedrockClientにはaws-sdk-bedrockruntime gemが必要です。
Vertex AI： Anthropic::VertexClient。googleauth gemが必要です。
Foundry： 現在、Ruby SDKではサポートされていません。サポートされているSDKについては、Microsoft FoundryでのClaudeを参照してください。
Claude Platform on AWS： メインのanthropic gemの一部です（aws-sdk-core gemが必要）。Anthropic::AWSClientを提供します。コンストラクタにworkspace_id:を渡すか、ANTHROPIC_AWS_WORKSPACE_ID環境変数を設定してください（ワークスペースを参照）。ベータ版で利用可能です。

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

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

このパッケージはSemVerの規約に従っています。ライブラリは初期開発段階にあり、メジャーバージョンが0であるため、APIはいつでも変更される可能性があります。

このパッケージでは、（非ランタイムの）*.rbiおよび*.rbs型定義の改善は、破壊的変更ではないと見なされます。

追加リソース

Was this page helpful?

CLI、SDK、ライブラリクライアントSDK

Ruby SDK

Sorbet型、ストリーミングヘルパー、コネクションプーリングを備えたAnthropic Ruby SDKのインストールと設定

インストール

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

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固有のイベントなど、さまざまなヘルパーが利用できます。

入力スキーマとツール呼び出し

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の例を含む構造化出力の完全なドキュメントについては、構造化出力を参照してください。

エラー処理

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

エラーコードは以下のとおりです。

原因	エラータイプ
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回リトライされます。

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)

Sorbet

このライブラリは包括的なRBI定義を提供しており、sorbet-runtimへの依存はありません。

以下のように型安全なリクエストパラメータを提供できます。

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クラスをスプラット展開することもできます：
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)

Enum

# :auto
puts(Anthropic::MessageCreateParams::ServiceTier::AUTO)

# 判明した型: `T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)`
T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO)

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

# 列挙型定数を使用すると、タグ付き型情報が保持されます：
anthropic.messages.create(
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
  # ...
)

# リテラル値も使用可能です：
anthropic.messages.create(
  service_tier: :auto,
  # ...
)

BaseModel

すべてのパラメータおよびレスポンスオブジェクトはAnthropic::Internal::Type::BaseModelを継承しており、以下のような便利な機能を提供します。

未知のフィールドを含むすべてのフィールドはobj[:prop]構文でアクセス可能で、obj => {prop: prop}またはパターンマッチング構文で分割代入できます。
等価性における構造的等価性。2つのAPI呼び出しが同じ値を返す場合、レスポンスを==で比較するとtrueが返されます。
インスタンスとクラス自体の両方をpretty-printできます。
#to_h、#deep_to_h、#to_json、#to_yamlなどのヘルパー。

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

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

特に指定がない限り、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])

未文書化のリクエストパラメータ

未文書化のエンドポイント

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

プラットフォーム統合

コード例付きの詳細なプラットフォームセットアップガイドについては、以下を参照してください。

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

Bedrock： Anthropic::BedrockMantleClient、またはbedrock-runtimeパス用のAnthropic::BedrockClient。Anthropic::BedrockMantleClientにはaws-sdk-core gemが必要です。Anthropic::BedrockClientにはaws-sdk-bedrockruntime gemが必要です。
Vertex AI： Anthropic::VertexClient。googleauth gemが必要です。
Foundry： 現在、Ruby SDKではサポートされていません。サポートされているSDKについては、Microsoft FoundryでのClaudeを参照してください。
Claude Platform on AWS： メインのanthropic gemの一部です（aws-sdk-core gemが必要）。Anthropic::AWSClientを提供します。コンストラクタにworkspace_id:を渡すか、ANTHROPIC_AWS_WORKSPACE_ID環境変数を設定してください（ワークスペースを参照）。ベータ版で利用可能です。

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

このパッケージでは、（非ランタイムの）*.rbiおよび*.rbs型定義の改善は、破壊的変更ではないと見なされます。

追加リソース

Was this page helpful?