SDK Ruby

La libreria Ruby di Anthropic fornisce un accesso pratico alla REST API di Anthropic 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-4-8"
)

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.



Streaming

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

stream.each do |message|
  puts(message.type)
end



Helper per lo streaming

Questa libreria fornisce diverse funzionalità di convenienza 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-4-8"
)

stream.text.each do |text|
  print(text)
end

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



Schema di input e chiamata di 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 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-4-8",
  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 di errore (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-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

I codici di errore sono i seguenti:



Tentativi di ripetizione

Alcuni errori verranno 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-4-8",
  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-4-8",
  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 nell'API di Claude sono paginati.

Questa libreria fornisce iteratori con paginazione automatica per ogni risposta di elenco, quindi non è necessario richiedere manualmente le pagine successive:

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

# Fetch single item from page.
batch = page.data[0]
puts(batch.id)

# Automatically fetches more pages as needed.
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 nella gestione delle 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 un file di grandi dimensioni in memoria:
file_metadata = anthropic.beta.files.upload(file: Pathname("/path/to/file"))

# In alternativa, passa direttamente il contenuto del file o uno `StringIO`:
file_metadata = anthropic.beta.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.beta.files.upload(file: file)

puts(file_metadata.id)

Nota che puoi anche passare un descrittore IO grezzo, ma questo disabilita i tentativi di ripetizione, poiché la libreria non può determinare se il descrittore è 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 typesafe 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-4-8"
)

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-4-8"
)

# Puoi anche espandere con splat un'intera classe 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

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

# :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 che il loro valore letterale:

# L'uso delle costanti enum preserva le informazioni sul tipo taggato:
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 parametro e risposta ereditano da Anthropic::Internal::Type::BaseModel, che fornisce diverse funzionalità di convenienza, 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 che 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 del pool sono in uso, le richieste attendono che una nuova connessione diventi disponibile, e il tempo di attesa 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-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])



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 di ripetizione 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:

• 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.
• Agent Platform: Anthropic::VertexClient. Richiede la gem googleauth.
• Foundry: Attualmente non supportato nell'SDK Ruby. Consulta Claude in Microsoft Foundry per gli SDK supportati.
• Claude Platform su AWS: Parte della gem principale anthropic (richiede la gem aws-sdk-core). Fornisce Anthropic::AWSClient. Passa workspace_id: al costruttore o imposta la variabile d'ambiente ANTHROPIC_AWS_WORKSPACE_ID (consulta Workspace). Disponibile in beta.

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. Poiché la libreria è in fase di sviluppo iniziale e ha una versione major pari a 0, le API possono cambiare in qualsiasi momento.

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



Risorse aggiuntive

• Repository GitHub
• Documentazione YARD
• Riferimento API
• Messaggi in streaming