--- title: Ruby SDK url: https://platform.claude.com/docs/de/cli-sdks-libraries/sdks/ruby description: Installiere und konfiguriere das Anthropic Ruby SDK mit Sorbet-Typen, Streaming-Helfern und Connection-Pooling --- Die Anthropic Ruby-Bibliothek bietet bequemen Zugriff auf die Claude API aus jeder Ruby-3.2.0+-Anwendung. 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" (Verbindungs-Pooling) über das Gem `connection_pool`. Eine Dokumentation der API-Funktionen mit Codebeispielen findest du in der [API-Referenz](https://platform.claude.com/docs/de/api/overview). Diese Seite behandelt Ruby-spezifische SDK-Funktionen und die Konfiguration. ## Installation Füge das Gem mit Bundler zum `Gemfile` deiner Anwendung hinzu: ```bash bundle add anthropic ``` ## Anforderungen Ruby 3.2.0 oder höher. ## Verwendung ```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 ``` Informationen zu Authentifizierungsoptionen, einschließlich Workload Identity Federation, findest du unter [Authentifizierung](https://platform.claude.com/docs/de/manage-claude/authentication). Wenn dein API-Key ein [persönlicher Key oder Service-Account-Key](https://platform.claude.com/docs/de/manage-claude/authentication#key-types) ist, der nicht auf einen Workspace beschränkt ist, setze die Workspace-ID im Request-Header `anthropic-workspace-id`; [Einen Workspace auswählen](https://platform.claude.com/docs/de/manage-claude/authentication#select-a-workspace) zeigt die Option pro Anfrage für dieses SDK. ## Streaming Das SDK unterstützt „streaming" (Streaming) von Antworten mithilfe von Server-Sent Events (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 ``` ### Streaming-Helfer Diese Bibliothek bietet mehrere Annehmlichkeiten für das Streaming von Nachrichten, zum Beispiel: ```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 ``` Streaming mit `anthropic.messages.stream(...)` stellt verschiedene Helfer bereit, darunter Akkumulation und SDK-spezifische Events. ## Input-Schema 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)](https://platform.claude.com/docs/de/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 # Übernimmt automatisch die Schleife der Tool-Ausführung 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 } ``` ## Strukturierte Ausgaben Die vollständige Dokumentation zu strukturierten Ausgaben einschließlich Ruby-Beispielen findest du unter [Strukturierte Ausgaben](https://platform.claude.com/docs/de/build-with-claude/structured-outputs). ## Fehlerbehandlung Wenn die Bibliothek keine Verbindung zur API herstellen kann oder die API einen Statuscode zurückgibt, der keinen Erfolg anzeigt (also eine 4xx- oder 5xx-Antwort), wird eine Unterklasse von `Anthropic::Errors::APIError` ausgelöst: ```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 ``` Die Fehlercodes lauten wie folgt: | Ursache | Fehlertyp | | ------------------- | -------------------------- | | HTTP 400 | `BadRequestError` | | HTTP 401 | `AuthenticationError` | | HTTP 403 | `PermissionDeniedError` | | HTTP 404 | `NotFoundError` | | HTTP 409 | `ConflictError` | | HTTP 422 | `UnprocessableEntityError` | | HTTP 429 | `RateLimitError` | | HTTP >= 500 | `InternalServerError` | | Anderer HTTP-Fehler | `APIStatusError` | | Timeout | `APITimeoutError` | | Netzwerkfehler | `APIConnectionError` | ## 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 Rate Limit, >=500 interne Fehler und Timeouts werden standardmäßig alle wiederholt. Mit der Option `max_retries` kannst du dies konfigurieren oder deaktivieren: ```ruby # Konfiguriere den Standard für alle Anfragen: anthropic = Anthropic::Client.new( max_retries: 0 # default is 2 ) # Oder konfiguriere es pro Anfrage: anthropic.messages.create( max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}], model: :"claude-opus-5-5", request_options: {max_retries: 5} ) ``` ## Timeouts Standardmäßig laufen Anfragen nach 10 Minuten in ein Timeout. Mit der Option `timeout` kannst du dies konfigurieren: ```ruby # Konfiguriere den Standard für alle Anfragen: anthropic = Anthropic::Client.new( timeout: 20 # 20 seconds (default is 10 minutes) ) # Oder konfiguriere es pro Anfrage: anthropic.messages.create( max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}], model: :"claude-opus-5-5", request_options: {timeout: 5} ) ``` Bei einem Timeout wird `Anthropic::Errors::APITimeoutError` ausgelöst. Beachte, dass Anfragen, die in ein Timeout laufen, standardmäßig wiederholt werden. ## Paginierung List-Methoden in der Claude API sind paginiert. Diese Bibliothek stellt bei jeder List-Antwort automatisch paginierende Iteratoren bereit, sodass du aufeinanderfolgende Seiten nicht manuell anfordern musst: ```ruby 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` für eine feinere Kontrolle bei der Arbeit mit Seiten verwenden. ```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 ``` ## Datei-Uploads Anfrageparameter, die Datei-Uploads entsprechen, können als Rohinhalt, als [`Pathname`](https://rubyapi.org/3.2/o/pathname)-Instanz, als [`StringIO`](https://rubyapi.org/3.2/o/stringio) oder auf weitere Arten übergeben werden. ```ruby anthropic = Anthropic::Client.new require "pathname" # Verwende `Pathname`, um den Dateinamen mitzusenden und/oder das Laden einer großen Datei in den Speicher zu vermeiden: 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 Dateinamen und/oder Content-Type festzulegen: 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 jedoch Wiederholungsversuche deaktiviert, 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](https://sorbet.org/docs/rbi)-Definitionen bereit und hat keine Abhängigkeit von sorbet-runtime. Du kannst typsichere Anfrageparameter wie folgt angeben: ```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" ) ``` Oder gleichwertig: ```ruby 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-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-5" ) anthropic.messages.create(**params) ``` ### Enums Da diese Bibliothek nicht von `sorbet-runtime` abhängt, kann sie keine [`T::Enum`](https://sorbet.org/docs/tenum)-Instanzen bereitstellen. Stattdessen stellt das SDK „tagged symbols" (getaggte Symbole) bereit, die zur Laufzeit immer Primitive sind: ```ruby # :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: ```ruby anthropic = Anthropic::Client.new # Die Verwendung der Enum-Konstanten erhält die getaggten Typinformationen: 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 ) # Literale Werte sind ebenfalls zulässig: anthropic.messages.create( max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}], model: :"claude-opus-5-5", service_tier: :auto ) ``` ## BaseModel Alle Parameter- und Antwortobjekte erben von `Anthropic::Internal::Type::BaseModel`, das mehrere Annehmlichkeiten bietet, darunter: 1. Alle Felder, einschließlich unbekannter, sind mit der 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, liefert ein Vergleich der Antworten mit == true. 3. Sowohl Instanzen als auch die Klassen selbst können per 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-Verbindungspool mit einer Standardgröße von 99. Daher wird empfohlen, 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 auf das Anfrage-Timeout angerechnet wird. Sofern nicht anders angegeben, haben andere Klassen im SDK keine Locks, die ihre zugrunde liegende Datenstruktur schützen. ## OpenTelemetry-Tracing Wenn deine Anwendung einen OpenTelemetry Tracer Provider registriert, gibt das SDK für jede Anfrage, die es sendet, einen Span aus. Um die Spans an deine Observability-Plattform zu senden, siehe [OpenTelemetry mit dem Claude SDK einrichten](https://platform.claude.com/docs/de/manage-claude/opentelemetry/sdk). ## Benutzerdefinierte oder undokumentierte Anfragen stellen ### Undokumentierte Eigenschaften Du kannst undokumentierte Parameter an jeden Endpunkt senden und undokumentierte Antworteigenschaften wie folgt lesen: Die gleichnamigen `extra_`-Parameter überschreiben die dokumentierten Parameter. Stelle aus Sicherheitsgründen sicher, dass diese Methoden nur mit vertrauenswürdigen Eingabedaten verwendet werden. ```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]) ``` ### Undokumentierte Anfrageparameter Wenn du explizit einen zusätzlichen Parameter senden möchtest, kannst du dies beim Stellen einer Anfrage mit `extra_query`, `extra_body` und `extra_headers` unter dem Parameter `request_options:` tun, wie in den vorherigen 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: ```ruby response = anthropic.request( method: :post, path: '/undocumented/endpoint', query: {"dog": "woof"}, headers: {"useful-header": "interesting-value"}, body: {"hello": "world"} ) ``` ## Plattform-Integrationen Ausführliche Anleitungen zur Plattform-Einrichtung mit Codebeispielen findest du unter: * [Amazon Bedrock](https://platform.claude.com/docs/de/build-with-claude/claude-in-amazon-bedrock) * [Amazon Bedrock (Opus 4.6 und früher)](https://platform.claude.com/docs/de/build-with-claude/claude-on-amazon-bedrock-legacy) * [Claude Platform on AWS](https://platform.claude.com/docs/de/build-with-claude/claude-platform-on-aws) * [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/de/build-with-claude/claude-models-on-google-cloud/google-managed) Siehe auch [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/de/build-with-claude/claude-models-on-google-cloud/anthropic-managed). 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](https://platform.claude.com/docs/de/build-with-claude/claude-platform-on-aws#workspaces)). Als Beta verfügbar. * **Foundry:** Wird im Ruby SDK derzeit nicht unterstützt. Unterstützte SDKs findest du unter [Claude in Microsoft Foundry](https://platform.claude.com/docs/de/build-with-claude/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. Das Ruby SDK unterstützt über `Anthropic::GoogleCloudClient` auch Claude Models on Google Cloud (Anthropic managed). Dieser Client befindet sich in der Beta-Phase. Er wird im Haupt-Gem `anthropic` ausgeliefert und benötigt das Gem `googleauth`. Übergib `workspace_id:` an den Konstruktor oder setze die Umgebungsvariable `ANTHROPIC_GOOGLE_CLOUD_WORKSPACE_ID`. Unter [Auflösung von Projekt, Standort und Workspace](https://platform.claude.com/docs/de/build-with-claude/claude-models-on-google-cloud/anthropic-managed#project-location-and-workspace-resolution) erfährst du, wie der Client die Workspace-ID auflöst. ## Semantische Versionierung Jede Hauptversion dieses SDK sendet standardmäßig eine API-Version im Header `anthropic-version`, und mit jeder neuen API-Version kommt eine neue Hauptversion. Die erste Hauptversion, die `2026-10-21` sendet, ist 2.0.0; siehe [Migration zur API-Version 2026-10-21](https://platform.claude.com/docs/de/api/migration-2026-10-21#upgrade). Dieses Paket folgt den [SemVer](https://semver.org/spec/v2.0.0.html)-Konventionen. Dieses Paket betrachtet Verbesserungen an den (nicht zur Laufzeit verwendeten) Typdefinitionen `*.rbi` und `*.rbs` als nicht-brechende Änderungen. ## Zusätzliche Ressourcen * [GitHub-Repository](https://github.com/anthropics/anthropic-sdk-ruby) * [YARD-Dokumentation](https://gemdocs.org/gems/anthropic) * [API-Referenz](https://platform.claude.com/docs/de/api/overview) * [Streaming von Nachrichten](https://platform.claude.com/docs/de/build-with-claude/streaming)