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 inclui tipos abrangentes e docstrings em Yard, RBS e RBI. O net/http da biblioteca padrão é usado como transporte HTTP, com 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-4-8"
)

puts(message.content)

Para opções de autenticação, incluindo Workload Identity Federation, consulte Autenticação.

Streaming

O SDK oferece suporte para respostas em streaming usando "Server-Sent Events" (eventos enviados pelo servidor), ou SSE.

anthropic = Anthropic::Client.new
stream = anthropic.messages.stream(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-4-8"
)

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

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.

Input schema 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 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

# Gerencia automaticamente o loop de execução de ferramentas
anthropic.beta.messages.tool_runner(
  model: "claude-opus-4-8",
  max_tokens: 1024,
  messages: [{role: "user", content: "What's 15 * 7?"}],
  tools: [Calculator.new]
).each_message { |message| puts message.content }

Saídas estruturadas

Para documentação completa sobre 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-4-8"
  )
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 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-4-8",
  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-4-8",
  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 de paginação automática com cada resposta de lista, 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, entre 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.beta.files.upload(file: Pathname("/path/to/file"))

# Como alternativa, 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 tem como saber 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-4-8"
)

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

# 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-4-8"
)
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 primitivos 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 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 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 impressas de forma legível (pretty-printed).

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ó 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 de fila contando para o timeout da requisição.

A menos que especificado de outra forma, 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, 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-4-8",
    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 o benefício 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 de plataforma

O SDK Ruby suporta as seguintes plataformas:

• 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.
• Vertex AI: Anthropic::VertexClient. Requer a gem googleauth.
• Foundry: Atualmente não suportado no SDK Ruby. Consulte Claude no Microsoft Foundry para SDKs suportados.
• 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.

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 *.rbi e *.rbs (não de tempo de execução) como mudanças não disruptivas.

Recursos adicionais

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