Zum Inhalt springen

Claude Agent SDK: der komplette Leitfaden für Unternehmens-Agenten

Wer einen KI-Agenten bauen will, der nicht nur antwortet, sondern Dateien liest, Befehle ausführt und Ergebnisse prüft, muss die Schleife aus Modellaufruf, Werkzeugausführung und Rückmeldung irgendwo programmieren. Das Claude Agent SDK nimmt Ihnen diese Schleife ab: Es liefert die Laufzeit, auf der auch Claude Code arbeitet, als Bibliothek für Python und TypeScript. Dieser Leitfaden erklärt Aufbau, Einsatzfelder, Voraussetzungen und Grenzen, Stand Oktober 2026.

Was ist das Claude Agent SDK und wofür wird es eingesetzt?

Das Claude Agent SDK ist eine Bibliothek von Anthropic, die laut offizieller Übersicht dieselben Tools, denselben Agent-Loop und dieselbe Kontextverwaltung bereitstellt, die Claude Code antreiben. Sie bauen damit eigene Agenten, die Aufgaben planen und selbstständig mit Dateien, Shell-Befehlen, Webrecherche und angebundenen Systemen erledigen.

Der entscheidende Unterschied zu anderen Frameworks: Die meisten Agenten-Frameworks liefern einen Modell-Client plus Abstraktionen, die Werkzeuge schreiben Sie selbst. Das Claude Agent SDK liefert dagegen eine komplette, erprobte Laufzeit mit eingebauten Werkzeugen. Technisch startet das SDK ein Claude-Code-Binary als Unterprozess und steuert es über stdio, wie die Hosting-Dokumentation beschreibt.

Anthropic grenzt das SDK selbst von drei Nachbarprodukten ab:

  • Claude Code CLI: die Terminal-Oberfläche für interaktive Entwicklung.
  • Client SDK: direkter Zugriff auf die Claude API; die Werkzeugschleife schreiben Sie selbst oder nutzen den Tool Runner (Beta).
  • Managed Agents: Anthropic hostet den Agent-Loop, die Werkzeuge laufen in einer verwalteten oder selbst gehosteten Sandbox.

Das Agent SDK ist die Wahl, wenn Sie den Agenten in Ihre eigene Anwendung einbetten und den Prozess selbst betreiben wollen. Typische Aufgaben im Unternehmen: Prüfberichte aus einem Ordner auswerten und zusammenfassen, Tickets mit Logdateien abgleichen, Angebotsentwürfe aus Vorlagen und Stammdaten erzeugen, Code-Wartung in CI-Pipelines.

Früher hieß das Produkt Claude Code SDK. Der Migrationsleitfaden begründet die Umbenennung mit den breiteren Einsatzmöglichkeiten jenseits von Programmieraufgaben.

Wie funktioniert das Claude Agent SDK?

Kern ist eine Schleife: Claude erhält Prompt, Systemprompt, Werkzeugdefinitionen und Verlauf, entscheidet, ob es antwortet oder Werkzeuge aufruft, das SDK führt die Werkzeuge aus und gibt die Ergebnisse zurück. Das wiederholt sich, bis eine Antwort ohne Werkzeugaufruf kommt. Ihre Anwendung bekommt dabei einen Strom von Nachrichten.

Die Dokumentation zum Agent-Loop nennt fünf Nachrichtentypen: SystemMessage (Sitzungsereignisse wie Start oder Kompaktierung), AssistantMessage (Text oder Werkzeugaufruf), UserMessage (Werkzeugergebnis), StreamEvent (nur bei aktiviertem Teil-Streaming) und ResultMessage mit Endergebnis, Tokenverbrauch, Kosten und Sitzungs-ID.

Eingebaute Werkzeuge

Ohne eine Zeile eigenen Werkzeugcode stehen bereit:

KategorieWerkzeuge
DateienRead, Edit, Write
SucheGlob, Grep
AusführungBash
WebWebSearch, WebFetch
OrchestrierungAgent, Skill, AskUserQuestion, TaskCreate, TaskUpdate

Dazu kommt ToolSearch, das Werkzeugdefinitionen erst bei Bedarf lädt. Eigene Werkzeuge definieren Sie in Python mit dem Dekorator @tool und bündeln sie mit create_sdk_mcp_server zu einem MCP-Server, der laut Custom-Tools-Doku im eigenen Prozess läuft. Externe Systeme binden Sie über das Model Context Protocol an.

Rechte und Hooks

Jeder Werkzeugaufruf durchläuft eine feste Prüfreihenfolge, die die Permissions-Doku beschreibt: zuerst Hooks, dann Deny-Regeln, Ask-Regeln, der Permission-Modus, Allow-Regeln und zuletzt Ihr canUseTool-Callback. Eine Deny-Regel blockiert auch im Modus bypassPermissions. Hooks wie PreToolUse laufen in Ihrem Anwendungsprozess und verbrauchen keinen Kontext.

Die Modi im Überblick: default (unklare Aufrufe gehen an Ihren Callback, ohne Callback wird abgelehnt), acceptEdits (Dateiänderungen im Arbeitsverzeichnis automatisch), plan (nur planen, keine Änderungen), dontAsk (alles ohne Freigaberegel wird abgelehnt), auto (ein Klassifikationsmodell prüft Aktionen) und bypassPermissions (nur für isolierte Umgebungen).

Steuerung von Aufwand und Parallelität

Neben Rechten steuern Sie, wie gründlich Claude nachdenkt. Die Option effort kennt die Stufen low, medium, high, xhigh und max; niedrigere Stufen verbrauchen laut Doku weniger Tokens pro Durchlauf. Für einen Agenten, der nur Dateien auflistet, genügt low, für eine Fehlersuche über mehrere Module eher high. Die Stufe lässt sich pro Subagent überschreiben.

Fordert Claude mehrere Werkzeuge in einem Durchlauf an, führt das SDK lesende Werkzeuge wie Read, Glob und Grep parallel aus, verändernde wie Edit, Write und Bash nacheinander. Eigene Werkzeuge laufen standardmäßig nacheinander; mit der Annotation readOnlyHint erlauben Sie die parallele Ausführung. Diese Annotation ist eine Angabe, keine Durchsetzung: Schreibt die Funktion trotzdem, verhindert das SDK es nicht.

Kontext, Kompaktierung und Sitzungen

Nähert sich der Kontext seinem Limit, fasst das SDK ältere Verlaufsteile automatisch zusammen und meldet das mit einer compact_boundary-Nachricht. Anweisungen aus dem ersten Prompt können dabei verloren gehen; Anthropic empfiehlt, dauerhafte Regeln in eine CLAUDE.md zu schreiben, die bei jeder Anfrage erneut eingespielt wird. Sitzungen lassen sich über die Sitzungs-ID fortsetzen oder verzweigen.

Wofür eignet sich das SDK im Unternehmen?

Das SDK passt überall dort, wo ein Agent mehrere Schritte selbst plant und mit echten Dateien oder Systemen arbeitet. Weniger passend ist es für einfache Frage-Antwort-Anwendungen, bei denen ein einzelner API-Aufruf genügt. Vier Varianten treten in der Praxis häufig auf.

Dokumenten- und Datei-Agenten. Ein Agent liest einen Ordner mit Lieferscheinen, Prüfprotokollen oder Excel-Exporten, gleicht sie ab und schreibt einen Bericht. Die Dateiwerkzeuge sind eingebaut, die Rechte lassen sich per Read(path)- und Edit(path)-Regeln auf Verzeichnisse beschränken.

Service- und Wissens-Agenten. Ein Agent sucht in Handbüchern, Ticket-Historie und Logdateien nach der Ursache einer Störung. Über eigene MCP-Werkzeuge greift er auf das Ticketsystem zu. Wie solche Fachagenten fachlich aufgebaut sind, zeigt die Seite zum technischen Service mit KI-Agenten.

Entwicklungs- und CI-Agenten. Tests ausführen, Fehler analysieren, Korrekturen vorschlagen: Das ist das ursprüngliche Einsatzgebiet von Claude Code, jetzt in eigenen Pipelines einsetzbar.

Orchestrierte Mehrschritt-Agenten. Ein Hauptagent verteilt Teilaufgaben an Subagenten, die laut Doku nur ihre Endantwort zurückgeben und so den Kontext des Hauptagenten schlank halten.

Wie das SDK im Vergleich zu LangGraph, CrewAI oder dem OpenAI Agents SDK abschneidet, behandelt der Vergleich der KI-Agenten-Frameworks. Kurz: Viele andere Frameworks sind modellneutral und stärker auf explizite Ablaufgraphen ausgelegt, das Claude Agent SDK ist an Claude gebunden, bringt dafür eine vollständige Werkzeug- und Rechteschicht mit. Welche Claude-Tarife und Datenschutzfragen dahinterstehen, erklärt der Artikel Claude im Unternehmen.

Welche Voraussetzungen brauchen Sie?

Sie brauchen Python 3.10 oder Node.js 18, einen Zugang zur Claude API oder zu einem unterstützten Cloud-Anbieter und eine Ausführungsumgebung, in der der Agent Dateien und Befehle sicher nutzen darf. Organisatorisch brauchen Sie eine klare Festlegung, welche Systeme der Agent berühren darf und wer Ergebnisse verantwortet.

Technik

  • Laufzeit: Python 3.10+ oder Node.js 18+ laut Quickstart. Das Python-Paket claude-agent-sdk lag am 24. Oktober 2026 in Version 0.2.174 auf PyPI.
  • Zugang: Umgebungsvariable ANTHROPIC_API_KEY oder einer der Cloud-Wege: CLAUDE_CODE_USE_BEDROCK=1 (Amazon Bedrock), CLAUDE_CODE_USE_VERTEX=1 (Google Cloud), CLAUDE_CODE_USE_FOUNDRY=1 (Microsoft Foundry) oder Claude Platform on AWS.
  • Ressourcen: Die Hosting-Doku nennt 1 GiB RAM, 5 GiB Speicher und 1 CPU pro Agent als Ausgangspunkt; der Speicherbedarf wächst mit Sitzungslänge und Werkzeugnutzung.
  • Netz: ausgehendes HTTPS zu api.anthropic.com oder zum regionalen Endpunkt des Cloud-Anbieters.

Wichtig für die Lizenzfrage: Eigene Produkte dürfen ohne Freigabe von Anthropic kein claude.ai-Login und keine Abo-Kontingente nutzen. Für den Betrieb brauchen Sie also einen API-Vertrag.

Daten und Organisation

Ein Agent ist nur so gut wie die Dateien und Schnittstellen, die er erreicht. Klären Sie vorab: Wo liegen die Eingangsdaten (Netzlaufwerk, SharePoint, ERP-Export)? Welche Aktionen darf der Agent selbst ausführen, welche nur vorschlagen? Wer prüft Ergebnisse, bevor sie Kunden erreichen? Wenn der Agent personenbezogene Daten verarbeitet, gehören Auftragsverarbeitung und Datenstandort auf die Liste. Ein Betrieb über einen Cloud-Anbieter mit EU-Region kann helfen, ist aber keine Rechtsberatung; die Prüfung bleibt beim Datenschutzbeauftragten.

Wie gehen Sie in Schritten vor?

Starten Sie mit einem eng umrissenen Prozess, einem nur lesenden Agenten und harten Grenzen für Durchläufe und Budget. Erweitern Sie Schreibrechte erst, wenn Sie die Protokolle mehrerer Läufe gesehen haben. Fünf Schritte haben sich bewährt.

  1. Prozess wählen. Eine wiederkehrende Aufgabe mit klarem Ergebnis, etwa „Prüfprotokolle der Woche auf Abweichungen auswerten".
  2. Prototyp mit Lesezugriff. Agent mit allowed_tools=["Read", "Glob", "Grep"] und permission_mode="dontAsk" bauen. So läuft er ohne Rückfragen, kann aber nichts verändern.
  3. Eigene Werkzeuge ergänzen. Zugriffe auf ERP, Ticketsystem oder Datenbank als @tool-Funktionen kapseln, statt dem Agenten Shell-Zugang zu geben.
  4. Grenzen setzen. max_turns und max_budget_usd begrenzen Durchläufe und geschätzte Kosten. Ohne Limit läuft die Schleife, bis Claude fertig ist, was bei offenen Aufgaben lange dauern kann.
  5. Betrieb aufsetzen. Container pro Aufgabe oder langlaufender Dienst, Sitzungen über einen SessionStore sichern, OpenTelemetry-Export einschalten, ausgehenden Verkehr über einen Proxy mit Domain-Allowlist führen.

Welches Betriebsmuster passt?

Die Hosting-Doku beschreibt vier Muster, die sich nach Lebensdauer der Container unterscheiden:

  • Kurzlebige Sitzungen: ein Container pro Aufgabe, danach wird er verworfen. Passt zu Rechnungsauswertung, Übersetzung oder einer einzelnen Fehlersuche.
  • Langlaufende Sitzungen: dauerhafte Container mit mehreren SDK-Prozessen, etwa für einen Agenten, der eingehende E-Mails sichtet. Die Größe richtet sich nach der Zahl gleichzeitiger Sitzungen.
  • Hybride Sitzungen: kurzlebige Container, die beim Start den Verlauf aus einem SessionStore laden und Änderungen zurückschreiben. Ohne Store geht der Verlauf beim Herunterfahren verloren.
  • Mehrere Agenten in einem Container: für eng zusammenarbeitende Agenten, jeweils mit eigenem Arbeitsverzeichnis.

Für die Überwachung übernimmt das SDK die OpenTelemetry-Konfiguration aus der Umgebung. Prompt-Texte und Werkzeugeingaben sind laut Doku standardmäßig nicht im Export enthalten, was die Abstimmung mit Datenschutz und Betriebsrat erleichtert.

Ein minimaler, nur lesender Agent sieht so aus (Python, claude-agent-sdk 0.2.174, Stand Oktober 2026):

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],  # nur lesen
        permission_mode="dontAsk",               # alles andere ablehnen
        max_turns=20,                            # Durchläufe begrenzen
        cwd="./pruefprotokolle",                 # Arbeitsverzeichnis
    )
    async for message in query(
        prompt="Fasse alle Abweichungen in den Prüfprotokollen dieser Woche zusammen.",
        options=options,
    ):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

Ein ausführliches Einsteiger-Tutorial mit Tests und eigenen Werkzeugen folgt als eigener Artikel in diesem Themenbereich.

Wo liegen Grenzen und Risiken?

Das SDK nimmt Ihnen die Schleife ab, aber nicht die Verantwortung für Betrieb, Sicherheit und Kosten. Die größten Risiken sind zu weite Rechte, unbegrenzte Läufe, ungeplanter Speicherverbrauch und die feste Bindung an Claude als Modell.

  • Modellbindung. Das SDK arbeitet mit Claude-Modellen. Wer Modelle verschiedener Anbieter mischen will, ist mit einem modellneutralen Framework besser bedient.
  • Kein zustandsloser Dienst. Jede Sitzung ist ein eigener Unterprozess mit Shell, Arbeitsverzeichnis und Sitzungsdateien. Container-Neustarts löschen diesen Zustand, wenn Sie ihn nicht extern sichern.
  • Rechte-Fallen. allowed_tools begrenzt den Modus bypassPermissions nicht: Die Doku warnt ausdrücklich, dass dann trotzdem alle Werkzeuge freigegeben sind. Automatisch freigegebene Aufrufe erreichen Ihren canUseTool-Callback nie; Pflichtprüfungen gehören deshalb in einen PreToolUse-Hook.
  • Einstellungen aus dem Dateisystem. Ohne explizite setting_sources lädt das SDK Benutzer-, Projekt- und lokale Einstellungen inklusive CLAUDE.md, wie die CLI. In mandantenfähigen Systemen müssen Sie das abschalten, sonst können Kontexte zwischen Mandanten durchsickern.
  • Kein globales Timeout. Laut Hosting-Doku läuft eine Sitzung ohne eigene Zeitbegrenzung; nur max_turns begrenzt sie.
  • Kosten. Nach Angaben von Anthropic übersteigen Tokenkosten die Containerkosten typischerweise um mindestens eine Größenordnung. Budgetgrenzen und Kostenauswertung pro Sitzung sind Pflicht.
  • Kompaktierung. Frühe Anweisungen können bei der Zusammenfassung verloren gehen. Feste Regeln gehören in Konfiguration oder CLAUDE.md, nicht nur in den ersten Prompt.

In unserem eigenen Betrieb hat sich gezeigt, dass die meisten Probleme nicht vom Modell kommen, sondern von zu großzügigen Rechten und fehlenden Grenzen für Laufzeit und Budget.

Wie fangen Sie an?

Installieren Sie das SDK, setzen Sie einen API-Schlüssel und lassen Sie einen nur lesenden Agenten auf einen Testordner los. Danach entscheiden Sie anhand echter Protokolle, ob das SDK zu Ihrem Prozess passt oder ob ein einfacher API-Aufruf, ein anderes Framework oder ein gehosteter Agent besser geeignet ist.

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
export ANTHROPIC_API_KEY=ihr-schluessel

Prüfen Sie nach dem ersten Lauf drei Dinge: Welche Werkzeuge hat der Agent aufgerufen? Wie viele Durchläufe und welche Kosten weist die ResultMessage aus? Und hätten Sie die Aufgabe genauso zerlegt? Wenn die Antworten stimmen, folgt der Schritt zu eigenen Werkzeugen und einem abgesicherten Betrieb.

Wer den Weg vom Prototyp zu einem produktiven Fachagenten nicht allein gehen möchte, findet auf der Seite zu KI-Agenten für den Mittelstand einen Überblick, wie solche Agenten für Angebot, Service, Wissen und Vertrieb aufgebaut werden.

Häufige Fragen

Ist das Claude Agent SDK dasselbe wie das Claude Code SDK?

Ja, es ist der Nachfolger. Anthropic hat das Claude Code SDK umbenannt; die Pakete heißen jetzt claude-agent-sdk (Python) und @anthropic-ai/claude-agent-sdk (TypeScript), der Optionstyp in Python heißt ClaudeAgentOptions statt ClaudeCodeOptions.

Kann ich das SDK mit einem Claude-Pro- oder Max-Abo betreiben?

Für eigene Produkte nicht. Laut Anthropic dürfen Drittentwickler ohne vorherige Freigabe kein claude.ai-Login und keine claude.ai-Kontingente anbieten; vorgesehen ist ein API-Schlüssel oder ein Cloud-Anbieter wie Amazon Bedrock, Google Cloud oder Microsoft Foundry.

Brauche ich Claude Code zusätzlich installiert?

In den meisten Fällen nicht. Beide SDKs bringen ein natives Claude-Code-Binary mit; nur bei Installationen ohne passendes Binary, etwa einer Python-Quelldistribution, muss Claude Code separat installiert werden.

Welche Lizenz gilt für das Claude Agent SDK?

Die Nutzung richtet sich nach den Commercial Terms of Service von Anthropic, auch wenn Sie damit Produkte für eigene Kunden bauen. Einzelne Komponenten können eigene Lizenzen haben, die in deren LICENSE-Datei stehen.

Läuft das SDK komplett lokal?

Nein. Agent-Loop, Tools und Sitzungsdateien laufen bei Ihnen, die Modellaufrufe gehen aber an die Claude API oder an den gewählten Cloud-Anbieter. Ausgehender HTTPS-Zugang zu diesem Endpunkt ist Pflicht.

Quellen

  1. Anthropic: Agent SDK overview code.claude.com
  2. Anthropic: How the agent loop works code.claude.com
  3. Anthropic: Configure permissions (Agent SDK) code.claude.com
  4. Anthropic: Agent SDK Quickstart code.claude.com
  5. Anthropic: Hosting the Agent SDK code.claude.com
  6. Anthropic: Give Claude custom tools code.claude.com
  7. Anthropic: Migrate to Claude Agent SDK code.claude.com
  8. PyPI: claude-agent-sdk pypi.org