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

puts(message.content)

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 (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à utili 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 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-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 automaticamente ritentati 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 utilizzare 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 utilizzare 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, 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 utilizzare 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ò sapere 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 una classe Params completa:
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. Invece, l'SDK fornisce "tagged symbols", 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à utili, 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-printed).

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 hanno lock che proteggono la 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 sopra.

Endpoint non documentati

Per effettuare richieste a endpoint non documentati mantenendo i vantaggi di autenticazione, tentativi di ripetizione e così via, puoi effettuare richieste utilizzando 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.
• Vertex AI: 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 al costruttore o imposta la variabile d'ambiente (consulta ). 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 runtime) come modifiche non breaking.

Risorse aggiuntive

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