SDK Ruby

A biblioteca Ruby da Anthropic fornece acesso conveniente à Claude API a partir de qualquer aplicação Ruby 3.2.0+. Ela vem com 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.

Instalação

Adicione a gem ao Gemfile da sua aplicação com o Bundler:

bundle add anthropic

Requisitos

Ruby 3.2.0 ou superior.

Uso

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

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. Se sua chave de API for uma chave pessoal ou de conta de serviço com acesso a vários workspaces, defina o ID do workspace no cabeçalho de requisição anthropic-workspace-id; Selecionar um 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).

anthropic = Anthropic::Client.new
stream = anthropic.messages.stream(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-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:

anthropic = Anthropic::Client.new
stream = anthropic.messages.stream(
  max_tokens: 1024,
  messages: [{role: :user, content: "Say hello there!"}],
  model: :"claude-opus-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).

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

# Lida automaticamente com o loop de execução de ferramentas
anthropic.beta.messages.tool_runner(
  model: "claude-opus-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.

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:

anthropic = Anthropic::Client.new
begin
  message = anthropic.messages.create(
    max_tokens: 1024,
    messages: [{role: "user", content: "Hello, Claude"}],
    model: :"claude-opus-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:

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:

# 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",
  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:

# 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",
  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:

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.

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, StringIO ou outros.

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 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:

anthropic = Anthropic::Client.new
anthropic.messages.create(
  max_tokens: 1024,
  messages: [Anthropic::MessageParam.new(role: "user", content: "Hello, Claude")],
  model: :"claude-opus-5"
)

Ou, de forma equivalente:

anthropic = Anthropic::Client.new
# Hashes funcionam, mas não têm segurança de tipos:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-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"
)
anthropic.messages.create(**params)

Enums

Como esta biblioteca não depende do sorbet-runtime, ela não pode fornecer instâncias de T::Enum. Em vez disso, o SDK fornece "tagged symbols" (símbolos marcados), que são sempre um primitivo em tempo de execução:

# :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:

# Usar as constantes enum preserva as informações de tipo marcado:
anthropic.messages.create(
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
  # ...
)

# Valores literais também são permitidos:
anthropic.messages.create(
  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:

anthropic = Anthropic::Client.new
value = "example"
message =
  anthropic.messages.create(
    max_tokens: 1024,
    messages: [{role: "user", content: "Hello, Claude"}],
    model: :"claude-opus-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 sob o parâmetro request_options: ao fazer uma requisição, como visto nos exemplos acima.

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

response = anthropic.request(
  method: :post,
  path: '/undocumented/endpoint',
  query: {"dog": "woof"},
  headers: {"useful-header": "interesting-value"},
  body: {"hello": "world"}
)

Integrações com plataformas

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). Disponível em beta.
• Foundry: Atualmente não suportado no SDK Ruby. Consulte Claude no 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.

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
• Documentação YARD
• Referência da API
• Streaming de mensagens