SDK Ruby

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

Installation

Ajoutez la gem au Gemfile de votre application avec Bundler :

bundle add anthropic

Prérequis

Ruby 3.2.0 ou version ultérieure.

Utilisation

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)

Pour les options d'authentification, y compris la « Workload Identity Federation » (fédération d'identité de charge de travail), consultez Authentification.

Streaming

Le SDK prend en charge le « streaming » (streaming) des réponses à l'aide des Server-Sent Events (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

Assistants de streaming

Cette bibliothèque fournit plusieurs fonctionnalités pratiques pour le streaming de messages, par exemple :

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

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'utilisation d'outils, y compris le tool runner, consultez 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

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

Sorties structurées

Pour la documentation complète sur les sorties structurées, y compris des exemples Ruby, consultez Sorties structurées.

Gestion des erreurs

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

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

Les codes d'erreur sont les suivants :

Nouvelles tentatives

Certaines erreurs feront automatiquement l'objet de 2 nouvelles tentatives par défaut, avec un court 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 :

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

# Ou configurez par requête :
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-4-8",
  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 :

# 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 par requête :
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-4-8",
  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 dans 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 :

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 plus de pages selon les besoins.
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 granulaire lors de la manipulation des pages.

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, de StringIO, ou autre.

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

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

# Vous pouvez également passer directement le contenu du fichier ou un `StringIO` :
file_metadata = anthropic.beta.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.beta.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 déterminer si le descripteur est un fichier ou un pipe (qui ne peut pas être rembobiné).

Sorbet

Cette bibliothèque fournit des définitions RBI complètes et n'a aucune dépendance envers sorbet-runtime.

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

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 manière équivalente :

anthropic = Anthropic::Client.new
# Les hashes fonctionnent, mais ne sont pas typesafe :
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-4-8"
)

# Vous pouvez aussi utiliser le splat d'une classe Params complète :
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)

Énumérations

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

# :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 d'énumération ont un type « relâché », vous pouvez donc transmettre soit des constantes d'énumération, soit leur valeur littérale :

# L'utilisation des constantes d'énumération préserve les informations de type étiqueté :
anthropic.messages.create(
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
  # ...
)

# Les valeurs littérales sont également admises :
anthropic.messages.create(
  service_tier: :auto,
  # ...
)

BaseModel

Tous les objets de paramètres et de réponses héritent de Anthropic::Internal::Type::BaseModel, qui offre plusieurs fonctionnalités pratiques, 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. É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 ainsi que les classes elles-mêmes peuvent être affichées de manière lisible (pretty-printed).

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

Concurrence et pooling de connexions

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

Chaque instance de Anthropic::Client possède son propre pool de connexions HTTP avec une taille par défaut de 99. Par conséquent, il est recommandé de créer le client une seule fois par application dans la plupart des configurations.

Lorsque toutes les connexions disponibles du pool sont utilisées, les requêtes attendent qu'une nouvelle connexion devienne disponible, le temps d'attente en file é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.

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 point de terminaison et lire des propriétés de réponse non documentées, comme suit :

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])

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 d'une requête, comme illustré dans les exemples ci-dessus.

Points de terminaison non documentés

Pour effectuer des requêtes vers des points de terminaison 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 suit :

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

Intégrations de plateformes

Le SDK Ruby prend en charge les plateformes suivantes :

• 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.
• Vertex AI : Anthropic::VertexClient. Nécessite la gem googleauth.
• Foundry : Non pris en charge actuellement dans le SDK Ruby. Consultez Claude dans Microsoft Foundry pour les SDK pris en charge.
• 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 (voir Espaces de travail). Disponible en version bêta.

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

Versionnage sémantique

Ce package suit les conventions SemVer. Comme la bibliothèque est en développement initial et possède une version majeure 0, les API peuvent changer à tout moment.

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
• Documentation YARD
• Référence de l'API
• Streaming de messages