SDK de Ruby

La biblioteca de Ruby de Anthropic proporciona un acceso conveniente a la Claude API desde cualquier aplicación con 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 "connection pooling" (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. Si tu clave de API es una clave personal o de cuenta de servicio con acceso a múltiples espacios de trabajo, establece el ID del espacio de trabajo en el encabezado de solicitud anthropic-workspace-id; Seleccionar un espacio de trabajo muestra la opción por solicitud para este SDK.

Streaming

El SDK proporciona soporte para respuestas en streaming mediante "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 comodidades 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 llamada de herramientas

El SDK proporciona mecanismos auxiliares para definir clases de datos estructurados para herramientas y permitir que Claude las ejecute automáticamente. Para obtener documentación detallada sobre los patrones de "tool use" (uso de herramientas), incluido 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 la documentación completa de salidas estructuradas, incluidos 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 reintentan 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 los tiempos de espera agotados se reintentan todos 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, configúralo 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 su 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, configúralo 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 su tiempo de espera se reintentan de forma predeterminada.

Paginación

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

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

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

# Obtiene 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 pueden pasarse como contenido sin procesar, una instancia de Pathname, StringIO, y 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.files.upload(file: Pathname("/path/to/file"))

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

# O, 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.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 un pipe (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 tienen seguridad de tipos:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5"
)

# También puedes expandir con 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 enum tienen un tipo "relajado", por lo que puedes pasar tanto constantes enum como su valor literal:

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

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

BaseModel

Todos los objetos de parámetros y de respuesta heredan de Anthropic::Internal::Type::BaseModel, que proporciona varias comodidades, entre ellas:

1. Todos los campos, incluidos los desconocidos, son accesibles con la sintaxis obj[:prop], y pueden desestructurarse con obj => {prop: prop} o con la 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 propias clases pueden imprimirse con formato 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 ante 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 ello, la recomendación es crear el cliente una sola vez por aplicación en la mayoría de los entornos.

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

A menos que se especifique lo contrario, las demás clases del SDK no tienen locks 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 quieres enviar explícitamente un parámetro adicional, puedes hacerlo con extra_query, extra_body y extra_headers dentro del 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 la autenticación, los 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 con plataformas

El SDK de Ruby es compatible con 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: Forma 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 es 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