Ruby SDK

La libreria Ruby di Anthropic fornisce un accesso comodo alla Claude API da qualsiasi applicazione Ruby 3.2.0+. Include tipi e docstring completi in YARD, RBS e RBI. Il net/http della libreria standard viene utilizzato come trasporto HTTP, con il "connection pooling" (pool di connessioni) tramite la gem connection_pool.

Installazione

Aggiungi la gem al Gemfile della tua applicazione con Bundler:

bundle add anthropic

Requisiti

Ruby 3.2.0 o superiore.

Utilizzo

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

Per le opzioni di autenticazione, inclusa la Workload Identity Federation, consulta Autenticazione. Se la tua chiave API è una chiave personale o di account di servizio che non è limitata a un workspace, imposta l'ID del workspace nell'header di richiesta anthropic-workspace-id; Selezionare un workspace mostra l'opzione per singola richiesta per questo SDK.

Streaming

L'SDK fornisce il supporto per le risposte in "streaming" (streaming) utilizzando i "Server-Sent Events" (eventi inviati dal server), o SSE.

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

Helper per lo streaming

Questa libreria fornisce diverse comodità per lo streaming dei messaggi, ad esempio:

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

Lo streaming con anthropic.messages.stream(...) espone vari helper, tra cui l'accumulo e gli eventi specifici dell'SDK.

Schema di input e chiamata degli strumenti

L'SDK fornisce meccanismi di supporto per definire classi di dati strutturati per gli strumenti e consentire a Claude di eseguirli automaticamente. Per la documentazione dettagliata sui pattern di "tool use" (uso degli strumenti), incluso il tool runner, consulta 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

# Gestisce automaticamente il ciclo di esecuzione degli strumenti
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 }

Output strutturati

Per la documentazione completa sugli output strutturati, inclusi esempi in Ruby, consulta Output strutturati.

Gestione degli errori

Quando la libreria non riesce a connettersi all'API, o se l'API restituisce un codice di stato diverso da successo (ovvero una risposta 4xx o 5xx), viene sollevata una sottoclasse di Anthropic::Errors::APIError:

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

I codici di errore sono i seguenti:

Tentativi ripetuti

Alcuni errori vengono ritentati automaticamente 2 volte per impostazione predefinita, con un breve "exponential backoff" (attesa esponenziale).

Gli errori di connessione (ad esempio, a causa di un problema di connettività di rete), 408 Request Timeout, 409 Conflict, 429 Rate Limit, gli errori interni >=500 e i timeout vengono tutti ritentati per impostazione predefinita.

Puoi usare l'opzione max_retries per configurare o disabilitare questo comportamento:

# Configura il valore predefinito per tutte le richieste:
anthropic = Anthropic::Client.new(
  max_retries: 0 # default is 2
)

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

Timeout

Per impostazione predefinita, le richieste scadono dopo 10 minuti. Puoi usare l'opzione timeout per configurare questo comportamento:

# Configura il valore predefinito per tutte le richieste:
anthropic = Anthropic::Client.new(
  timeout: 20 # 20 seconds (default is 10 minutes)
)

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

In caso di timeout, viene sollevato Anthropic::Errors::APITimeoutError.

Tieni presente che le richieste che scadono vengono ritentate per impostazione predefinita.

Paginazione

I metodi di elenco nella Claude API sono paginati.

Questa libreria fornisce iteratori con paginazione automatica per ogni risposta di elenco, così non devi richiedere manualmente le pagine successive:

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

# Recupera un singolo elemento dalla pagina.
batch = page.data[0]
puts(batch.id)

# Recupera automaticamente altre pagine quando necessario.
page.auto_paging_each do |batch|
  puts(batch.id)
end

In alternativa, puoi usare i metodi #next_page? e #next_page per un controllo più granulare nel lavoro con le pagine.

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

Caricamento di file

I parametri di richiesta che corrispondono a caricamenti di file possono essere passati come contenuto grezzo, un'istanza di Pathname, StringIO o altro.

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

# Usa `Pathname` per inviare il nome del file e/o evitare di caricare in memoria un file di grandi dimensioni:
file_metadata = anthropic.files.upload(file: Pathname("/path/to/file"))

# In alternativa, passa direttamente il contenuto del file o uno `StringIO`:
file_metadata = anthropic.files.upload(file: File.read("/path/to/file"))

# Oppure, per controllare il nome del file e/o il tipo di contenuto:
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)

Tieni presente che puoi anche passare un descrittore IO grezzo, ma questo disabilita i tentativi ripetuti, poiché la libreria non può essere certa che il descrittore sia un file o una pipe (che non può essere riavvolta).

Sorbet

Questa libreria fornisce definizioni RBI complete e non ha alcuna dipendenza da sorbet-runtime.

Puoi fornire parametri di richiesta type-safe in questo modo:

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

Oppure, in modo equivalente:

anthropic = Anthropic::Client.new
# Gli hash funzionano, ma non sono typesafe:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5"
)

# Puoi anche fare lo splat di un'intera classe 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)

Enum

Poiché questa libreria non dipende da sorbet-runtime, non può fornire istanze di T::Enum. Invece, l'SDK fornisce dei "tagged symbols" (simboli etichettati), che a runtime sono sempre primitivi:

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

# Tipo rivelato: `T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)`
T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO)

I parametri enum hanno un tipo "rilassato", quindi puoi passare sia le costanti enum sia il loro valore letterale:

anthropic = Anthropic::Client.new
# L'uso delle costanti enum preserva le informazioni sul tipo con tag:
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
)

# Sono ammessi anche valori letterali:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5",
  service_tier: :auto
)

BaseModel

Tutti gli oggetti di parametro e di risposta ereditano da Anthropic::Internal::Type::BaseModel, che fornisce diverse comodità, tra cui:

1. Tutti i campi, inclusi quelli sconosciuti, sono accessibili con la sintassi obj[:prop] e possono essere destrutturati con obj => {prop: prop} o con la sintassi di pattern matching.

2. Equivalenza strutturale per l'uguaglianza. Se due chiamate API restituiscono gli stessi valori, il confronto delle risposte con == restituirà true.

3. Sia le istanze sia le classi stesse possono essere stampate in modo leggibile (pretty-print).

4. Helper come #to_h, #deep_to_h, #to_json e #to_yaml.

Concorrenza e connection pooling

Le istanze di Anthropic::Client sono thread-safe, ma sono fork-safe solo quando non ci sono richieste HTTP in corso.

Ogni istanza di Anthropic::Client ha il proprio pool di connessioni HTTP con una dimensione predefinita di 99. Pertanto, nella maggior parte dei contesti si consiglia di creare il client una sola volta per applicazione.

Quando tutte le connessioni disponibili nel pool sono in uso, le richieste attendono che una nuova connessione diventi disponibile, e il tempo in coda viene conteggiato nel timeout della richiesta.

Salvo diversa indicazione, le altre classi dell'SDK non dispongono di lock che proteggano la loro struttura dati sottostante.

Tracciamento OpenTelemetry

Quando la tua applicazione registra un tracer provider OpenTelemetry, l'SDK emette uno span per ogni richiesta che invia. Per inviare gli span alla tua piattaforma di osservabilità, consulta Configurare OpenTelemetry con il Claude SDK.

Effettuare richieste personalizzate o non documentate

Proprietà non documentate

Puoi inviare parametri non documentati a qualsiasi endpoint e leggere proprietà di risposta non documentate, in questo modo:

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

Parametri di richiesta non documentati

Se vuoi inviare esplicitamente un parametro aggiuntivo, puoi farlo con extra_query, extra_body ed extra_headers all'interno del parametro request_options: quando effettui una richiesta, come mostrato negli esempi precedenti.

Endpoint non documentati

Per effettuare richieste a endpoint non documentati mantenendo i vantaggi di autenticazione, tentativi ripetuti e così via, puoi effettuare richieste usando anthropic.request, in questo modo:

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

Integrazioni con le piattaforme

L'SDK Ruby supporta le seguenti piattaforme:

• Agent Platform: Anthropic::VertexClient. Richiede la gem googleauth.
• Bedrock: Anthropic::BedrockMantleClient, oppure Anthropic::BedrockClient per il percorso bedrock-runtime. Anthropic::BedrockMantleClient richiede la gem aws-sdk-core; Anthropic::BedrockClient richiede la gem aws-sdk-bedrockruntime.
• Claude Platform su AWS: Parte della gem principale anthropic (richiede la gem aws-sdk-core). Fornisce Anthropic::AWSClient. Passa workspace_id: al costruttore oppure imposta la variabile d'ambiente ANTHROPIC_AWS_WORKSPACE_ID (consulta Workspace). Disponibile in beta.
• Foundry: Attualmente non supportato nell'SDK Ruby. Consulta Claude in Microsoft Foundry per gli SDK supportati.

Usa Anthropic::BedrockMantleClient per i nuovi progetti; Anthropic::BedrockClient rimane disponibile per le applicazioni esistenti che utilizzano l'API InvokeModel di Bedrock.

L'SDK Ruby supporta anche Claude Models on Google Cloud (Anthropic managed) tramite Anthropic::GoogleCloudClient. Questo client è in beta. È incluso nella gem principale anthropic e richiede la gem googleauth. Passa workspace_id: al costruttore oppure imposta la variabile d'ambiente ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID. Consulta Risoluzione di progetto, location e workspace per scoprire come il client risolve l'ID del workspace.

Versionamento semantico

Ogni versione major di questo SDK invia per impostazione predefinita una versione dell'API nell'header anthropic-version, e una nuova versione major accompagna ogni nuova versione dell'API. La prima versione major che invia 2026-10-21 è la 2.0.0; consulta Migrazione alla versione API 2026-10-21.

Questo pacchetto segue le convenzioni SemVer.

Questo pacchetto considera i miglioramenti alle definizioni di tipo (non runtime) *.rbi e *.rbs come modifiche non incompatibili.

Risorse aggiuntive

• Repository GitHub
• Documentazione YARD
• Riferimento API
• Streaming dei messaggi