--- title: Ruby SDK url: https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/sdks/ruby description: Instale e configure o SDK Ruby da Anthropic com tipos Sorbet, auxiliares de streaming e pool de conexões --- A biblioteca Ruby da Anthropic fornece acesso conveniente à Claude API a partir de qualquer aplicação Ruby 3.2.0+. Ela inclui tipos abrangentes e docstrings em YARD, RBS e RBI. O `net/http` da biblioteca padrão é usado como transporte HTTP, com "connection pooling" (pool de conexões) por meio da gem `connection_pool`. Para documentação de recursos da API com exemplos de código, consulte a [referência da API](https://platform.claude.com/docs/pt-BR/api/overview). Esta página aborda recursos e configurações específicos do SDK Ruby. ## Instalação Adicione a gem ao `Gemfile` da sua aplicação com o Bundler: ```bash bundle add anthropic ``` ## Requisitos Ruby 3.2.0 ou superior. ## Uso ```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 ``` Para opções de autenticação, incluindo Workload Identity Federation, consulte [Autenticação](https://platform.claude.com/docs/pt-BR/manage-claude/authentication). Se a sua chave de API for uma [chave pessoal ou de conta de serviço](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#key-types) que não esteja vinculada a um workspace, defina o ID do workspace no cabeçalho de requisição `anthropic-workspace-id`; [Selecionar um workspace](https://platform.claude.com/docs/pt-BR/manage-claude/authentication#select-a-workspace) mostra a opção por requisição para este SDK. ## Streaming O SDK oferece suporte a respostas em "streaming" (streaming) usando "Server-Sent Events" (eventos enviados pelo servidor), ou 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 ``` ### Auxiliares de streaming Esta biblioteca fornece várias conveniências para streaming de mensagens, por exemplo: ```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 ``` O streaming com `anthropic.messages.stream(...)` expõe vários auxiliares, incluindo acumulação e eventos específicos do SDK. ## Esquema de entrada e chamada de ferramentas O SDK fornece mecanismos auxiliares para definir classes de dados estruturados para ferramentas e permitir que Claude as execute automaticamente. Para documentação detalhada sobre padrões de "tool use" (uso de ferramentas), incluindo o tool runner, consulte [Tool Runner (SDK)](https://platform.claude.com/docs/pt-BR/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 # Gerencia automaticamente o loop de execução de ferramentas 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 } ``` ## Saídas estruturadas Para a documentação completa de saídas estruturadas, incluindo exemplos em Ruby, consulte [Saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs). ## Tratamento de erros Quando a biblioteca não consegue se conectar à API, ou se a API retorna um código de status que não indica sucesso (ou seja, resposta 4xx ou 5xx), uma subclasse de `Anthropic::Errors::APIError` é lançada: ```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 ``` Os códigos de erro são os seguintes: | Causa | Tipo de erro | | --------------- | -------------------------- | | HTTP 400 | `BadRequestError` | | HTTP 401 | `AuthenticationError` | | HTTP 403 | `PermissionDeniedError` | | HTTP 404 | `NotFoundError` | | HTTP 409 | `ConflictError` | | HTTP 422 | `UnprocessableEntityError` | | HTTP 429 | `RateLimitError` | | HTTP >= 500 | `InternalServerError` | | Outro erro HTTP | `APIStatusError` | | Timeout | `APITimeoutError` | | Erro de rede | `APIConnectionError` | ## Novas tentativas Certos erros são automaticamente repetidos 2 vezes por padrão, com um breve "exponential backoff" (recuo exponencial). Erros de conexão (por exemplo, devido a um problema de conectividade de rede), 408 Request Timeout, 409 Conflict, 429 Rate Limit, erros internos >=500 e timeouts são todos repetidos por padrão. Você pode usar a opção `max_retries` para configurar ou desativar isso: ```ruby # Configure o padrão para todas as requisições: anthropic = Anthropic::Client.new( max_retries: 0 # default is 2 ) # Ou configure por requisição: anthropic.messages.create( max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}], model: :"claude-opus-5-5", request_options: {max_retries: 5} ) ``` ## Timeouts Por padrão, as requisições expiram após 10 minutos. Você pode usar a opção `timeout` para configurar isso: ```ruby # Configure o padrão para todas as requisições: anthropic = Anthropic::Client.new( timeout: 20 # 20 seconds (default is 10 minutes) ) # Ou configure por requisição: anthropic.messages.create( max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}], model: :"claude-opus-5-5", request_options: {timeout: 5} ) ``` Em caso de timeout, `Anthropic::Errors::APITimeoutError` é lançado. Observe que as requisições que expiram são repetidas por padrão. ## Paginação Os métodos de listagem na Claude API são paginados. Esta biblioteca fornece iteradores com paginação automática em cada resposta de listagem, para que você não precise solicitar páginas sucessivas manualmente: ```ruby anthropic = Anthropic::Client.new page = anthropic.messages.batches.list(limit: 20) # Busca um único item da página. batch = page.data[0] puts(batch.id) # Busca automaticamente mais páginas conforme necessário. page.auto_paging_each do |batch| puts(batch.id) end ``` Alternativamente, você pode usar os métodos `#next_page?` e `#next_page` para um controle mais granular ao trabalhar com páginas. ```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 ``` ## Upload de arquivos Parâmetros de requisição que correspondem a uploads de arquivos podem ser passados como conteúdo bruto, uma instância de [`Pathname`](https://rubyapi.org/3.2/o/pathname), [`StringIO`](https://rubyapi.org/3.2/o/stringio) ou outros. ```ruby anthropic = Anthropic::Client.new require "pathname" # Use `Pathname` para enviar o nome do arquivo e/ou evitar carregar um arquivo grande na memória: file_metadata = anthropic.files.upload(file: Pathname("/path/to/file")) # Como alternativa, passe o conteúdo do arquivo ou um `StringIO` diretamente: file_metadata = anthropic.files.upload(file: File.read("/path/to/file")) # Ou, para controlar o nome do arquivo e/ou o tipo de conteúdo: 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) ``` Observe que você também pode passar um descritor `IO` bruto, mas isso desativa as novas tentativas, pois a biblioteca não pode ter certeza se o descritor é um arquivo ou um pipe (que não pode ser rebobinado). ## Sorbet Esta biblioteca fornece definições [RBI](https://sorbet.org/docs/rbi) abrangentes e não depende do sorbet-runtime. Você pode fornecer parâmetros de requisição com segurança de tipos assim: ```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" ) ``` Ou, de forma equivalente: ```ruby anthropic = Anthropic::Client.new # Hashes funcionam, mas não são typesafe: anthropic.messages.create( max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}], model: :"claude-opus-5-5" ) # Você também pode fazer splat de uma classe Params completa: 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) ``` ### Enums Como esta biblioteca não depende do `sorbet-runtime`, ela não pode fornecer instâncias de [`T::Enum`](https://sorbet.org/docs/tenum). Em vez disso, o SDK fornece "tagged symbols" (símbolos marcados), que são sempre primitivos em tempo de execução: ```ruby # :auto puts(Anthropic::MessageCreateParams::ServiceTier::AUTO) # Tipo revelado: `T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)` T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO) ``` Parâmetros de enum têm um tipo "relaxado", então você pode passar constantes de enum ou seu valor literal: ```ruby anthropic = Anthropic::Client.new # Usar as constantes do enum preserva as informações do tipo marcado: 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 ) # Valores literais também são permitidos: anthropic.messages.create( max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}], model: :"claude-opus-5-5", service_tier: :auto ) ``` ## BaseModel Todos os objetos de parâmetro e de resposta herdam de `Anthropic::Internal::Type::BaseModel`, que fornece várias conveniências, incluindo: 1. Todos os campos, incluindo os desconhecidos, são acessíveis com a sintaxe `obj[:prop]` e podem ser desestruturados com `obj => {prop: prop}` ou com a sintaxe de pattern matching. 2. Equivalência estrutural para igualdade. Se duas chamadas de API retornarem os mesmos valores, comparar as respostas com == retornará true. 3. Tanto as instâncias quanto as próprias classes podem ser impressas de forma formatada (pretty-print). 4. Auxiliares como `#to_h`, `#deep_to_h`, `#to_json` e `#to_yaml`. ## Concorrência e pool de conexões As instâncias de `Anthropic::Client` são thread-safe, mas só são fork-safe quando não há requisições HTTP em andamento. Cada instância de `Anthropic::Client` tem seu próprio pool de conexões HTTP com tamanho padrão de 99. Por isso, a recomendação é criar o cliente uma vez por aplicação na maioria dos cenários. Quando todas as conexões disponíveis do pool estão em uso, as requisições aguardam até que uma nova conexão fique disponível, e o tempo na fila conta para o timeout da requisição. Salvo indicação em contrário, outras classes do SDK não possuem locks protegendo sua estrutura de dados subjacente. ## Tracing do OpenTelemetry Quando a sua aplicação registra um tracer provider do OpenTelemetry, o SDK emite um span para cada requisição que envia. Para enviar os spans para a sua plataforma de observabilidade, consulte [Configurar o OpenTelemetry com o Claude SDK](https://platform.claude.com/docs/pt-BR/manage-claude/opentelemetry/sdk). ## Fazendo requisições personalizadas ou não documentadas ### Propriedades não documentadas Você pode enviar parâmetros não documentados para qualquer endpoint e ler propriedades de resposta não documentadas, assim: Os parâmetros `extra_` de mesmo nome substituem os parâmetros documentados. Por motivos de segurança, garanta que esses métodos sejam usados apenas com dados de entrada confiáveis. ```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]) ``` ### Parâmetros de requisição não documentados Se você quiser enviar explicitamente um parâmetro extra, pode fazê-lo com `extra_query`, `extra_body` e `extra_headers` no parâmetro `request_options:` ao fazer uma requisição, como visto nos exemplos anteriores. ### Endpoints não documentados Para fazer requisições a endpoints não documentados mantendo os benefícios de autenticação, novas tentativas e assim por diante, você pode fazer requisições usando `anthropic.request`, assim: ```ruby response = anthropic.request( method: :post, path: '/undocumented/endpoint', query: {"dog": "woof"}, headers: {"useful-header": "interesting-value"}, body: {"hello": "world"} ) ``` ## Integrações de plataforma Para guias detalhados de configuração de plataforma com exemplos de código, consulte: * [Amazon Bedrock](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-amazon-bedrock) * [Amazon Bedrock (Opus 4.6 e anteriores)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-amazon-bedrock-legacy) * [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws) * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/google-managed) Consulte também [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed). O SDK Ruby oferece suporte às seguintes plataformas: * **Agent Platform:** `Anthropic::VertexClient`. Requer a gem `googleauth`. * **Bedrock:** `Anthropic::BedrockMantleClient`, ou `Anthropic::BedrockClient` para o caminho `bedrock-runtime`. `Anthropic::BedrockMantleClient` requer a gem `aws-sdk-core`; `Anthropic::BedrockClient` requer a gem `aws-sdk-bedrockruntime`. * **Claude Platform on AWS:** Parte da gem principal `anthropic` (requer a gem `aws-sdk-core`). Fornece `Anthropic::AWSClient`. Passe `workspace_id:` para o construtor ou defina a variável de ambiente `ANTHROPIC_AWS_WORKSPACE_ID` (consulte [Workspaces](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws#workspaces)). Disponível em beta. * **Foundry:** Atualmente não suportado no SDK Ruby. Consulte [Claude no Microsoft Foundry](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-microsoft-foundry) para os SDKs suportados. Use `Anthropic::BedrockMantleClient` para novos projetos; `Anthropic::BedrockClient` permanece para aplicações existentes que usam a API `InvokeModel` do Bedrock. O SDK Ruby também oferece suporte a Claude Models on Google Cloud (Anthropic managed) por meio de `Anthropic::GoogleCloudClient`. Este cliente está em beta. Ele é distribuído na gem principal `anthropic` e requer a gem `googleauth`. Passe `workspace_id:` para o construtor ou defina a variável de ambiente `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`. Consulte [Resolução de projeto, localização e workspace](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution) para saber como o cliente resolve o ID do workspace. ## Versionamento semântico Cada versão principal deste SDK envia uma versão da API no cabeçalho `anthropic-version` por padrão, e uma nova versão principal acompanha cada nova versão da API. A primeira versão principal que envia `2026-10-21` é a 2.0.0; consulte [Migrando para a versão da API 2026-10-21](https://platform.claude.com/docs/pt-BR/api/migration-2026-10-21#upgrade). Este pacote segue as convenções do [SemVer](https://semver.org/spec/v2.0.0.html). Este pacote considera melhorias nas definições de tipo `*.rbi` e `*.rbs` (que não são de tempo de execução) como alterações que não quebram compatibilidade. ## Recursos adicionais * [Repositório no GitHub](https://github.com/anthropics/anthropic-sdk-ruby) * [Documentação YARD](https://gemdocs.org/gems/anthropic) * [Referência da API](https://platform.claude.com/docs/pt-BR/api/overview) * [Streaming de mensagens](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming)