SDK Ruby

La libreria Ruby di Anthropic fornisce un accesso comodo alla Claude API da qualsiasi applicazione Ruby 3.2.0+. Include tipi completi e docstring in Yard, RBS e RBI. Come trasporto HTTP viene utilizzato net/http della libreria standard, con "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"
)

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 con accesso a più workspace, imposta l'ID del workspace nell'header di richiesta anthropic-workspace-id; Seleziona un workspace mostra l'opzione per singola richiesta per questo SDK.

Streaming

L'SDK fornisce supporto per le risposte in streaming utilizzando 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 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"
)

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 helper 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",
  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 non di 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"
  )
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 backoff esponenziale.

Gli errori di connessione (ad esempio, a causa di un problema di connettività di rete), 408 Request Timeout, 409 Conflict, 429 Rate Limit, 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",
  request_options: {max_retries: 5}
)

Timeout

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

# 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",
  request_options: {timeout: 5}
)

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

Nota che le richieste che vanno in timeout 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 secondo necessità.
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 lavorare 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 contenuti grezzi, 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)

Nota che puoi anche passare un descrittore IO grezzo, ma questo disabilita i tentativi ripetuti, poiché la libreria non può essere certa se 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"
)

Oppure, in modo equivalente:

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

# Puoi anche espandere con splat una classe Params completa:
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

Poiché questa libreria non dipende da sorbet-runtime, non può fornire istanze di T::Enum. Al loro posto, l'SDK fornisce "tagged symbols" (simboli etichettati), che a runtime sono sempre un tipo primitivo:

# :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:

# L'uso delle costanti enum preserva le informazioni sul tipo con tag:
anthropic.messages.create(
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
  # ...
)

# Sono ammessi anche i valori letterali:
anthropic.messages.create(
  service_tier: :auto,
  # ...
)

BaseModel

Tutti gli oggetti di parametri 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 formato 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 raccomanda di creare il client una sola volta per applicazione.

Quando tutte le connessioni disponibili del 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 a protezione della loro struttura dati sottostante.

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",
    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 extra, 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.

Versionamento semantico

Questo pacchetto segue le convenzioni SemVer.

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

Risorse aggiuntive

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