SDK de Ruby

La biblioteca de Ruby de Anthropic proporciona acceso conveniente a la API REST de Anthropic desde cualquier aplicación Ruby 3.2.0+. Incluye tipos completos y docstrings en Yard, RBS y RBI. Se utiliza net/http de la biblioteca estándar como transporte HTTP, con agrupación de conexiones a través de la gema connection_pool.



Instalación

Agrega la gema al Gemfile de tu aplicación con Bundler:

bundle add anthropic



Requisitos

Ruby 3.2.0 o 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 conocer las opciones de autenticación, incluida Workload Identity Federation, consulta Autenticación.



Streaming

El SDK proporciona soporte para respuestas en streaming usando "Server-Sent Events" (eventos enviados por el servidor), o 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 proporciona varias utilidades para el streaming de mensajes, por ejemplo:

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

El streaming con anthropic.messages.stream(...) expone varios helpers, incluyendo acumulación y eventos específicos del SDK.



Esquema de entrada y llamadas a herramientas

El SDK proporciona mecanismos auxiliares para definir clases de datos estructurados para herramientas y permitir que Claude las ejecute automáticamente. Para documentación detallada sobre patrones de uso de herramientas, incluyendo el tool runner, consulta 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

# Maneja automáticamente el bucle de ejecución de herramientas
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 }



Salidas estructuradas

Para documentación completa sobre salidas estructuradas, incluyendo ejemplos en Ruby, consulta Salidas estructuradas.



Manejo de errores

Cuando la biblioteca no puede conectarse a la API, o si la API devuelve un código de estado no exitoso (es decir, una respuesta 4xx o 5xx), se lanza una subclase de Anthropic::Errors::APIError:

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

Los códigos de error son los siguientes:



Reintentos

Ciertos errores se reintentarán automáticamente 2 veces de forma predeterminada, con un breve retroceso exponencial.

Los errores de conexión (por ejemplo, debido a un problema de conectividad de red), 408 Request Timeout, 409 Conflict, 429 Rate Limit, errores internos >=500 y tiempos de espera agotados se reintentan de forma predeterminada.

Puedes usar la opción max_retries para configurar o deshabilitar esto:

# Configura el valor predeterminado para todas las solicitudes:
anthropic = Anthropic::Client.new(
  max_retries: 0 # default is 2
)

# O bien, configura por solicitud:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5",
  request_options: {max_retries: 5}
)



Tiempos de espera

De forma predeterminada, las solicitudes agotan el tiempo de espera después de 10 minutos. Puedes usar la opción timeout para configurar esto:

# Configura el valor predeterminado para todas las solicitudes:
anthropic = Anthropic::Client.new(
  timeout: 20 # 20 seconds (default is 10 minutes)
)

# O bien, configura por solicitud:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5",
  request_options: {timeout: 5}
)

Cuando se agota el tiempo de espera, se lanza Anthropic::Errors::APITimeoutError.

Ten en cuenta que las solicitudes que agotan el tiempo de espera se reintentan de forma predeterminada.



Paginación

Los métodos de listado en la API de Claude están paginados.

Esta biblioteca proporciona iteradores de paginación automática con cada respuesta de listado, por lo que no tienes que solicitar páginas sucesivas manualmente:

anthropic = Anthropic::Client.new
page = anthropic.messages.batches.list(limit: 20)

# Obtener un solo elemento de la página.
batch = page.data[0]
puts(batch.id)

# Obtiene automáticamente más páginas según sea necesario.
page.auto_paging_each do |batch|
  puts(batch.id)
end

Alternativamente, puedes usar los métodos #next_page? y #next_page para un control más granular al trabajar con 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



Carga de archivos

Los parámetros de solicitud que corresponden a cargas de archivos se pueden pasar como contenido sin procesar, una instancia de Pathname, StringIO, o más.

anthropic = Anthropic::Client.new
require "pathname"

# Usa `Pathname` para enviar el nombre de archivo y/o evitar cargar un archivo grande en memoria:
file_metadata = anthropic.beta.files.upload(file: Pathname("/path/to/file"))

# Alternativamente, pasa el contenido del archivo o un `StringIO` directamente:
file_metadata = anthropic.beta.files.upload(file: File.read("/path/to/file"))

# O bien, para controlar el nombre de archivo y/o el tipo de contenido:
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)

Ten en cuenta que también puedes pasar un descriptor IO sin procesar, pero esto deshabilita los reintentos, ya que la biblioteca no puede estar segura de si el descriptor es un archivo o una tubería (que no se puede rebobinar).



Sorbet

Esta biblioteca proporciona definiciones RBI completas y no tiene dependencia de sorbet-runtime.

Puedes proporcionar parámetros de solicitud con seguridad de tipos de la siguiente manera:

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

O, de forma equivalente:

anthropic = Anthropic::Client.new
# Los hashes funcionan, pero no son seguros en cuanto a tipos:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5"
)

# También puedes expandir (splat) una clase 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

Dado que esta biblioteca no depende de sorbet-runtime, no puede proporcionar instancias de T::Enum. En su lugar, el SDK proporciona "tagged symbols" (símbolos etiquetados), que siempre son un primitivo en tiempo de ejecución:

# :auto
puts(Anthropic::MessageCreateParams::ServiceTier::AUTO)

# Tipo revelado: `T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)`
T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO)

Los parámetros de enum tienen un tipo "relajado", por lo que puedes pasar constantes de enum o su valor literal:

# Usar las constantes de enumeración preserva la información de tipo etiquetado:
anthropic.messages.create(
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
  # ...
)

# Los valores literales también son admisibles:
anthropic.messages.create(
  service_tier: :auto,
  # ...
)



BaseModel

Todos los objetos de parámetros y respuestas heredan de Anthropic::Internal::Type::BaseModel, que proporciona varias utilidades, incluyendo:

1. Todos los campos, incluidos los desconocidos, son accesibles con la sintaxis obj[:prop], y se pueden desestructurar con obj => {prop: prop} o sintaxis de pattern-matching.

2. Equivalencia estructural para la igualdad; si dos llamadas a la API devuelven los mismos valores, comparar las respuestas con == devolverá true.

3. Tanto las instancias como las clases mismas se pueden imprimir de forma legible (pretty-print).

4. Helpers como #to_h, #deep_to_h, #to_json y #to_yaml.



Concurrencia y agrupación de conexiones

Las instancias de Anthropic::Client son seguras para hilos (threadsafe), pero solo son seguras para fork cuando no hay solicitudes HTTP en curso.

Cada instancia de Anthropic::Client tiene su propio pool de conexiones HTTP con un tamaño predeterminado de 99. Por lo tanto, la recomendación es crear el cliente una vez por aplicación en la mayoría de los casos.

Cuando todas las conexiones disponibles del pool están en uso, las solicitudes esperan a que una nueva conexión esté disponible, y el tiempo en cola cuenta para el tiempo de espera de la solicitud.

A menos que se especifique lo contrario, otras clases del SDK no tienen bloqueos que protejan su estructura de datos subyacente.



Realizar solicitudes personalizadas o no documentadas



Propiedades no documentadas

Puedes enviar parámetros no documentados a cualquier endpoint y leer propiedades de respuesta no documentadas, de la siguiente manera:

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 solicitud no documentados

Si deseas enviar explícitamente un parámetro adicional, puedes hacerlo con extra_query, extra_body y extra_headers bajo el parámetro request_options: al realizar una solicitud, como se ve en los ejemplos anteriores.



Endpoints no documentados

Para realizar solicitudes a endpoints no documentados conservando el beneficio de autenticación, reintentos, etc., puedes realizar solicitudes usando anthropic.request, de la siguiente manera:

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



Integraciones de plataforma

El SDK de Ruby admite las siguientes plataformas:

• Agent Platform: Anthropic::VertexClient. Requiere la gema googleauth.
• Bedrock: Anthropic::BedrockMantleClient, o Anthropic::BedrockClient para la ruta bedrock-runtime. Anthropic::BedrockMantleClient requiere la gema aws-sdk-core; Anthropic::BedrockClient requiere la gema aws-sdk-bedrockruntime.
• Claude Platform en AWS: Parte de la gema principal anthropic (requiere la gema aws-sdk-core). Proporciona Anthropic::AWSClient. Pasa workspace_id: al constructor o establece la variable de entorno ANTHROPIC_AWS_WORKSPACE_ID (consulta Workspaces). Disponible en beta.
• Foundry: Actualmente no compatible con el SDK de Ruby. Consulta Claude en Microsoft Foundry para ver los SDK compatibles.

Usa Anthropic::BedrockMantleClient para proyectos nuevos; Anthropic::BedrockClient se mantiene para aplicaciones existentes que usan la API InvokeModel de Bedrock.



Versionado semántico

Este paquete sigue las convenciones de SemVer.

Este paquete considera que las mejoras a las definiciones de tipos *.rbi y *.rbs (que no son de tiempo de ejecución) son cambios no disruptivos.



Recursos adicionales

• Repositorio de GitHub
• Documentación de YARD
• Referencia de la API
• Streaming de mensajes