SDK Ruby

Pustaka Anthropic Ruby menyediakan akses yang mudah ke REST API Anthropic dari aplikasi Ruby 3.2.0+ apa pun. Pustaka ini dilengkapi dengan tipe dan docstring yang komprehensif dalam Yard, RBS, dan RBI. net/http dari pustaka standar digunakan sebagai transport HTTP, dengan "connection pooling" (pengelompokan koneksi) melalui gem connection_pool.



Instalasi

Tambahkan gem ke Gemfile aplikasi Anda dengan Bundler:

bundle add anthropic



Persyaratan

Ruby 3.2.0 atau lebih tinggi.



Penggunaan

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

Untuk opsi autentikasi termasuk Workload Identity Federation, lihat Autentikasi.



Streaming

SDK menyediakan dukungan untuk streaming respons menggunakan 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



Helper streaming

Pustaka ini menyediakan beberapa kemudahan untuk streaming pesan, misalnya:

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

Streaming dengan anthropic.messages.stream(...) mengekspos berbagai helper termasuk akumulasi dan event khusus SDK.



Skema input dan pemanggilan alat

SDK menyediakan mekanisme helper untuk mendefinisikan kelas data terstruktur untuk alat dan membiarkan Claude mengeksekusinya secara otomatis. Untuk dokumentasi terperinci tentang pola penggunaan alat termasuk tool runner, lihat 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

# Secara otomatis menangani loop eksekusi alat
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 }



Output terstruktur

Untuk dokumentasi lengkap tentang output terstruktur termasuk contoh Ruby, lihat Output terstruktur.



Menangani error

Ketika pustaka tidak dapat terhubung ke API, atau jika API mengembalikan kode status non-sukses (yaitu, respons 4xx atau 5xx), subkelas dari Anthropic::Errors::APIError akan dimunculkan:

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

Kode error adalah sebagai berikut:



Percobaan ulang

Error tertentu akan secara otomatis dicoba ulang 2 kali secara default, dengan "exponential backoff" (penundaan eksponensial) singkat.

Error koneksi (misalnya, karena masalah konektivitas jaringan), 408 Request Timeout, 409 Conflict, 429 Rate Limit, error Internal >=500, dan timeout semuanya dicoba ulang secara default.

Anda dapat menggunakan opsi max_retries untuk mengonfigurasi atau menonaktifkan ini:

# Konfigurasikan default untuk semua permintaan:
anthropic = Anthropic::Client.new(
  max_retries: 0 # default is 2
)

# Atau, konfigurasikan per permintaan:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5",
  request_options: {max_retries: 5}
)



Timeout

Secara default, permintaan akan timeout setelah 10 menit. Anda dapat menggunakan opsi timeout untuk mengonfigurasi ini:

# Konfigurasikan default untuk semua permintaan:
anthropic = Anthropic::Client.new(
  timeout: 20 # 20 seconds (default is 10 minutes)
)

# Atau, konfigurasikan per permintaan:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5",
  request_options: {timeout: 5}
)

Saat timeout, Anthropic::Errors::APITimeoutError akan dimunculkan.

Perhatikan bahwa permintaan yang timeout akan dicoba ulang secara default.



Paginasi

Metode list di Claude API menggunakan paginasi.

Pustaka ini menyediakan iterator dengan paginasi otomatis pada setiap respons list, sehingga Anda tidak perlu meminta halaman berikutnya secara manual:

anthropic = Anthropic::Client.new
page = anthropic.messages.batches.list(limit: 20)

# Mengambil satu item dari halaman.
batch = page.data[0]
puts(batch.id)

# Secara otomatis mengambil halaman berikutnya sesuai kebutuhan.
page.auto_paging_each do |batch|
  puts(batch.id)
end

Sebagai alternatif, Anda dapat menggunakan metode #next_page? dan #next_page untuk kontrol yang lebih terperinci saat bekerja dengan halaman.

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



Unggah file

Parameter permintaan yang berkaitan dengan unggahan file dapat diberikan sebagai konten mentah, instans Pathname, StringIO, atau lainnya.

anthropic = Anthropic::Client.new
require "pathname"

# Gunakan `Pathname` untuk mengirim nama file dan/atau menghindari memuat file besar ke dalam memori:
file_metadata = anthropic.beta.files.upload(file: Pathname("/path/to/file"))

# Sebagai alternatif, berikan isi file atau `StringIO` secara langsung:
file_metadata = anthropic.beta.files.upload(file: File.read("/path/to/file"))

# Atau, untuk mengontrol nama file dan/atau tipe konten:
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)

Perhatikan bahwa Anda juga dapat memberikan deskriptor IO mentah, tetapi ini menonaktifkan percobaan ulang, karena pustaka tidak dapat memastikan apakah deskriptor tersebut adalah file atau pipe (yang tidak dapat diputar ulang).



Sorbet

Pustaka ini menyediakan definisi RBI yang komprehensif, dan tidak memiliki dependensi pada sorbet-runtime.

Anda dapat memberikan parameter permintaan yang typesafe seperti berikut:

anthropic = Anthropic::Client.new
anthropic.messages.create(
  max_tokens: 1024,
  messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
  model: :"claude-opus-5"
)

Atau, secara setara:

anthropic = Anthropic::Client.new
# Hash dapat digunakan, tetapi tidak typesafe:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5"
)

# Anda juga dapat melakukan splat pada kelas Params lengkap:
params = Anthropic::MessageCreateParams.new(
  max_tokens: 1024,
  messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
  model: :"claude-opus-5"
)
anthropic.messages.create(**params)



Enum

Karena pustaka ini tidak bergantung pada sorbet-runtime, pustaka ini tidak dapat menyediakan instans T::Enum. Sebagai gantinya, SDK menyediakan "tagged symbols", yang selalu berupa primitif saat runtime:

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

# Tipe yang terungkap: `T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)`
T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO)

Parameter enum memiliki tipe yang "longgar", sehingga Anda dapat memberikan konstanta enum atau nilai literalnya:

# Menggunakan konstanta enum mempertahankan informasi tipe yang ditandai:
anthropic.messages.create(
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
  # ...
)

# Nilai literal juga diperbolehkan:
anthropic.messages.create(
  service_tier: :auto,
  # ...
)



BaseModel

Semua objek parameter dan respons mewarisi dari Anthropic::Internal::Type::BaseModel, yang menyediakan beberapa kemudahan, termasuk:

1. Semua field, termasuk yang tidak dikenal, dapat diakses dengan sintaks obj[:prop], dan dapat didestrukturisasi dengan obj => {prop: prop} atau sintaks pattern-matching.

2. Kesetaraan struktural untuk perbandingan; jika dua panggilan API mengembalikan nilai yang sama, membandingkan respons dengan == akan mengembalikan true.

3. Baik instans maupun kelasnya sendiri dapat di-pretty-print.

4. Helper seperti #to_h, #deep_to_h, #to_json, dan #to_yaml.



Konkurensi dan connection pooling

Instans Anthropic::Client bersifat threadsafe, tetapi hanya fork-safe ketika tidak ada permintaan HTTP yang sedang berlangsung.

Setiap instans Anthropic::Client memiliki pool koneksi HTTP sendiri dengan ukuran default 99. Oleh karena itu, rekomendasinya adalah membuat klien sekali per aplikasi dalam sebagian besar situasi.

Ketika semua koneksi yang tersedia dari pool sudah digunakan, permintaan akan menunggu koneksi baru tersedia, dengan waktu antrean dihitung ke dalam timeout permintaan.

Kecuali ditentukan lain, kelas lain dalam SDK tidak memiliki lock yang melindungi struktur data yang mendasarinya.



Membuat permintaan kustom atau tidak terdokumentasi



Properti tidak terdokumentasi

Anda dapat mengirim parameter yang tidak terdokumentasi ke endpoint mana pun, dan membaca properti respons yang tidak terdokumentasi, seperti berikut:

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



Parameter permintaan tidak terdokumentasi

Jika Anda ingin secara eksplisit mengirim parameter tambahan, Anda dapat melakukannya dengan extra_query, extra_body, dan extra_headers di bawah parameter request_options: saat membuat permintaan, seperti yang terlihat pada contoh di atas.



Endpoint tidak terdokumentasi

Untuk membuat permintaan ke endpoint yang tidak terdokumentasi sambil tetap mempertahankan manfaat autentikasi, percobaan ulang, dan sebagainya, Anda dapat membuat permintaan menggunakan anthropic.request, seperti berikut:

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



Integrasi platform

SDK Ruby mendukung platform berikut:

• Agent Platform: Anthropic::VertexClient. Memerlukan gem googleauth.
• Bedrock: Anthropic::BedrockMantleClient, atau Anthropic::BedrockClient untuk jalur bedrock-runtime. Anthropic::BedrockMantleClient memerlukan gem aws-sdk-core; Anthropic::BedrockClient memerlukan gem aws-sdk-bedrockruntime.
• Claude Platform di AWS: Bagian dari gem utama anthropic (memerlukan gem aws-sdk-core). Menyediakan Anthropic::AWSClient. Berikan workspace_id: ke konstruktor atau atur variabel lingkungan ANTHROPIC_AWS_WORKSPACE_ID (lihat Workspaces). Tersedia dalam versi beta.
• Foundry: Saat ini tidak didukung di SDK Ruby. Lihat Claude di Microsoft Foundry untuk SDK yang didukung.

Gunakan Anthropic::BedrockMantleClient untuk proyek baru; Anthropic::BedrockClient tetap tersedia untuk aplikasi yang sudah ada yang menggunakan API InvokeModel Bedrock.



Semantic versioning

Paket ini mengikuti konvensi SemVer. Karena pustaka ini masih dalam pengembangan awal dan memiliki versi mayor 0, API dapat berubah kapan saja.

Paket ini menganggap peningkatan pada definisi tipe *.rbi dan *.rbs (non-runtime) sebagai perubahan yang tidak merusak (non-breaking).



Sumber daya tambahan

• Repositori GitHub
• Dokumentasi YARD
• Referensi API
• Streaming Messages