---
title: SDK Ruby
url: https://platform.claude.com/docs/fr/cli-sdks-libraries/sdks/ruby
description: Installez et configurez le SDK Ruby d'Anthropic avec les types Sorbet, les assistants de streaming et le pool de connexions
---

La bibliothèque Ruby d'Anthropic offre un accès pratique à l'API Claude depuis n'importe quelle application Ruby 3.2.0+. Elle est livrée avec des types et des docstrings complets en YARD, RBS et RBI. Le `net/http` de la bibliothèque standard est utilisé comme transport HTTP, avec un « connection pooling » (pool de connexions) assuré par la gem `connection_pool`.

<Info>
  Pour la documentation des fonctionnalités de l'API avec des exemples de code, consultez la [référence de l'API](https://platform.claude.com/docs/fr/api/overview). Cette page couvre les fonctionnalités et la configuration spécifiques au SDK Ruby.
</Info>

## Installation

Ajoutez la gem au `Gemfile` de votre application avec Bundler :

```bash
bundle add anthropic
```

## Prérequis

Ruby 3.2.0 ou supérieur.

## Utilisation

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

Pour les options d'authentification, y compris la fédération d'identité de charge de travail (Workload Identity Federation), consultez [Authentification](https://platform.claude.com/docs/fr/manage-claude/authentication). Si votre clé API est une [clé de compte personnel ou de compte de service](https://platform.claude.com/docs/fr/manage-claude/authentication#key-types) qui n'est pas limitée à un espace de travail, définissez l'ID de l'espace de travail dans l'en-tête de requête `anthropic-workspace-id` ; [Sélectionner un espace de travail](https://platform.claude.com/docs/fr/manage-claude/authentication#select-a-workspace) présente l'option par requête pour ce SDK.

## Streaming

Le SDK prend en charge le « streaming » (streaming) des réponses à l'aide des « Server-Sent Events » (événements envoyés par le serveur), ou 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
```

### Assistants de streaming

Cette bibliothèque fournit plusieurs commodités pour le streaming des messages, par exemple :

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

Le streaming avec `anthropic.messages.stream(...)` expose divers assistants, notamment l'accumulation et des événements spécifiques au SDK.

## Schéma d'entrée et appel d'outils

Le SDK fournit des mécanismes d'assistance pour définir des classes de données structurées pour les outils et permettre à Claude de les exécuter automatiquement. Pour une documentation détaillée sur les modèles d'« tool use » (utilisation d'outils), y compris le tool runner, consultez [Tool Runner (SDK)](https://platform.claude.com/docs/fr/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

# Gère automatiquement la boucle d'exécution des outils.
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 }
```

## Sorties structurées

Pour la documentation complète sur les sorties structurées, y compris des exemples en Ruby, consultez [Sorties structurées](https://platform.claude.com/docs/fr/build-with-claude/structured-outputs).

## Gestion des erreurs

Lorsque la bibliothèque ne parvient pas à se connecter à l'API, ou si l'API renvoie un code de statut d'échec (c'est-à-dire une réponse 4xx ou 5xx), une sous-classe de `Anthropic::Errors::APIError` est levée :

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

Les codes d'erreur sont les suivants :

| Cause                   | Type d'erreur              |
| ----------------------- | -------------------------- |
| HTTP 400                | `BadRequestError`          |
| HTTP 401                | `AuthenticationError`      |
| HTTP 403                | `PermissionDeniedError`    |
| HTTP 404                | `NotFoundError`            |
| HTTP 409                | `ConflictError`            |
| HTTP 422                | `UnprocessableEntityError` |
| HTTP 429                | `RateLimitError`           |
| HTTP >= 500             | `InternalServerError`      |
| Autre erreur HTTP       | `APIStatusError`           |
| Délai d'attente dépassé | `APITimeoutError`          |
| Erreur réseau           | `APIConnectionError`       |

## Nouvelles tentatives

Certaines erreurs font automatiquement l'objet de 2 nouvelles tentatives par défaut, avec un court « exponential backoff » (délai exponentiel).

Les erreurs de connexion (par exemple, en raison d'un problème de connectivité réseau), 408 Request Timeout, 409 Conflict, 429 Rate Limit, les erreurs internes >=500 et les dépassements de délai font tous l'objet de nouvelles tentatives par défaut.

Vous pouvez utiliser l'option `max_retries` pour configurer ou désactiver ce comportement :

```ruby
# Configurez la valeur par défaut pour toutes les requêtes :
anthropic = Anthropic::Client.new(
  max_retries: 0 # default is 2
)

# Ou configurez-la par requête :
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5",
  request_options: {max_retries: 5}
)
```

## Délais d'attente

Par défaut, les requêtes expirent après 10 minutes. Vous pouvez utiliser l'option `timeout` pour configurer ce délai :

```ruby
# Configurez la valeur par défaut pour toutes les requêtes :
anthropic = Anthropic::Client.new(
  timeout: 20 # 20 seconds (default is 10 minutes)
)

# Ou configurez-la par requête :
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5",
  request_options: {timeout: 5}
)
```

En cas de dépassement du délai, `Anthropic::Errors::APITimeoutError` est levée.

Notez que les requêtes qui expirent font l'objet de nouvelles tentatives par défaut.

## Pagination

Les méthodes de liste de l'API Claude sont paginées.

Cette bibliothèque fournit des itérateurs à pagination automatique avec chaque réponse de liste, de sorte que vous n'avez pas à demander manuellement les pages successives :

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

# Récupère un seul élément de la page.
batch = page.data[0]
puts(batch.id)

# Récupère automatiquement d'autres pages si nécessaire.
page.auto_paging_each do |batch|
  puts(batch.id)
end
```

Vous pouvez également utiliser les méthodes `#next_page?` et `#next_page` pour un contrôle plus précis lors du travail avec les pages.

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

## Téléversement de fichiers

Les paramètres de requête correspondant à des téléversements de fichiers peuvent être transmis sous forme de contenu brut, d'une instance [`Pathname`](https://rubyapi.org/3.2/o/pathname), de [`StringIO`](https://rubyapi.org/3.2/o/stringio), ou autre.

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

# Utilisez `Pathname` pour envoyer le nom de fichier et/ou éviter de charger un gros fichier en mémoire :
file_metadata = anthropic.files.upload(file: Pathname("/path/to/file"))

# Vous pouvez aussi passer directement le contenu du fichier ou un `StringIO` :
file_metadata = anthropic.files.upload(file: File.read("/path/to/file"))

# Ou, pour contrôler le nom de fichier et/ou le type de contenu :
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)
```

Notez que vous pouvez également transmettre un descripteur `IO` brut, mais cela désactive les nouvelles tentatives, car la bibliothèque ne peut pas savoir si le descripteur est un fichier ou un pipe (qui ne peut pas être rembobiné).

## Sorbet

Cette bibliothèque fournit des définitions [RBI](https://sorbet.org/docs/rbi) complètes et ne dépend pas de sorbet-runtime.

Vous pouvez fournir des paramètres de requête typés de manière sûre comme ceci :

```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"
)
```

Ou, de manière équivalente :

```ruby
anthropic = Anthropic::Client.new
# Les hashes fonctionnent, mais ne sont pas typés de manière sûre :
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5"
)

# Vous pouvez aussi décomposer (splat) une classe Params complète :
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

Comme cette bibliothèque ne dépend pas de `sorbet-runtime`, elle ne peut pas fournir d'instances [`T::Enum`](https://sorbet.org/docs/tenum). À la place, le SDK fournit des « tagged symbols » (symboles étiquetés), qui sont toujours des primitives à l'exécution :

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

# Type révélé : `T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)`
T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO)
```

Les paramètres enum ont un type « assoupli », vous pouvez donc transmettre soit des constantes enum, soit leur valeur littérale :

```ruby
anthropic = Anthropic::Client.new
# L'utilisation des constantes d'énumération préserve les informations de type étiqueté :
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
)

# Les valeurs littérales sont également autorisées :
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5-5",
  service_tier: :auto
)
```

## BaseModel

Tous les objets de paramètres et de réponses héritent de `Anthropic::Internal::Type::BaseModel`, qui fournit plusieurs commodités, notamment :

1. Tous les champs, y compris les champs inconnus, sont accessibles avec la syntaxe `obj[:prop]` et peuvent être déstructurés avec `obj => {prop: prop}` ou la syntaxe de pattern matching.

2. Une équivalence structurelle pour l'égalité. Si deux appels d'API renvoient les mêmes valeurs, la comparaison des réponses avec == renverra true.

3. Les instances comme les classes elles-mêmes peuvent être affichées de manière lisible (pretty-print).

4. Des assistants tels que `#to_h`, `#deep_to_h`, `#to_json` et `#to_yaml`.

## Concurrence et pool de connexions

Les instances de `Anthropic::Client` sont thread-safe, mais ne sont fork-safe que lorsqu'aucune requête HTTP n'est en cours.

Chaque instance de `Anthropic::Client` possède son propre pool de connexions HTTP avec une taille par défaut de 99. Il est donc recommandé de créer le client une seule fois par application dans la plupart des cas.

Lorsque toutes les connexions disponibles du pool sont utilisées, les requêtes attendent qu'une nouvelle connexion se libère, le temps d'attente étant comptabilisé dans le délai d'expiration de la requête.

Sauf indication contraire, les autres classes du SDK ne disposent pas de verrous protégeant leur structure de données sous-jacente.

## Traçage OpenTelemetry

Lorsque votre application enregistre un tracer provider OpenTelemetry, le SDK émet un span pour chaque requête qu'il envoie. Pour envoyer les spans à votre plateforme d'observabilité, consultez [Configurer OpenTelemetry avec le SDK Claude](https://platform.claude.com/docs/fr/manage-claude/opentelemetry/sdk).

## Effectuer des requêtes personnalisées ou non documentées

### Propriétés non documentées

Vous pouvez envoyer des paramètres non documentés à n'importe quel endpoint et lire des propriétés de réponse non documentées, comme ceci :

<Warning>
  Les paramètres `extra_` du même nom remplacent les paramètres documentés. Pour des raisons de sécurité, assurez-vous que ces méthodes ne sont utilisées qu'avec des données d'entrée fiables.
</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])
```

### Paramètres de requête non documentés

Si vous souhaitez envoyer explicitement un paramètre supplémentaire, vous pouvez le faire avec `extra_query`, `extra_body` et `extra_headers` sous le paramètre `request_options:` lors de l'envoi d'une requête, comme illustré dans les exemples précédents.

### Endpoints non documentés

Pour effectuer des requêtes vers des endpoints non documentés tout en conservant les avantages de l'authentification, des nouvelles tentatives, etc., vous pouvez effectuer des requêtes à l'aide de `anthropic.request`, comme ceci :

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

## Intégrations de plateformes

<Note>
  Pour des guides de configuration détaillés des plateformes avec des exemples de code, consultez :

  * [Amazon Bedrock](https://platform.claude.com/docs/fr/build-with-claude/claude-in-amazon-bedrock)
  * [Amazon Bedrock (Opus 4.6 et versions antérieures)](https://platform.claude.com/docs/fr/build-with-claude/claude-on-amazon-bedrock-legacy)
  * [Claude Platform sur AWS](https://platform.claude.com/docs/fr/build-with-claude/claude-platform-on-aws)
  * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/fr/build-with-claude/claude-models-on-google-cloud/google-managed)

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

Le SDK Ruby prend en charge les plateformes suivantes :

* **Agent Platform :** `Anthropic::VertexClient`. Nécessite la gem `googleauth`.
* **Bedrock :** `Anthropic::BedrockMantleClient`, ou `Anthropic::BedrockClient` pour le chemin `bedrock-runtime`. `Anthropic::BedrockMantleClient` nécessite la gem `aws-sdk-core` ; `Anthropic::BedrockClient` nécessite la gem `aws-sdk-bedrockruntime`.
* **Claude Platform sur AWS :** Fait partie de la gem principale `anthropic` (nécessite la gem `aws-sdk-core`). Fournit `Anthropic::AWSClient`. Transmettez `workspace_id:` au constructeur ou définissez la variable d'environnement `ANTHROPIC_AWS_WORKSPACE_ID` (consultez [Espaces de travail](https://platform.claude.com/docs/fr/build-with-claude/claude-platform-on-aws#workspaces)). Disponible en bêta.
* **Foundry :** Actuellement non pris en charge dans le SDK Ruby. Consultez [Claude dans Microsoft Foundry](https://platform.claude.com/docs/fr/build-with-claude/claude-in-microsoft-foundry) pour les SDK pris en charge.

Utilisez `Anthropic::BedrockMantleClient` pour les nouveaux projets ; `Anthropic::BedrockClient` reste disponible pour les applications existantes utilisant l'API Bedrock `InvokeModel`.

Le SDK Ruby prend également en charge Claude Models on Google Cloud (Anthropic managed) via `Anthropic::GoogleCloudClient`. Ce client est en version bêta. Il est fourni dans la gem principale `anthropic` et nécessite la gem `googleauth`. Transmettez `workspace_id:` au constructeur ou définissez la variable d'environnement `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`. Consultez [Résolution du projet, de l'emplacement et de l'espace de travail](https://platform.claude.com/docs/fr/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution) pour savoir comment le client résout l'ID de l'espace de travail.

## Versionnage sémantique

Chaque version majeure de ce SDK envoie par défaut une version de l'API dans l'en-tête `anthropic-version`, et une nouvelle version majeure accompagne chaque nouvelle version de l'API. La première version majeure qui envoie `2026-10-21` est la 2.0.0 ; consultez [Migration vers la version 2026-10-21 de l'API](https://platform.claude.com/docs/fr/api/migration-2026-10-21#upgrade).

Ce package suit les conventions [SemVer](https://semver.org/spec/v2.0.0.html).

Ce package considère les améliorations apportées aux définitions de types `*.rbi` et `*.rbs` (hors exécution) comme des changements non cassants.

## Ressources supplémentaires

* [Dépôt GitHub](https://github.com/anthropics/anthropic-sdk-ruby)
* [Documentation YARD](https://gemdocs.org/gems/anthropic)
* [Référence de l'API](https://platform.claude.com/docs/fr/api/overview)
* [Streaming des messages](https://platform.claude.com/docs/fr/build-with-claude/streaming)