SDK Ruby

A biblioteca Ruby da Anthropic fornece acesso conveniente à API REST da Anthropic 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) através 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.



Streaming

O SDK fornece suporte para respostas em 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 Claude as execute automaticamente. Para documentação detalhada sobre padrões de 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 de não sucesso (ou seja, 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 "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 desabilitar 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 requisições que expiram são repetidas por padrão.



Paginação

Os métodos de listagem na API do Claude 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

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 mais.

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.beta.files.upload(file: Pathname("/path/to/file"))

# Alternativamente, passe o conteúdo do arquivo ou um `StringIO` diretamente:
file_metadata = anthropic.beta.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.beta.files.upload(file: file)

puts(file_metadata.id)

Observe que você também pode passar um descritor IO bruto, mas isso desabilita 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 de sorbet-runtime.

Você pode fornecer parâmetros de requisição com tipagem segura assim:

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 são typesafe:
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 de 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)

Parâmetros de enum têm um tipo "relaxado", então você pode passar constantes de enum ou seu valor literal:

# Usar as constantes do enum preserva as informações do tipo tagueado:
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 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 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 exibidas com 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 thread-safe, mas são fork-safe apenas 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. Sendo 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 que uma nova conexão fique disponível, com o tempo de fila contando para o timeout da requisição.

Salvo indicação em contrário, outras classes no 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, assim:

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 dentro do 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 o benefício de autenticação, novas tentativas e assim por diante, você pode fazer requisições usando anthropic.request, assim:

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



Integrações de plataforma

O SDK Ruby suporta as 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 na 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 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. Como a biblioteca está em desenvolvimento inicial e tem uma versão principal 0, as APIs podem mudar a qualquer momento.

Este pacote considera melhorias nas definições de tipo (não de runtime) *.rbi e *.rbs como mudanças não disruptivas.



Recursos adicionais

• Repositório no GitHub
• Documentação YARD
• Referência da API
• Streaming de Mensagens