Autonome Agenten mit dem Claude Code SDK entwickeln: Ein praktischer Leitfaden für Entwickler

Autonome Agenten mit dem Claude Code SDK entwickeln: Ein praktischer Leitfaden für Entwickler

Das Claude Code SDK — offiziell Agent SDK genannt — ist eine Python- und TypeScript-Bibliothek, mit der du die vollständige agentische Engine von Claude Code programmatisch steuern kannst: kein Terminal, kein Mensch an der Tastatur, sondern deine Anwendung ruft eine asynchrone query()-Funktion auf und streamt jeden Schritt der Arbeit des Agenten zurück. Wenn du Claude Code interaktiv verwendet hast, bietet dir das SDK denselben Ablauf aus Dateien lesen / Code bearbeiten / Befehle ausführen als komponierbare Bibliothek, die du in CI-Pipelines, Code-Review-Bots, Multi-Agent-Orchestratoren oder beliebige Backend-Dienste einbetten kannst.

Was das Agent SDK ist — und warum es existiert

Claude Code ist vor allem als Terminal-Tool bekannt. Du gibst einen Prompt ein, der Agent denkt über deine Codebasis nach, ruft integrierte Tools auf (Read, Edit, Bash, Grep und andere) und schreibt Ergebnisse zurück an dich. Aber sobald du diesen Ablauf automatisieren willst — eine Review bei jedem Pull Request auslösen, auf mehrere spezialisierte Sub-Agenten verteilen oder ein Produkt darauf aufbauen — ist die interaktive CLI die falsche Abstraktion. Du brauchst eine Bibliothek.

Das Agent SDK schließt diese Lücke. Laut Anthropics offizieller Dokumentation macht es „dieselben Tools, denselben Agent-Loop und dasselbe Kontextmanagement, die Claude Code antreiben, in Python und TypeScript programmierbar." Das ist keine Marketingsprache — es ist die buchstäbliche Architektur. Das SDK startet die Claude Code CLI-Binärdatei als verwalteten Subprozess, kommuniziert mit ihr über stdio und stellt alles als asynchronen Stream typisierter Nachrichtenobjekte dar, die dein Code konsumieren und darauf reagieren kann.

Diese Unterscheidung ist aus mehreren Gründen wichtig:

Gleiche Engine, andere Schnittstelle. Wenn du von der CLI zum SDK wechselst, wechselst du nicht zu einem geringerwertigen oder einfacheren Tool. Das SDK erbt jede Fähigkeit der CLI — MCP-Serverkonnektivität, Hooks-Lifecycle, Skill-Dateien, CLAUDE.md-Speicher, Sub-Agent-Delegation und die vollständige Tool-Palette.

Das SDK übernimmt die Tool-Ausführung für dich. Wenn du das Anthropic Client SDK verwendest (das systemnähere anthropic Python/JS-Paket) und möchtest, dass Claude Tools aufruft, musst du den Tool-Loop selbst implementieren: die API aufrufen, eine Tool-Use-Antwort erkennen, das Tool ausführen, das Ergebnis zurückgeben, wiederholen, bis Claude stoppt. Das Agent SDK fasst diesen gesamten Loop in einem einzigen async for message in query(...) zusammen — Claude entscheidet, welche Tools aufgerufen werden, führt sie innerhalb seines Subprozesses aus und läuft weiter, bis die Aufgabe erledigt ist. Du konsumierst nur den Stream.

Headless by Design. Die Berechtigungsabfragen der CLI — „diesen Bash-Befehl erlauben?" — blockieren auf menschliche Eingabe. Das SDK ersetzt sie durch eine permissionMode-Option und eine Reihe von Berechtigungsmodi — zum Beispiel acceptEdits, um Dateibearbeitungen automatisch zu genehmigen, und bypassPermissions, um alles ohne Nachfrage in einer sandboxed CI-Umgebung auszuführen — plus einen programmatischen Genehmigungs-Callback für individuelle Abläufe. Die genauen Modusnamen und Verhaltensweisen sind in Anthropics SDK-Referenz dokumentiert (dort nachschauen für die aktuelle Liste), aber der Effekt ist derselbe: Deine Automatisierung hängt nie fest und wartet auf einen Tastendruck.

Dieselbe Claude Code Engine, zwei Schnittstellen: die interaktive CLI für Human-in-the-Loop-Arbeit, das Agent SDK für programmatische, headless Automatisierung, bei der deine Anwendung den Prompt steuert und ein Berechtigungsmodus den Genehmigungsdialog ersetzt.

Installation des SDK

Anthropic veröffentlicht zwei Pakete:

• TypeScript: @anthropic-ai/claude-agent-sdk (npm)
• Python: claude-agent-sdk (pip; erfordert Python 3.10+)

Das TypeScript-Paket bündelt eine native Claude Code-Binärdatei für deine Plattform, sodass keine separate CLI-Installation erforderlich ist. Die Authentifizierung erfolgt über eine ANTHROPIC_API_KEY-Umgebungsvariable, die du aus der Anthropic Console erhältst. Das SDK unterstützt außerdem Amazon Bedrock, Google Vertex AI und Microsoft Azure AI Foundry — siehe Anthropics Dokumentation für die entsprechenden Umgebungsvariablen-Muster.

Kernkonzepte

Das Verständnis von vier Konzepten deckt den Großteil der praktischen SDK-Nutzung ab.

1. Die query()-Funktion und der asynchrone Nachrichten-Stream

Jede SDK-Interaktion beginnt mit query(). Du übergibst einen prompt-String und ein options-Objekt; im Gegenzug erhältst du einen asynchronen Iterator, der typisierte Nachrichtenobjekte liefert, während der Agent arbeitet. Der Loop endet, wenn der Agent fertig ist oder auf einen Fehler stößt.

Die Nachrichten, die du empfängst, umfassen:

• AssistantMessage — Claudes Reasoning-Text und Beschreibungen der Tool-Aufrufe
• ToolResultMessage — die Ausgabe jeder Tool-Ausführung
• ResultMessage — das endgültige Ergebnis, mit einem subtype-Feld, das Erfolg oder Misserfolg anzeigt
• SystemMessage — Ereignisse im Session-Lifecycle (der init-Subtyp trägt die session_id)

In den meisten Produktionscodes filterst du nach ResultMessage, um die endgültige Ausgabe zu extrahieren, und protokollierst optional AssistantMessage-Blöcke, um nachzuverfolgen, was der Agent getan hat.

2. Tools und allowedTools

Die integrierte Tool-Palette des SDK bildet direkt die Fähigkeiten von Claude Code ab:

Die Option allowedTools genehmigt im Voraus eine Teilmenge davon und erteilt dem Agenten damit effektiv die Berechtigung, sie ohne zusätzliche Absicherung aufzurufen. Ein reiner Audit-Agent könnte nur ["Read", "Glob", "Grep"] auflisten; eine vollständige Automatisierung könnte ["Read", "Edit", "Bash", "Glob", "Grep"] enthalten.

3. Berechtigungsmodi

Berechtigungsmodi steuern, was passiert, wenn der Agent ein Tool verwenden möchte, das nicht in allowedTools vorab genehmigt ist:

• acceptEdits — genehmigt Dateibearbeitungen und gängige Dateisystemoperationen automatisch; fragt bei allem anderen nach. Am besten für vertrauenswürdige Entwicklungsworkflows.
• dontAsk — verweigert stillschweigend alles, was nicht in allowedTools steht. Am besten für abgeriegelte headless Agenten.
• bypassPermissions — führt jedes Tool ohne Absicherung aus. Nur innerhalb einer sandboxed Umgebung verwenden.

Das SDK stellt außerdem einen programmatischen Genehmigungs-Callback bereit, mit dem du vollständig individuelle Genehmigungslogik implementieren kannst, und die verfügbaren Modusnamen können sich im Laufe der Zeit erweitern — konsultiere Anthropics SDK-Referenz für die maßgebliche, aktuelle Liste und das genaue Verhalten jedes Modus. In CI wirst du fast immer eine eng begrenzte, standardmäßig verweigernde Konfiguration oder bypassPermissions innerhalb eines Container-Sandboxes verwenden, den du selbst kontrollierst.

4. Sessions, Fortsetzung und Kontext

Jeder Aufruf von query() erstellt (oder setzt fort) eine Session. Die session_id der Session kommt in der ersten SystemMessage mit subtype === "init" an. Du kannst sie erfassen und als resume: sessionId in einem nachfolgenden Aufruf übergeben, um genau dort weiterzumachen, wo das Gespräch aufgehört hat — dieselben Dateizugriffe, dieselbe Reasoning-Historie, dasselbe Kontextfenster.

So baust du Multi-Turn-Agenten: Ein query()-Aufruf analysiert ein Modul, erfasst die session_id, und ein zweiter query()-Aufruf (mit resume) bezieht sich auf „es" oder „die Datei, die du gerade gelesen hast", ohne alles neu erklären zu müssen. Session-Transkripte werden standardmäßig auf die lokale Festplatte geschrieben; für die Produktion kannst du einen SessionStore-Adapter anhängen, der von S3, Redis oder Postgres unterstützt wird, damit Sessions Container-Neustarts überstehen.

Build-Muster 1: Ein CI-Code-Review-Bot

Dies ist der klassische Anwendungsfall für „headless Automatisierung". Bei jedem Pull Request checkt ein CI-Job den Branch aus, führt einen Agenten aus, der die geänderten Dateien liest, und postet einen Review-Kommentar.

Der Ablauf:

1. Ein PR-Ereignis löst einen GitHub Actions-Workflow (oder einen GitLab-CI-Job) aus.
2. Der Runner checkt den Branch aus und führt dein Review-Skript aus.
3. Dein Skript ruft query() mit einem Review-Prompt auf, allowedTools: ["Read", "Glob", "Grep", "Bash"] und permissionMode: "dontAsk".
4. Claude liest den Diff, sucht nach Mustern, denkt über die Befunde nach.
5. Die ResultMessage trägt den Review-Text; dein Skript postet ihn über die GitHub API an den PR.

Die zentrale Design-Entscheidung ist die Verwendung von dontAsk mit einer schreibgeschützten Tool-Liste. Der Agent kann keine Dateien schreiben oder Netzwerkaufrufe außerhalb dessen tätigen, was die Tools erlauben, sodass dein CI-Job nicht versehentlich Commits mergen oder externe APIs aufrufen kann. Ein maxTurns-Limit (in den Optionen gesetzt) begrenzt die Tiefe des Agenten, damit außer Kontrolle geratene Loops kein Budget verbrauchen.

Die illustrierte Architektur dieses Ablaufs siehst du im Diagramm unten.

Eine vollständig automatisierte Code-Review-Pipeline. Der SDK-Agent läuft innerhalb eines CI-Containers mit einer schreibgeschützten Tool-Liste; Befunde strömen als ResultMessage zurück, und dein Code postet sie als GitHub-PR-Kommentar. Der Agent schreibt nie Dateien und verlässt den Container nie.

Du kannst dieses Muster mit Hooks erweitern — einer SDK-Funktion, die in unserem Claude Code Hooks Deep-Dive behandelt wird —, um jeden Tool-Aufruf in einer Audit-Datei zu protokollieren, bestimmte Dateipfade vom Lesen auszuschließen oder strukturierte Telemetrie zusammen mit der Review auszugeben.

Build-Muster 2: Multi-Agent-Tool-Ketten

Die agents-Option des SDK erlaubt es dir, benannte Sub-Agenten zu definieren, jeweils mit eigenem System-Prompt, Tool-Liste und Berechtigungen. Dein Haupt-Agent delegiert Arbeit an sie über das integrierte Agent-Tool. Sub-Agent-Nachrichten enthalten ein parent_tool_use_id-Feld, mit dem du genau nachverfolgen kannst, welche Delegation welches Ausgabestück erzeugt hat.

Ein praktisches Beispiel: eine Sicherheits-Audit-Agentenkette, bei der ein code-scanner-Sub-Agent mit Grep und Glob potenzielle Schwachstellen findet, ein dependency-checker-Sub-Agent Bash ausführt, um deine Paket-Metadaten abzufragen, und ein koordinierender Agent beide Berichte zu einem einheitlichen Audit zusammenfasst. Jeder Sub-Agent hat den minimalen Tool-Zugriff, der für seine Rolle nötig ist, was den Wirkungsradius begrenzt, falls ein Sub-Agent einen gefährlichen Befehl halluziniert.

Multi-Agent-Ketten eignen sich gut für Aufgaben, die sich natürlich zerlegen lassen: ein Agent pro Anliegen, jeweils mit einer engen Tool-Liste, orchestriert von einem Koordinator, der nur Read und Agent benötigt. Für einen breiteren Blick darauf, wie Multi-Agent-Architekturen mit Claude Code-Funktionen wie CLAUDE.md-Speicher und Skill-Dateien zusammenspielen, siehe unseren Harness Engineering Guide.

Build-Muster 3: Headless-Automatisierungspipelines

Über Code-Reviews hinaus glänzt das SDK bei jeder wiederkehrenden Automatisierung, bei der der Agent ein Schritt in einer größeren Pipeline ist:

Nächtliche Abhängigkeits-Audits. Ein Cron-Job ruft query() mit einem Prompt auf, um veraltete Pakete zu prüfen, Sicherheitsscanner auszuführen und einen strukturierten Bericht zu erstellen. Das Bash-Tool führt npm audit oder pip check aus; Read untersucht Lock-Dateien. Die ResultMessage speist eine Slack-Benachrichtigung.

Übersetzung und i18n beim PR-Merge. Wenn ein PR gemergt wird, löst ein Webhook einen Agenten aus, der geänderte String-Dateien mit Glob und Read liest, übersetzte Versionen mit Write erstellt und über Bash (durch Ausführen von gh pr create) einen neuen PR öffnet.

Log-Anomalie-Erkennung. Leite aktuelle Log-Ausgaben in einen query()-Prompt. Der Agent liest bei Bedarf zusätzliche Kontextdateien, denkt über die Logs nach und gibt einen strukturierten Befund aus. Keine Dateischreibvorgänge erforderlich; eine schreibgeschützte Tool-Liste genügt.

Dokumentationssynchronisation. Nachdem PRs gemergt wurden, liest ein Agent aktualisierte Quelldateien, schreibt entsprechende Dokumentationsseiten neu und committet die Änderungen. permissionMode: "acceptEdits" übernimmt Dateischreibvorgänge ohne Nachfrage.

Der gemeinsame Nenner: query() ersetzt eine maßgeschneiderte LLM-Integration. Du implementierst keinen Tool-Loop, verwaltest keine Kontextfenster manuell und parst keine Modellausgaben, um zu entscheiden, was als Nächstes ausgeführt wird. Der Agent übernimmt die Orchestrierung; du lieferst den Prompt und konsumierst das Ergebnis.

Ein ausführliches Beispiel: Ein Bugfix-Agent

Der offizielle Quickstart demonstriert dieses Muster übersichtlich (der folgende Code folgt der dokumentierten API — überprüfe die genaue Syntax in Anthropics Quickstart-Dokumentation):

Illustratives Python (genaue API in der offiziellen Dokumentation prüfen):

# Illustrativ — genaue Importpfade und Optionsnamen in der offiziellen Dokumentation bestätigen
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def run_bug_fixer(file_path: str):
    async for message in query(
        prompt=f"Review {file_path} for bugs that would cause crashes. Fix any issues.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"Completed: {message.subtype}")

asyncio.run(run_bug_fixer("src/utils.py"))

Illustratives TypeScript (genaue API in der offiziellen Dokumentation prüfen):

// Illustrativ — genaue Importpfade und Optionsnamen in der offiziellen Dokumentation bestätigen
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review src/utils.ts for crash-causing bugs and fix them.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
  },
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
    }
  }
  if (message.type === "result") console.log("Done:", message.subtype);
}

Was passiert, wenn dies ausgeführt wird: Claude liest utils.py (oder .ts) mit dem Read-Tool, denkt über den Code nach, identifiziert Edge Cases und ruft dann Edit auf, um defensive Behandlung einzufügen. Du siehst das Reasoning und die Tool-Aufrufe als AssistantMessage-Objekte vorbeiziehen; die abschließende ResultMessage signalisiert den Abschluss. Der gesamte Agent-Loop — einschließlich des erneuten Lesens der Datei, um die Bearbeitung zu überprüfen — wird vom SDK verwaltet.

Das unterscheidet das SDK vom direkten Aufruf der Anthropic Models API: Du implementierst die Tool-Ausführungsschicht nicht. Claude entscheidet, wann Read aufgerufen wird, ruft es auf, erhält den Dateiinhalt zurück und denkt weiter nach. Der Loop ist autonom.

Berechtigungen, Sandboxing und Produktionssicherheit

Der Betrieb autonomer Agenten in der Produktion erfordert eine sorgfältige Überlegung, worauf sie Zugriff haben sollen. Das SDK bietet mehrere gestaffelte Kontrollen.

Tool-Scoping ist die erste Verteidigungslinie. Wenn ein Agent Bash nicht benötigt, füge es nicht in allowedTools ein. Ein Agent mit nur ["Read", "Glob", "Grep"] kann keine Dateien ändern, keine Shell-Befehle ausführen oder Netzwerkaufrufe tätigen, egal was sein Prompt sagt.

Berechtigungsmodi bieten ein zweites Gate. dontAsk stellt sicher, dass alles außerhalb von allowedTools stillschweigend verweigert wird, anstatt nachzufragen. Das ist in headless Umgebungen entscheidend — eine Abfrage, die auf Nutzereingabe wartet, würde deine Pipeline blockieren.

Die cwd-Option begrenzt den Dateisystemzugriff des Agenten auf ein bestimmtes Verzeichnis. In Multi-Tenant-Umgebungen übergibst du ein Arbeitsverzeichnis pro Session, damit Agenten verschiedener Mandanten nicht gegenseitig ihre Dateien lesen können.

Mandantenisolation erfordert zusätzliche Schritte: Setze settingSources: [], damit keine Dateisystemeinstellungen mandantenübergreifend durchsickern; setze CLAUDE_CODE_DISABLE_AUTO_MEMORY=1, um zu verhindern, dass Auto-Memory geladen wird; richte CLAUDE_CONFIG_DIR auf einen mandantenspezifischen Pfad. Diese sind detailliert in Anthropics Hosting-Guide dokumentiert.

Container-Sandboxing ist die äußere Hülle. Für Produktions-Agenten, die Bash-Zugriff benötigen, führe das SDK innerhalb eines Containers aus, dessen Netzwerk-Egress auf die von dir explizit erlaubten Domains beschränkt ist. Anbieter wie Modal, E2B, Cloudflare Sandboxes, Fly Machines und Vercel Sandbox werden in Anthropics Dokumentation als Optionen für sandboxed SDK-Deployments genannt.

maxTurns begrenzt die Anzahl der Tool-Use-Runden und beschränkt sowohl Kosten als auch außer Kontrolle geratene Loops. Setze es basierend auf der erwarteten Komplexität deiner Aufgabe — eine einfache Datei-Review könnte 5–10 Runden benötigen; ein komplexes Multi-File-Refactoring könnte 30–50 benötigen.

Für Teams, die Produktions-Hooks und Berechtigungsabläufe aufbauen, behandelt unser Claude Code Hooks Guide den PreToolUse- und PostToolUse-Hook-Lifecycle im Detail, einschließlich der Frage, wie man Hook-Callbacks schreibt, die Tool-Aufrufe vor ihrer Ausführung blockieren, transformieren oder protokollieren.

MCP: Verbindung des Agenten mit externen Systemen

Das SDK unterstützt das Model Context Protocol (MCP) vollständig, mit dem du deinen Agenten mit jedem externen System verbinden kannst, das einen MCP-Server bereitstellt: Datenbanken, Browser-Automatisierung, Jira, Slack, GitHub und Hunderte von community-erstellten Servern.

Du konfigurierst MCP-Server in der mcpServers-Option — jeder Eintrag gibt einen auszuführenden Befehl und optionale Argumente an. Das SDK startet diese Server als Subprozesse, und der Agent kann ihre Tools genauso aufrufen wie integrierte Tools. So gibst du einem Code-Review-Agenten Zugriff auf dein Issue-Tracking-System oder verbindest einen Dokumentations-Agenten mit deiner Unternehmens-Wissensdatenbank.

Das Berechtigungsmodell gilt auch für MCP-Tool-Aufrufe — allowedTools kann MCP-Tool-Namen enthalten, und permissionMode regelt, was bei nicht aufgeführten Tools passiert.

Fallstricke und häufige Stolpersteine

Sessions sind standardmäßig subprozess-lokal. Session-Transkripte liegen auf der lokalen Festplatte des Hosts unter ~/.claude/projects/. In containerisierten oder horizontal skalierten Deployments bedeutet das, dass der Session-Zustand bei einem Neustart oder einer Node-Neuzuweisung verloren geht. Verwende einen SessionStore-Adapter für jede Session, die du containerübergreifend fortsetzen musst.

Das Subprozess-Modell hat Auswirkungen auf den Speicher. Jede laufende Session ist ein separater Subprozess. Fünfzig gleichzeitige Sessions bedeuten fünfzig Claude Code-Prozesse. Die offizielle Empfehlung liegt bei etwa 1 GiB RAM pro Agent als Ausgangspunkt, aber der tatsächliche Speicherverbrauch hängt von der Sessiondauer und der Tool-Aktivität ab. Dimensioniere deine Container entsprechend und setze maxTurns, um die Session-Tiefe zu begrenzen.

Große Sub-Agent-Fanouts stoßen an Rate-Limits. Wenn dein Orchestrator gleichzeitig an zwanzig Sub-Agenten delegiert, wirst du wahrscheinlich Anthropics API-Rate-Limits erreichen. Zerlege breite Fanouts in Batches und füge eine kleine Verzögerung zwischen den Dispatches hinzu.

bypassPermissions erfordert eine echte Sandbox. Dieser Modus überspringt alle Berechtigungsgates. Er ist für vollständig kontrollierte Umgebungen wie CI-Container konzipiert, in denen du den gesamten Ausführungskontext besitzt. Ihn auf dem Rechner eines Entwicklers zu verwenden — wo der Agent Zugriff auf SSH-Schlüssel, Cloud-Zugangsdaten und beliebige Dateisystempfade hat — ist ein Sicherheitsrisiko.

Das TypeScript-SDK bündelt die Claude Code-Binärdatei; Python benötigt sie nicht separat. Aber beide SDKs sind auf eine bestimmte CLI-Version festgelegt. Wenn du das SDK-Paket aktualisierst, aktualisierst du die zugrunde liegende CLI. Prüfe das Changelog vor Minor-Upgrades — Breaking-Behavior-Änderungen werden dort angekündigt.

Prompt-Text und Tool-Eingaben sind standardmäßig nicht in OTEL-Exporten enthalten. Das ist beabsichtigtes Datenschutzverhalten. Wenn du für Debugging-Zwecke Tracing auf Prompt-Ebene benötigst, musst du dies explizit über Umgebungsvariablen aktivieren, die in Anthropics Observability-Guide dokumentiert sind.

Ältere SDK-Versionen unterstützen möglicherweise keine neueren Modelle. Anthropics Dokumentation weist darauf hin, dass aktuelle Modelle aufgrund von Änderungen in der Thinking-Parameter-API eine aktuelle SDK-Version erfordern können, sodass ein veraltetes SDK bei einem neuen Modell fehlschlagen kann. Prüfe immer das Changelog und lege eine bekanntermaßen funktionierende Version fest, wenn du neue Modelle einsetzt.

Das SDK vs. die CLI: Was brauchst du?

Für die meisten Entwickler lautet die Antwort: beides — und das ist so beabsichtigt.

Die interaktive CLI ist das richtige Tool für die tägliche Entwicklung: Erkundung einer unbekannten Codebasis, interaktives Durcharbeiten eines komplexen Bugs oder Durchführung eines einmaligen Refactorings. Das SDK ist das richtige Tool für alles, was ohne anwesenden Menschen laufen muss: CI, geplante Aufgaben, Anwendungsfunktionen und Multi-Agent-Pipelines.

Das SDK und die CLI sind keine konkurrierenden Produkte. Die Workflows, die du interaktiv mit der CLI entwickelst, übertragen sich direkt auf die SDK-Automatisierung — dieselben Tools, dieselben Berechtigungskonzepte, dasselbe CLAUDE.md-Speicher- und Skill-System. Ein Review-Workflow, den du heute mit claude in deinem Terminal prototypst, wird morgen zu einem SDK-gestützten CI-Bot.

Für Teams, die die Web-Version von Claude Code nutzen (behandelt in unserem Claude Code im Web Guide), öffnet das SDK die Tür, um Web-Sessions mit programmatischer Orchestrierung zu kombinieren — starte eine langlaufende Aufgabe im Web und klinke dich dann programmatisch von deinem Backend aus ein.

Häufig gestellte Fragen

Was genau ist das Claude Code SDK (Agent SDK)? Es ist eine Python- (claude-agent-sdk) und TypeScript-Bibliothek (@anthropic-ai/claude-agent-sdk), die die vollständige agentische Engine von Claude Code — Tools, Berechtigungen, Session-Management, Sub-Agenten, MCP — als programmierbare asynchrone API bereitstellt. Du rufst query() auf, übergibst einen Prompt und Optionen und streamst die Arbeit des Agenten als typisierte Nachrichtenobjekte zurück.

Muss ich Claude Code installiert haben, um das SDK zu verwenden? Für das TypeScript-SDK nein — das Paket bündelt eine native Claude Code-Binärdatei. Für das Python-SDK übernimmt das claude-agent-sdk-Paket die Abhängigkeit. Du benötigst jedoch einen Anthropic API-Schlüssel aus der Anthropic Console.

Kann ich das SDK mit anderen Modellen als Claude auf Anthropics API verwenden? Ja. Das SDK unterstützt Amazon Bedrock, Google Vertex AI, Microsoft Azure AI Foundry und Claude Platform auf AWS über Umgebungsvariablen. Du kannst Anfragen auch über einen benutzerdefinierten Proxy leiten, indem du ANTHROPIC_BASE_URL setzt.

Wie verwende ich das SDK in einem GitHub Actions-Workflow? Füge deinen ANTHROPIC_API_KEY als GitHub Actions-Secret hinzu, checke den PR-Branch in deinem Workflow aus, installiere das SDK-Paket und führe dein Agenten-Skript aus. Verwende permissionMode: "dontAsk" mit einer schreibgeschützten allowedTools-Liste, damit der Agent keine Dateien in deiner CI-Umgebung ändern kann. Anthropics Dokumentation behandelt auch eine dedizierte GitHub Actions-Integration, die PR-Reviews und Issue-Triage automatisiert, ohne dass du eigenen SDK-Code schreiben musst.

Was ist der Unterschied zwischen dem Agent SDK und Managed Agents? Das Agent SDK ist eine Bibliothek, die den Agent-Loop innerhalb deines eigenen Prozesses und deiner eigenen Infrastruktur ausführt. Managed Agents ist eine gehostete REST-API, bei der Anthropic den Agenten und die Sandbox betreibt — du sendest Ereignisse und streamst Ergebnisse zurück. Das SDK eignet sich besser für lokales Prototyping und Agenten, die direkt auf deinem Dateisystem arbeiten; Managed Agents eignet sich besser für die Produktion, wenn du keine Container-Infrastruktur betreiben möchtest.

Wie begrenze ich, worauf der Agent zugreifen kann? Verwende allowedTools, um einzuschränken, welche Tools verfügbar sind, permissionMode: "dontAsk", um alles außerhalb dieser Liste zu verweigern, und cwd, um den Dateisystemzugriff auf ein bestimmtes Verzeichnis zu begrenzen. Für Multi-Tenant-Deployments setze zusätzlich settingSources: [] und CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Unterstützt das SDK Streaming-Ausgabe? Ja — der asynchrone Iterator von query() streamt Nachrichten in Echtzeit. Wenn du keine Live-Ausgabe benötigst (bei Hintergrundjobs oder CI-Pipelines, bei denen dich nur das Endergebnis interessiert), beschreibt Anthropics Dokumentation einen Single-Turn-Modus, der alle Nachrichten sammelt, bevor er zurückkehrt. Siehe Streaming vs. Single-Turn-Modus in der offiziellen Dokumentation.

Kann ich mehrere Agenten parallel ausführen? Ja. Jeder query()-Aufruf startet einen unabhängigen Subprozess. Du kannst N gleichzeitige Sessions ausführen — aber jede ist ein separater Prozess, also plane den Speicher entsprechend ein und achte auf API-Rate-Limits. Für gleichzeitige Sub-Agent-Fanouts von einem einzelnen Orchestrator aus bündle deine Dispatches, um Rate-Limits zu vermeiden.

Was passiert, wenn die Session mitten in der Aufgabe abstürzt? Standardmäßig sind Session-Transkripte lokal auf den Container beschränkt und gehen bei einem Neustart verloren. Um Neustarts zu überstehen, konfiguriere einen SessionStore-Adapter (S3, Redis oder Postgres) und übergib ihn in den Optionen. Du kannst die Session dann anhand der session_id auf einem neuen Container fortsetzen.

Agenten ohne lokales Setup ausführen

Das Wertversprechen des SDK ist Automatisierung — aber diese Automatisierung zum Laufen zu bringen, erfordert echte Infrastruktur: eine Python- oder Node-Laufzeitumgebung, einen API-Schlüssel, eine Container-Strategie, eine Sandboxing-Entscheidung und Zeit für die Modellierung von Berechtigungen vor deinem ersten Produktions-Deployment.

Für Entwickler, die Agenten-Ideen ohne diesen Setup-Aufwand ausprobieren möchten, betreibt Happycapy Claude Code-artige Agenten direkt im Browser. Es gibt keine lokale Installation, keine Subprozess-Verwaltung und keine Container-Bereitstellung. Du bringst einen Prompt mit, Happycapy übernimmt die Ausführungsumgebung — mit Zugriff auf über 150 Modelle und eine sichere Cloud-Sandbox. Es ist ein schneller Weg, um das Agentenverhalten zu prototypen, das du später mit dem SDK produktionsreif machst.

Kostenlos starten auf happycapy.ai

Verwandte Leitfäden

• Claude Code Hooks: The Power-User Guide to Automating Your Agent
• How Claude Code Review Actually Works: Diffs, Hooks, and What the Agent Catches
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)
• What Is Harness Engineering? Building Reliable AI Agent Harnesses (2026)