Ruby SDK

Die Anthropic Ruby-Bibliothek bietet bequemen Zugriff auf die Claude API aus jeder Ruby-Anwendung ab Version 3.2.0. Sie wird mit umfassenden Typen und Docstrings in Yard, RBS und RBI ausgeliefert. Als HTTP-Transport wird net/http aus der Standardbibliothek verwendet, mit „connection pooling“ (Verbindungspooling) über das Gem connection_pool.

Installation

Füge das Gem mit Bundler zum Gemfile deiner Anwendung hinzu:

bundle add anthropic

Anforderungen

Ruby 3.2.0 oder höher.

Verwendung

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

Authentifizierungsoptionen einschließlich Workload Identity Federation findest du unter Authentifizierung. Wenn dein API-Key ein persönlicher Key oder ein Service-Account-Key mit Zugriff auf mehrere Workspaces ist, setze die Workspace-ID im Request-Header anthropic-workspace-id; Einen Workspace auswählen zeigt die Option pro Anfrage für dieses SDK.

Streaming

Das SDK unterstützt „streaming“ (Streaming) von Antworten mithilfe von Server-Sent Events (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

Streaming-Helfer

Diese Bibliothek bietet mehrere Komfortfunktionen für das Streaming von Nachrichten, zum Beispiel:

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

Streaming mit anthropic.messages.stream(...) stellt verschiedene Helfer bereit, darunter Akkumulation und SDK-spezifische Events.

Eingabeschema und Tool-Aufrufe

Das SDK bietet Hilfsmechanismen, um strukturierte Datenklassen für Tools zu definieren und Claude diese automatisch ausführen zu lassen. Eine ausführliche Dokumentation zu Mustern der „tool use“ (Tool-Nutzung), einschließlich des Tool Runners, findest du unter 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

# Verarbeitet die Tool-Ausführungsschleife automatisch
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 }

Strukturierte Ausgaben

Die vollständige Dokumentation zu strukturierten Ausgaben einschließlich Ruby-Beispielen findest du unter Strukturierte Ausgaben.

Fehlerbehandlung

Wenn die Bibliothek keine Verbindung zur API herstellen kann oder die API einen nicht erfolgreichen Statuscode zurückgibt (also eine 4xx- oder 5xx-Antwort), wird eine Unterklasse von Anthropic::Errors::APIError ausgelöst:

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

Die Fehlercodes lauten wie folgt:

Wiederholungsversuche

Bestimmte Fehler werden standardmäßig automatisch 2 Mal wiederholt, mit einem kurzen exponentiellen Backoff.

Verbindungsfehler (zum Beispiel aufgrund eines Netzwerkverbindungsproblems), 408 Request Timeout, 409 Conflict, 429 Ratenlimit, interne Fehler >=500 sowie Timeouts werden standardmäßig alle wiederholt.

Du kannst die Option max_retries verwenden, um dies zu konfigurieren oder zu deaktivieren:

# Konfiguriere den Standardwert für alle Anfragen:
anthropic = Anthropic::Client.new(
  max_retries: 0 # default is 2
)

# Oder konfiguriere pro Anfrage:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5",
  request_options: {max_retries: 5}
)

Timeouts

Standardmäßig laufen Anfragen nach 10 Minuten in einen Timeout. Du kannst die Option timeout verwenden, um dies zu konfigurieren:

# Konfiguriere den Standardwert für alle Anfragen:
anthropic = Anthropic::Client.new(
  timeout: 20 # 20 seconds (default is 10 minutes)
)

# Oder konfiguriere pro Anfrage:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5",
  request_options: {timeout: 5}
)

Bei einem Timeout wird Anthropic::Errors::APITimeoutError ausgelöst.

Beachte, dass Anfragen, die in einen Timeout laufen, standardmäßig wiederholt werden.

Paginierung

List-Methoden in der Claude API sind paginiert.

Diese Bibliothek stellt mit jeder List-Antwort automatisch paginierende Iteratoren bereit, sodass du aufeinanderfolgende Seiten nicht manuell anfordern musst:

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

# Einzelnes Element von der Seite abrufen.
batch = page.data[0]
puts(batch.id)

# Ruft bei Bedarf automatisch weitere Seiten ab.
page.auto_paging_each do |batch|
  puts(batch.id)
end

Alternativ kannst du die Methoden #next_page? und #next_page verwenden, um bei der Arbeit mit Seiten eine feinere Kontrolle zu haben.

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

Datei-Uploads

Anfrageparameter, die Datei-Uploads entsprechen, können als Rohinhalt, als Pathname-Instanz, als StringIO oder in weiteren Formen übergeben werden.

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

# Verwende `Pathname`, um den Dateinamen zu senden und/oder zu vermeiden, dass eine große Datei in den Speicher geladen wird:
file_metadata = anthropic.files.upload(file: Pathname("/path/to/file"))

# Alternativ kannst du Dateiinhalte oder ein `StringIO` direkt übergeben:
file_metadata = anthropic.files.upload(file: File.read("/path/to/file"))

# Oder, um den Dateinamen und/oder den Content-Type zu steuern:
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)

Beachte, dass du auch einen rohen IO-Deskriptor übergeben kannst. Dies deaktiviert jedoch Wiederholungsversuche, da die Bibliothek nicht sicher sein kann, ob der Deskriptor eine Datei oder eine Pipe ist (die nicht zurückgespult werden kann).

Sorbet

Diese Bibliothek stellt umfassende RBI-Definitionen bereit und hat keine Abhängigkeit von sorbet-runtime.

Du kannst typsichere Anfrageparameter wie folgt angeben:

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

Oder, gleichwertig:

anthropic = Anthropic::Client.new
# Hashes funktionieren, sind aber nicht typsicher:
anthropic.messages.create(
  max_tokens: 1024,
  messages: [{role: "user", content: "Hello, Claude"}],
  model: :"claude-opus-5"
)

# Du kannst auch eine vollständige Params-Klasse per Splat übergeben:
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

Da diese Bibliothek nicht von sorbet-runtime abhängt, kann sie keine T::Enum-Instanzen bereitstellen. Stattdessen stellt das SDK „tagged symbols“ (markierte Symbole) bereit, die zur Laufzeit immer ein primitiver Wert sind:

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

# Ermittelter Typ: `T.all(Anthropic::MessageCreateParams::ServiceTier, Symbol)`
T.reveal_type(Anthropic::MessageCreateParams::ServiceTier::AUTO)

Enum-Parameter haben einen „gelockerten“ Typ, sodass du entweder Enum-Konstanten oder deren Literalwert übergeben kannst:

# Die Verwendung der Enum-Konstanten bewahrt die getaggten Typinformationen:
anthropic.messages.create(
  service_tier: Anthropic::MessageCreateParams::ServiceTier::AUTO,
  # ...
)

# Literalwerte sind ebenfalls zulässig:
anthropic.messages.create(
  service_tier: :auto,
  # ...
)

BaseModel

Alle Parameter- und Antwortobjekte erben von Anthropic::Internal::Type::BaseModel, das mehrere Komfortfunktionen bietet, darunter:

1. Alle Felder, einschließlich unbekannter, sind über die Syntax obj[:prop] zugänglich und können mit obj => {prop: prop} oder Pattern-Matching-Syntax destrukturiert werden.

2. Strukturelle Äquivalenz für Gleichheit; wenn zwei API-Aufrufe dieselben Werte zurückgeben, ergibt der Vergleich der Antworten mit == true.

3. Sowohl Instanzen als auch die Klassen selbst können mit Pretty-Print ausgegeben werden.

4. Helfer wie #to_h, #deep_to_h, #to_json und #to_yaml.

Nebenläufigkeit und Connection-Pooling

Die Anthropic::Client-Instanzen sind threadsicher, aber nur dann fork-sicher, wenn keine HTTP-Anfragen in Bearbeitung sind.

Jede Instanz von Anthropic::Client hat ihren eigenen HTTP-Connection-Pool mit einer Standardgröße von 99. Daher lautet die Empfehlung, den Client in den meisten Umgebungen einmal pro Anwendung zu erstellen.

Wenn alle verfügbaren Verbindungen aus dem Pool ausgecheckt sind, warten Anfragen darauf, dass eine neue Verbindung verfügbar wird, wobei die Wartezeit in der Warteschlange auf den Anfrage-Timeout angerechnet wird.

Sofern nicht anders angegeben, verfügen andere Klassen im SDK nicht über Locks, die ihre zugrunde liegende Datenstruktur schützen.

Benutzerdefinierte oder undokumentierte Anfragen stellen

Undokumentierte Eigenschaften

Du kannst undokumentierte Parameter an jeden Endpunkt senden und undokumentierte Antworteigenschaften wie folgt auslesen:

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

Undokumentierte Anfrageparameter

Wenn du explizit einen zusätzlichen Parameter senden möchtest, kannst du dies mit extra_query, extra_body und extra_headers unter dem Parameter request_options: beim Stellen einer Anfrage tun, wie in den obigen Beispielen gezeigt.

Undokumentierte Endpunkte

Um Anfragen an undokumentierte Endpunkte zu stellen und dabei die Vorteile von Authentifizierung, Wiederholungsversuchen usw. beizubehalten, kannst du Anfragen mit anthropic.request wie folgt stellen:

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

Plattformintegrationen

Das Ruby SDK unterstützt die folgenden Plattformen:

• Agent Platform: Anthropic::VertexClient. Erfordert das Gem googleauth.
• Bedrock: Anthropic::BedrockMantleClient oder Anthropic::BedrockClient für den bedrock-runtime-Pfad. Anthropic::BedrockMantleClient erfordert das Gem aws-sdk-core; Anthropic::BedrockClient erfordert das Gem aws-sdk-bedrockruntime.
• Claude Platform on AWS: Teil des Haupt-Gems anthropic (erfordert das Gem aws-sdk-core). Stellt Anthropic::AWSClient bereit. Übergib workspace_id: an den Konstruktor oder setze die Umgebungsvariable ANTHROPIC_AWS_WORKSPACE_ID (siehe Workspaces). In der Beta verfügbar.
• Foundry: Derzeit im Ruby SDK nicht unterstützt. Unterstützte SDKs findest du unter Claude in Microsoft Foundry.

Verwende Anthropic::BedrockMantleClient für neue Projekte; Anthropic::BedrockClient bleibt für bestehende Anwendungen erhalten, die die Bedrock-InvokeModel-API verwenden.

Semantische Versionierung

Dieses Paket folgt den SemVer-Konventionen.

Dieses Paket betrachtet Verbesserungen an den (nicht zur Laufzeit verwendeten) Typdefinitionen *.rbi und *.rbs als nicht-brechende Änderungen.

Zusätzliche Ressourcen

• GitHub-Repository
• YARD-Dokumentation
• API-Referenz
• Streaming von Nachrichten