--- title: SDK Ruby 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. Come trasporto HTTP viene utilizzato `net/http` della libreria standard, con "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 dell'SDK specifiche per 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) con accesso a più workspace, imposta l'ID del workspace nell'header di richiesta `anthropic-workspace-id`; [Seleziona 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 supporto per le risposte in streaming utilizzando Server-Sent Events (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 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)](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 non di 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 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: ```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 vanno in timeout dopo 10 minuti. Puoi usare l'opzione `timeout` per configurare questo valore: ```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`. 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: ```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 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. ```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 contenuti grezzi, 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) ``` 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](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 "tagged symbols" (simboli etichettati), che a runtime sono sempre tipi 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 i 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 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: I parametri `extra_` con lo stesso nome sovrascrivono i parametri documentati. Per motivi di sicurezza, assicurati che questi metodi vengano usati 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) * [Google Cloud](https://platform.claude.com/docs/it/build-with-claude/claude-on-vertex-ai) 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. ## Versionamento semantico Questo pacchetto segue le convenzioni [SemVer](https://semver.org/spec/v2.0.0.html). Questo pacchetto considera i miglioramenti alle definizioni di tipo `*.rbi` e `*.rbs` (non runtime) come modifiche non distruttive. ## 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)