---
title: SDK Ruby
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, helpers 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`.

<Info>
  Para a 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 cobre recursos e configurações do SDK específicos para Ruby.
</Info>

## 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 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) com acesso a vários workspaces, 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 (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
```

### Helpers 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 helpers, incluindo acumulação e eventos específicos do SDK.

## Schema de entrada e chamada de ferramentas

O SDK fornece mecanismos auxiliares para definir classes de dados estruturados para ferramentas e permitir que o 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, uma 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 serão automaticamente repetidos 2 vezes por padrão, com um curto backoff 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

Os 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 tem dependência do sorbet-runtime.

Você pode fornecer parâmetros de requisição com segurança de tipos da seguinte forma:

```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 de `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)
```

Os parâmetros enum têm um tipo "relaxado", então você pode passar tanto constantes enum quanto seu valor literal:

```ruby
anthropic = Anthropic::Client.new
# Usar as constantes enum preserva as informações de 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 legível (pretty-print).

4. Helpers 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 threadsafe, 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 um tamanho padrão de 99. Assim, 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, com o tempo em fila contando para o timeout da requisição.

Salvo indicação em contrário, as outras classes do SDK não possuem locks protegendo sua estrutura de dados subjacente.

## 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, da seguinte forma:

<Warning>
  Os parâmetros `extra_` de mesmo nome sobrescrevem os parâmetros documentados. Por motivos de segurança, garanta que esses métodos sejam usados apenas com dados de entrada confiáveis.
</Warning>

```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 com plataformas

<Note>
  Para guias detalhados de configuração de plataformas 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)
  * [Google Cloud](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-vertex-ai)
</Note>

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 ver os SDKs suportados.

Use `Anthropic::BedrockMantleClient` para novos projetos; `Anthropic::BedrockClient` permanece para aplicações existentes que usam a API `InvokeModel` do Bedrock.

## Versionamento semântico

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` (não usadas em 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)