---
title: SDK de Ruby
url: https://platform.claude.com/docs/es/cli-sdks-libraries/sdks/ruby
description: Instala y configura el SDK de Ruby de Anthropic con tipos de Sorbet, ayudantes de streaming y agrupación de conexiones
---

La biblioteca de Ruby de Anthropic proporciona acceso conveniente a la API de Claude 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 "connection pooling" (agrupación de conexiones) a través de la gema `connection_pool`.

<Info>
  Para la documentación de las funciones de la API con ejemplos de código, consulta la [referencia de la API](https://platform.claude.com/docs/es/api/overview). Esta página cubre las funciones y la configuración específicas del SDK de Ruby.
</Info>

## Instalación

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

```bash
bundle add anthropic
```

## Requisitos

Ruby 3.2.0 o superior.

## Uso

```ruby
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-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" (federación de identidades de carga de trabajo), consulta [Autenticación](https://platform.claude.com/docs/es/manage-claude/authentication). Si tu "API key" (clave de API) es una [clave personal o de cuenta de servicio](https://platform.claude.com/docs/es/manage-claude/authentication#key-types) que no está limitada a un espacio de trabajo, establece el ID del espacio de trabajo en el encabezado de solicitud `anthropic-workspace-id`; [Seleccionar un espacio de trabajo](https://platform.claude.com/docs/es/manage-claude/authentication#select-a-workspace) muestra la opción por solicitud para este SDK.

## Streaming

El SDK ofrece soporte para respuestas en "streaming" (transmisión continua) mediante "Server-Sent Events" (eventos enviados por el servidor), o SSE.

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

stream.each do |message|
  puts(message.type)
end
```

### Ayudantes de streaming

Esta biblioteca proporciona varias facilidades para hacer streaming de mensajes, por ejemplo:

```ruby
anthropic = Anthropic::Client.new
stream = anthropic.messages.stream(
  max_tokens: 1024,
  messages: [{role: :user, content: "Say hello there!"}],
  model: :"claude-opus-5-5"
)

stream.text.each do |text|
  print(text)
end
```

El streaming con `anthropic.messages.stream(...)` expone varios ayudantes, incluida la 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 obtener documentación detallada sobre los patrones de "tool use" (uso de herramientas), incluido el ejecutor de herramientas, consulta [Tool Runner (SDK)](https://platform.claude.com/docs/es/agents-and-tools/tool-use/tool-runner).

```ruby
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

# Gestiona automáticamente el bucle de ejecución de herramientas
anthropic.beta.messages.tool_runner(
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [{role: "user", content: "What's 15 * 7?"}],
  tools: [Calculator.new]
).each_message { |message| puts message.content }
```

## Salidas estructuradas

Para consultar la documentación completa de salidas estructuradas, incluidos ejemplos en Ruby, consulta [Salidas estructuradas](https://platform.claude.com/docs/es/build-with-claude/structured-outputs).

## Manejo de errores

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

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

| Causa                    | Tipo de error              |
| ------------------------ | -------------------------- |
| HTTP 400                 | `BadRequestError`          |
| HTTP 401                 | `AuthenticationError`      |
| HTTP 403                 | `PermissionDeniedError`    |
| HTTP 404                 | `NotFoundError`            |
| HTTP 409                 | `ConflictError`            |
| HTTP 422                 | `UnprocessableEntityError` |
| HTTP 429                 | `RateLimitError`           |
| HTTP >= 500              | `InternalServerError`      |
| Otro error HTTP          | `APIStatusError`           |
| Tiempo de espera agotado | `APITimeoutError`          |
| Error de red             | `APIConnectionError`       |

## 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, los errores internos >=500 y los tiempos de espera agotados se reintentan de forma predeterminada.

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

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

```ruby
# 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-5",
  request_options: {timeout: 5}
)
```

Cuando se agota el tiempo de espera, se genera `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 de la API de Claude están paginados.

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

```ruby
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
```

Como alternativa, puedes usar los métodos `#next_page?` y `#next_page` para tener un control más granular al trabajar con páginas.

```ruby
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`](https://rubyapi.org/3.2/o/pathname), [`StringIO`](https://rubyapi.org/3.2/o/stringio) u otros.

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

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

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

# O bien, para controlar el nombre del 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 desactiva los reintentos, ya que la biblioteca no puede saber con certeza si el descriptor es un archivo o una tubería (que no se puede rebobinar).

## Sorbet

Esta biblioteca proporciona definiciones [RBI](https://sorbet.org/docs/rbi) completas y no depende de sorbet-runtime.

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

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

O, de forma equivalente:

```ruby
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-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-5"
)
anthropic.messages.create(**params)
```

### Enums

Como esta biblioteca no depende de `sorbet-runtime`, no puede proporcionar instancias de [`T::Enum`](https://sorbet.org/docs/tenum). En su lugar, el SDK proporciona "símbolos etiquetados", que siempre son primitivos en tiempo de ejecución:

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

```ruby
anthropic = Anthropic::Client.new
# Usar las constantes del enum conserva la información del tipo etiquetado:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: Anthropic::Model::CLAUDE_OPUS_5_5,
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO
)

# También se permiten valores literales:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5",
  service_tier: :auto
)
```

## BaseModel

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

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

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 se pueden imprimir con formato legible.

4. Ayudantes 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, pero solo son seguras ante fork cuando no hay solicitudes HTTP en curso.

Cada instancia de `Anthropic::Client` tiene su propio grupo de conexiones HTTP con un tamaño predeterminado de 99. Por ello, se recomienda crear el cliente una sola vez por aplicación en la mayoría de los casos.

Cuando todas las conexiones disponibles del grupo 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 bloqueos que protejan su estructura de datos subyacente.

## Trazado de OpenTelemetry

Cuando tu aplicación registra un tracer provider de OpenTelemetry, el SDK emite un span por cada solicitud que envía. Para enviar los spans a tu plataforma de observabilidad, consulta [Configura OpenTelemetry con el Claude SDK](https://platform.claude.com/docs/es/manage-claude/opentelemetry/sdk).

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

<Warning>
  Los parámetros `extra_` con el mismo nombre anulan los parámetros documentados. Por motivos de seguridad, asegúrate de que estos métodos solo se usen con datos de entrada de confianza.
</Warning>

```ruby
anthropic = Anthropic::Client.new
value = "example"
message =
  anthropic.messages.create(
    max_tokens: 1024,
    messages: [{role: "user", content: "Hello, Claude"}],
    model: :"claude-opus-5-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 las ventajas de la autenticación, los reintentos, etc., puedes hacer solicitudes usando `anthropic.request`, de esta manera:

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

## Integraciones de plataforma

<Note>
  Para consultar guías detalladas de configuración de plataformas con ejemplos de código, consulta:

  * [Amazon Bedrock](https://platform.claude.com/docs/es/build-with-claude/claude-in-amazon-bedrock)
  * [Amazon Bedrock (Opus 4.6 y anteriores)](https://platform.claude.com/docs/es/build-with-claude/claude-on-amazon-bedrock-legacy)
  * [Claude Platform en AWS](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws)
  * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/google-managed)

  Consulta también [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/anthropic-managed).
</Note>

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 [Espacios de trabajo](https://platform.claude.com/docs/es/build-with-claude/claude-platform-on-aws#workspaces)). Disponible en beta.
* **Foundry:** Actualmente no es compatible con el SDK de Ruby. Consulta [Claude en Microsoft Foundry](https://platform.claude.com/docs/es/build-with-claude/claude-in-microsoft-foundry) para ver los SDK compatibles.

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

El SDK de Ruby también es compatible con Claude Models on Google Cloud (Anthropic managed) a través de `Anthropic::GoogleCloudClient`. Este cliente está en beta. Se incluye en la gema principal `anthropic` y necesita la gema `googleauth`. Pasa `workspace_id:` al constructor o establece la variable de entorno `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`. Consulta [Resolución del proyecto, la ubicación y el workspace](https://platform.claude.com/docs/es/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution) para ver cómo el cliente resuelve el ID del workspace.

## Versionado semántico

Cada versión principal de este SDK envía de forma predeterminada una versión de la API en el encabezado `anthropic-version`, y con cada nueva versión de la API llega una nueva versión principal. La primera versión principal que envía `2026-10-21` es la 2.0.0; consulta [Migrar a la versión de la API 2026-10-21](https://platform.claude.com/docs/es/api/migration-2026-10-21#upgrade).

Este paquete sigue las convenciones de [SemVer](https://semver.org/spec/v2.0.0.html).

Este paquete considera que las mejoras en las definiciones de tipos `*.rbi` y `*.rbs` (que no son de tiempo de ejecución) son cambios que no rompen la compatibilidad.

## Recursos adicionales

* [Repositorio de GitHub](https://github.com/anthropics/anthropic-sdk-ruby)
* [Documentación de YARD](https://gemdocs.org/gems/anthropic)
* [Referencia de la API](https://platform.claude.com/docs/es/api/overview)
* [Streaming de mensajes](https://platform.claude.com/docs/es/build-with-claude/streaming)