--- title: Ruby SDK url: https://platform.claude.com/docs/it/cli-sdks-libraries/sdks/ruby description: Installa e configura l'SDK Ruby di Anthropic con tipi Sorbet, helper per lo streaming e connection pooling --- 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`. Per la documentazione delle funzionalità dell'API con esempi di codice, consulta il [riferimento API](https://platform.claude.com/docs/it/api/overview). Questa pagina tratta le funzionalità e la configurazione specifiche dell'SDK Ruby. ## Installazione Aggiungi la gem al `Gemfile` della tua applicazione con Bundler: ```bash bundle add anthropic ``` ## Requisiti Ruby 3.2.0 o superiore. ## Utilizzo ```ruby 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](https://platform.claude.com/docs/it/manage-claude/authentication). Se la tua chiave API è una [chiave personale o di account di servizio](https://platform.claude.com/docs/it/manage-claude/authentication#key-types) che non è limitata a un workspace, imposta l'ID del workspace nell'header di richiesta `anthropic-workspace-id`; [Selezionare un workspace](https://platform.claude.com/docs/it/manage-claude/authentication#select-a-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. ```ruby 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: ```ruby 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)](https://platform.claude.com/docs/it/agents-and-tools/tool-use/tool-runner). ```ruby 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](https://platform.claude.com/docs/it/build-with-claude/structured-outputs). ## 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`: ```ruby 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: | Causa | Tipo di errore | | ----------------- | -------------------------- | | HTTP 400 | `BadRequestError` | | HTTP 401 | `AuthenticationError` | | HTTP 403 | `PermissionDeniedError` | | HTTP 404 | `NotFoundError` | | HTTP 409 | `ConflictError` | | HTTP 422 | `UnprocessableEntityError` | | HTTP 429 | `RateLimitError` | | HTTP >= 500 | `InternalServerError` | | Altro errore HTTP | `APIStatusError` | | Timeout | `APITimeoutError` | | Errore di rete | `APIConnectionError` | ## 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: ```ruby # 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: ```ruby # 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: ```ruby 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. ```ruby 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`](https://rubyapi.org/3.2/o/pathname), [`StringIO`](https://rubyapi.org/3.2/o/stringio) o altro. ```ruby 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](https://sorbet.org/docs/rbi) complete e non ha alcuna dipendenza da sorbet-runtime. Puoi fornire parametri di richiesta type-safe in questo modo: ```ruby 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: ```ruby 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`](https://sorbet.org/docs/tenum). Invece, l'SDK fornisce dei "tagged symbols" (simboli etichettati), che a runtime sono sempre primitivi: ```ruby # :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: ```ruby 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](https://platform.claude.com/docs/it/manage-claude/opentelemetry/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: I parametri `extra_` con lo stesso nome sovrascrivono i parametri documentati. Per motivi di sicurezza, assicurati che questi metodi vengano utilizzati solo con dati di input attendibili. ```ruby 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: ```ruby response = anthropic.request( method: :post, path: '/undocumented/endpoint', query: {"dog": "woof"}, headers: {"useful-header": "interesting-value"}, body: {"hello": "world"} ) ``` ## Integrazioni con le piattaforme Per guide dettagliate alla configurazione delle piattaforme con esempi di codice, consulta: * [Amazon Bedrock](https://platform.claude.com/docs/it/build-with-claude/claude-in-amazon-bedrock) * [Amazon Bedrock (Opus 4.6 e precedenti)](https://platform.claude.com/docs/it/build-with-claude/claude-on-amazon-bedrock-legacy) * [Claude Platform su AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws) * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/google-managed) Consulta anche [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed). 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](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws#workspaces)). Disponibile in beta. * **Foundry:** Attualmente non supportato nell'SDK Ruby. Consulta [Claude in Microsoft Foundry](https://platform.claude.com/docs/it/build-with-claude/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](https://platform.claude.com/docs/it/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution) 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](https://platform.claude.com/docs/it/api/migration-2026-10-21#upgrade). Questo pacchetto segue le convenzioni [SemVer](https://semver.org/spec/v2.0.0.html). Questo pacchetto considera i miglioramenti alle definizioni di tipo (non runtime) `*.rbi` e `*.rbs` come modifiche non incompatibili. ## Risorse aggiuntive * [Repository GitHub](https://github.com/anthropics/anthropic-sdk-ruby) * [Documentazione YARD](https://gemdocs.org/gems/anthropic) * [Riferimento API](https://platform.claude.com/docs/it/api/overview) * [Streaming dei messaggi](https://platform.claude.com/docs/it/build-with-claude/streaming)