Wer in den letzten Wochen in deutschen Entwickler-Foren und auf GitHub nach “Claude Agent SDK” gesucht hat, ist nicht allein: Laut aktuellen Keyword-Daten verzeichnet der Begriff rund 1.000 Suchanfragen pro Monat in Deutschland, bei niedriger Wettbewerbsdichte. Anthropic hat die deutsche Dokumentation zum SDK am 6. Oktober 2026 aktualisiert, nur drei Tage vor diesem Artikel. Grund genug, das Werkzeug einmal von Grund auf durchzugehen: Installation, Konfiguration, Berechtigungen, Hooks und ein komplettes Beispielprojekt, das Sie direkt übernehmen können.
Das Claude Agent SDK unterscheidet sich von der klassischen Claude API in einem entscheidenden Punkt: Es führt nicht nur ein Sprachmodell aus, das Text zurückgibt, sondern eine komplette agentische Schleife, in der Claude selbst Dateien liest, Code bearbeitet, Befehle ausführt und entscheidet, wann eine Aufgabe erledigt ist. Diese Anleitung zeigt in zwölf Schritten, wie Sie das SDK einrichten, einen ersten Agenten bauen, der Programmierfehler automatisch findet und korrigiert, und das Setup anschließend für den produktiven Einsatz absichern.
Was ist das Claude Agent SDK und wofür wird es gebraucht?
Das Claude Agent SDK ist eine Python- und TypeScript-Bibliothek von Anthropic, mit der Entwickler die gleiche Agent-Schleife, die auch Claude Code antreibt, in eigene Anwendungen einbetten. Statt selbst eine Tool-Schleife zu programmieren, die Modellantworten parst, Funktionsaufrufe erkennt und Ergebnisse zurückspielt, übernimmt das SDK diese Arbeit vollständig. Es bringt vorgefertigte Tools zum Lesen, Schreiben und Bearbeiten von Dateien mit, außerdem Bash-Ausführung, Websuche, ein Berechtigungssystem, Sitzungsverwaltung und Hooks für eigenen Code an kritischen Stellen des Ablaufs.
Technisch läuft im Hintergrund die native Claude-Code-Binärdatei, die sowohl das npm-Paket als auch das Python-Paket mitbringen. Ihr Python- oder TypeScript-Code kommuniziert mit dieser Binärdatei, sendet Prompts und empfängt einen Strom von Nachrichten, während der Agent arbeitet. Das Ergebnis: Sie schreiben wenige Zeilen Code und erhalten einen Agenten, der eigenständig plant, Tools aufruft, die Ergebnisse bewertet und entscheidet, was als Nächstes zu tun ist.
Besonders relevant wurde das Thema am 7. Oktober 2026, als Anthropic bekannt gab, dass Claude Max- und Team-Pläne künftig monatliche API-Guthaben enthalten. Diese Guthaben lassen sich laut Anthropic direkt für das Claude Agent SDK, den Headless-Modus claude -p, die Claude API und Claude Managed Agents einsetzen. Für Teams, die bereits einen Claude-Plan bezahlen, sinkt damit die Einstiegshürde für eigene Agenten-Projekte deutlich. Welches Modell dabei im Hintergrund die Entscheidungen trifft, lässt sich frei wählen, von schnellen und günstigen Modellen bis zu Anthropics aktuellstem Opus-Modell für besonders anspruchsvolle Aufgaben. Dieser Artikel ist Teil unserer laufenden Berichterstattung rund um KI und maschinelles Lernen, in der wir regelmäßig neue Werkzeuge aus dem Anthropic- und Open-Source-Umfeld einordnen.
Welche Funktionen bringt das SDK zusätzlich zum reinen Modellzugriff mit?
Bevor es an die Installation geht, lohnt sich ein Überblick darüber, was im Lieferumfang tatsächlich enthalten ist. Die offizielle Dokumentation listet acht Kernfunktionen, die über den reinen Chat-Zugriff der Claude API hinausgehen und die das SDK von einer einfachen Wrapper-Bibliothek unterscheiden.
| Funktion | Was sie konkret ermöglicht |
|---|---|
| Integrierte Tools | Dateien lesen, schreiben, bearbeiten, Befehle ausführen, im Web suchen |
| Hooks | Eigenen Code an festen Punkten im Lebenszyklus des Agenten ausführen |
| Subagenten | Spezialisierte Agenten für fokussierte Teilaufgaben starten |
| MCP | Externe Tools und Datenquellen über das Model Context Protocol anbinden |
| Berechtigungen | Steuern, welche Tools automatisch laufen und welche eine Bestätigung brauchen |
| Sitzungen | Kontext über mehrere Anfragen hinweg behalten, fortsetzen oder verzweigen |
| Skills, Befehle, Memory | Automatisches Laden aus dem .claude-Verzeichnis, genau wie in Claude Code |
| Plugins | Skills, Agenten, Hooks und MCP-Server gebündelt per lokalem Pfad laden |
Für die meisten Einstiegsprojekte reichen die ersten drei Zeilen dieser Tabelle, also Tools, Hooks und Berechtigungen, vollkommen aus. Sitzungen, Subagenten, MCP und Plugins werden erst relevant, wenn ein Agent mehrere Aufgaben koordiniert oder dauerhaft als Dienst läuft, wie es weiter unten im Abschnitt zu Sitzungen und im Beispielprojekt beschrieben wird.
Claude Agent SDK vs. Claude Code CLI vs. Claude API: Der Unterschied
Bevor Sie mit der Installation beginnen, lohnt sich ein Blick auf die Abgrenzung zu verwandten Anthropic-Werkzeugen, denn hier entstehen die meisten Verwechslungen. Die offizielle Dokumentation unterscheidet vier Wege, mit Claude zu arbeiten, je nachdem, wer den Agenten tatsächlich ausführt und wie viel Infrastruktur bereits vorgefertigt ist.
| Werkzeug | Wer führt den Agenten aus | Typischer Einsatz |
|---|---|---|
| Claude Agent SDK | Ihr eigener Prozess (Python/TypeScript) | Claude-Code-Fähigkeiten in eine eigene App einbetten |
| Claude Code CLI | Terminal auf Ihrem Rechner | Interaktive Entwicklung, einmalige Aufgaben |
| Client SDK / Claude API | Ihr eigener Prozess, Tool-Schleife selbst geschrieben | Direkter Modellzugriff ohne vorgefertigte Tools |
| Claude Managed Agents | Von Anthropic gehostete Sandbox oder eigene Sandbox | Agenten ohne eigene Infrastruktur betreiben |
Wer also schon mit der Claude API gearbeitet hat, kennt bereits den Modellzugriff, muss dort aber die Tool-Schleife, das Kontextmanagement und die Fehlerbehandlung selbst bauen. Das Agent SDK übernimmt genau diesen Teil, inklusive Berechtigungen, Hooks, Subagenten und Anbindung an das Model Context Protocol (MCP). Wer stattdessen gar keine eigene Infrastruktur betreiben will, greift zu Managed Agents, die über SDK, ant-CLI oder REST-API angesprochen werden.
Voraussetzungen: Diese Versionen brauchen Sie
Die Einstiegshürde ist niedrig, trotzdem sollten die folgenden Punkte vor dem ersten Schritt stimmen. Andernfalls scheitert die Installation später mit kryptischen Fehlermeldungen.
- Node.js 18 oder neuer, falls Sie mit TypeScript arbeiten möchten (prüfen mit
node -v) - Python 3.10 oder neuer, falls Sie mit Python arbeiten möchten (prüfen mit
python3 --version) - Ein Anthropic-Konto mit API-Zugriff über
platform.claude.com - Optional uv, Astrals schneller Python-Paketmanager, der virtuelle Umgebungen automatisch verwaltet
- Ein Terminal mit Schreibrechten im Projektverzeichnis, da der Agent dort Dateien anlegt und bearbeitet
- Für Unternehmensumgebungen alternativ Zugangsdaten für Amazon Bedrock, Google Cloud Vertex AI oder Microsoft Foundry statt eines reinen API-Schlüssels
Sie benötigen keine separate Claude-Code-Installation. Beide SDK-Pakete bringen die native Claude-Code-Binärdatei als Abhängigkeit mit. Eine Ausnahme gibt es: Installiert pip auf einer Plattform ohne passendes Wheel, etwa ARM64 unter Windows, die Quelldistribution, fehlt die gebündelte Binärdatei, und Sie müssen Claude Code manuell nachinstallieren. Gleiches gilt, wenn Sie npm mit --omit=optional aufrufen und damit die optionalen Abhängigkeiten überspringen.
Schritt 1 bis 2: Projektordner anlegen und Sprache wählen
Legen Sie zunächst ein neues Verzeichnis an. Das SDK greift standardmäßig nur auf Dateien in diesem Ordner und seinen Unterordnern zu, was für die ersten Tests ausreicht und spätere Sicherheitsprobleme von vornherein eingrenzt.
mkdir my-agent
cd my-agentOb Sie anschließend mit Python oder TypeScript weitermachen, hängt meist vom Rest Ihres Stacks ab. Beide SDKs bieten den identischen Funktionsumfang: dieselben Tools, dieselben Berechtigungsmodi, dieselben Hook-Ereignisse. In dieser Anleitung zeigen wir beide Varianten parallel, damit Sie direkt vergleichen können.
Ein Team, das bereits ein Node.js-Backend betreibt, bindet den Agenten meist direkt als zusätzlichen Service in dieselbe Codebasis ein und spart sich so eine zweite Laufzeitumgebung. Ein Data-Science- oder Backend-Team mit bestehendem Python-Stack tut dasselbe mit dem Python-Paket, oft als eigenständiges Skript oder als Teil einer bestehenden FastAPI- oder Django-Anwendung. Für reine Experimente ohne bestehenden Stack ist die Python-Variante mit uv meist der schnellere Einstieg, weil der Paketmanager die virtuelle Umgebung ohne weitere Konfiguration selbst anlegt.
Schritt 3: Das SDK installieren
Für ein neues TypeScript-Projekt richten Sie zuerst ein ES-Modul-Projekt ein und installieren danach das Paket @anthropic-ai/claude-agent-sdk zusammen mit tsx, das TypeScript-Dateien ohne separaten Build-Schritt ausführt.
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsxLäuft Ihr bestehendes Projekt noch mit CommonJS, benennen Sie die Agentendatei später agent.mts statt agent.ts. Die Endung zwingt tsx, die Datei als ES-Modul zu behandeln, ohne dass Sie das restliche Projekt umstellen müssen.
Für Python mit uv reichen zwei Befehle, da uv die virtuelle Umgebung automatisch anlegt und verwaltet:
uv init
uv add claude-agent-sdkBevorzugen Sie klassisches pip, erstellen Sie die virtuelle Umgebung selbst, aktivieren sie und installieren das Paket:
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdkUnter Windows nutzen Sie stattdessen py -m venv .venv und .venv\Scripts\Activate.ps1. Blockiert PowerShell das Aktivierungsskript mit einem Ausführungsrichtlinienfehler, führen Sie vorher einmalig Set-ExecutionPolicy -Scope Process RemoteSigned aus.
Schritt 4: API-Schlüssel und Authentifizierung konfigurieren
Holen Sie sich einen API-Schlüssel aus der Claude-Konsole unter platform.claude.com und setzen Sie ihn als Umgebungsvariable in der Shell, aus der Sie den Agenten später starten.
export ANTHROPIC_API_KEY=ihr-api-schluesselUnter Windows PowerShell lautet der Befehl $env:ANTHROPIC_API_KEY = "ihr-api-schluessel". Wichtig: Das SDK lädt keine .env-Dateien automatisch. Wer den Schlüssel dort ablegt, muss ihn selbst laden, etwa mit dem dotenv-Paket, bevor das SDK aufgerufen wird. Fehlt dieser Schritt, bricht der Agent später mit einem Authentifizierungsfehler wie Not logged in oder Invalid API key ab, obwohl der Schlüssel korrekt in der Datei steht.
Für Unternehmensumgebungen unterstützt das SDK auch Drittanbieter-Authentifizierung über Umgebungsvariablen: CLAUDE_CODE_USE_BEDROCK=1 für Amazon Bedrock, CLAUDE_CODE_USE_ANTHROPIC_AWS=1 zusammen mit ANTHROPIC_AWS_WORKSPACE_ID für Claude Platform on AWS, CLAUDE_CODE_USE_VERTEX=1 für Google Clouds Agent-Plattform und CLAUDE_CODE_USE_FOUNDRY=1 für Microsoft Foundry. In allen vier Fällen kommen zusätzlich die jeweiligen Cloud-Zugangsdaten zum Einsatz, der restliche Code bleibt unverändert.
Schritt 5: Eine Testdatei mit absichtlichen Fehlern erstellen
Damit der erste Agent etwas zu tun hat, legen Sie eine Datei mit zwei bekannten Fehlerquellen an. Erstellen Sie utils.py im Projektordner mit folgendem Inhalt:
def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers)
def get_user_name(user):
return user["name"].upper()Der Code enthält zwei klassische Laufzeitfehler: calculate_average([]) stürzt mit einer Division durch null ab, und get_user_name(None) wirft einen TypeError, weil None kein Dictionary ist. Beide Fälle sind typisch für Code, der nie gegen Randfälle getestet wurde, und genau daran lässt sich gut zeigen, wie selbstständig ein Agent arbeitet.
Schritt 6: Den ersten Agenten schreiben
Jetzt kommt der eigentliche Agentencode. Legen Sie agent.py beziehungsweise agent.ts an, wie es die offizielle Schnellstartanleitung von Anthropic auch vorschlägt. Der Agent bekommt einen Prompt, eine Liste erlaubter Tools und einen Berechtigungsmodus, der Dateibearbeitungen automatisch freigibt.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
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 hasattr(block, "name"):
print(f"Tool: {block.name}")
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}")
asyncio.run(main())Die TypeScript-Variante nutzt dieselbe Struktur, nur mit einer for await-Schleife statt async for:
import { query } from "@anthropic-ai/claude-agent-sdk";
for await (const message of query({
prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
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);
} else if ("name" in block) {
console.log(`Tool: ${block.name}`);
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`);
}
}Drei Dinge sind hier entscheidend. Erstens ist query der eigentliche Einstiegspunkt, der die agentische Schleife startet und einen asynchronen Iterator zurückgibt. Zweitens bestimmt der prompt, was Claude erreichen soll, während das Modell selbst entscheidet, welche Tools dafür nötig sind. Drittens steuert options das Verhalten: allowed_tools gibt Read, Edit und Glob vorab frei, permission_mode="acceptEdits" genehmigt Dateiänderungen automatisch, ohne bei jedem Schritt nachzufragen.
Schritt 7: Den Agenten ausführen und die Ausgabe lesen
Starten Sie den Agenten je nach Setup mit npx tsx agent.ts, uv run agent.py oder, bei aktivierter venv, einfach python agent.py. Eine typische Ausgabe sieht so aus:
I'll review utils.py for potential crash-causing bugs.
Tool: Read
I found two issues: calculate_average crashes on an empty list
(division by zero), and get_user_name crashes when user is None.
Tool: Edit
I've added guard clauses for both functions.
Done: successNach dem Lauf enthält utils.py defensiven Code, der leere Listen und None-Werte behandelt, ohne dass Sie eine Zeile selbst geschrieben haben. Der Agent hat dabei drei Schritte eigenständig durchlaufen: Er hat die Datei gelesen, um den Code zu verstehen, die Logik analysiert und die Randfälle identifiziert, die zum Absturz führen, und anschließend die Datei bearbeitet, um saubere Fehlerbehandlung einzubauen. Genau das unterscheidet das Agent SDK von einem einfachen Chat-Aufruf: Claude führt die Tools selbst aus, statt Sie zu bitten, das Ergebnis manuell umzusetzen.
Streaming- vs. Single-Turn-Modus: Welche Ausgabeform passt?
Das Beispiel aus Schritt 6 nutzt Streaming: Jede Nachricht, jeder Gedankenschritt und jeder Tool-Aufruf erscheint sofort in der Konsole, während der Agent noch arbeitet. Das ist praktisch, um live zu beobachten, was Claude gerade tut, etwa während der Entwicklung oder bei einer Demo vor Kollegen. Für Hintergrundjobs oder CI-Pipelines ist diese Live-Ausgabe aber meist unnötiger Overhead, dort reicht es, alle Nachrichten zu sammeln und erst am Ende auszuwerten.
Der Unterschied betrifft nur die Art, wie Sie die Nachrichten des Agenten konsumieren, nicht die Logik des Agenten selbst. Wer die rohen Nachrichtenobjekte ohne Filterung ausgibt, sieht übrigens deutlich mehr als nur Text und Tool-Namen: auch Systeminitialisierung und internen Zustand. Das ist beim Debuggen nützlich, wirkt im normalen Betrieb aber nur störend, weshalb sich die Filterung auf AssistantMessage und ResultMessage in der Praxis fast immer lohnt.
Schritt 8: Berechtigungsmodi richtig konfigurieren
Der Berechtigungsmodus entscheidet, wie viel menschliche Kontrolle über den Agenten bestehen bleibt. Das SDK kennt aktuell sechs Modi, die Sie beim Start der Abfrage oder dynamisch während einer laufenden Sitzung mit set_permission_mode() setzen können.
| Modus | Verhalten | Wann sinnvoll |
|---|---|---|
default | Keine automatische Freigabe, jede Anfrage läuft über den canUseTool-Callback | Produktionsnahe Umgebungen mit menschlicher Kontrolle |
acceptEdits | Dateibearbeitungen und Dateisystembefehle wie mkdir, mv, rm werden automatisch genehmigt | Prototyping im isolierten Verzeichnis |
plan | Claude erkundet und plant, Dateibearbeitungen werden nie automatisch freigegeben | Code-Review vor jeder Änderung |
dontAsk | Jede Anfrage, die sonst nachfragen würde, wird abgelehnt statt bestätigt | Headless-Agenten mit fester Tool-Oberfläche |
auto | Ein Modellklassifizierer prüft Shell-Befehle und Netzwerkzugriffe einzeln | Teilautomatisierung mit Restrisiko-Prüfung |
bypassPermissions | Nahezu alles wird ohne Rückfrage ausgeführt | Nur in vollständig kontrollierten Sandboxes |
Zwei Details aus der Dokumentation sind für die Praxis wichtig. Erstens blockiert selbst der bypassPermissions-Modus rm– und rmdir-Befehle, die auf kritische Systempfade zielen, diese landen trotzdem im canUseTool-Callback. Zweitens weigert sich Claude Code unter Linux und macOS, in diesem Modus als Root oder unter sudo außerhalb einer erkannten Sandbox zu starten, die Abfrage schlägt dann schon vor dem ersten Turn fehl. Seit TypeScript Agent SDK v0.3.286 verwirft eine Sitzung im Auto-Modus außerdem breite Allow-Regeln wie einen bloßen Bash-Eintrag, wer sich auf den alten Standard verlassen will, muss default jetzt explizit angeben.
Für einen klar abgesteckten Agenten empfiehlt sich die Kombination aus einer festen Tool-Liste und dem dontAsk-Modus:
const options = {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "dontAsk"
};Schritt 9: Hooks für Audit-Logging und Schutzregeln einrichten
Hooks sind Callback-Funktionen, die bei bestimmten Ereignissen im Agentenzyklus eigenen Code ausführen, etwa wenn ein Tool aufgerufen wird, eine Sitzung startet oder die Ausführung endet. Die offizielle Hooks-Dokumentation listet zwölf Hook-Ereignisse: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, StopFailure, SubagentStart, SubagentStop, PermissionRequest, SessionStart, SessionEnd und Notification.
Ein praktisches Beispiel: ein PreToolUse-Hook, der verhindert, dass der Agent jemals eine .env-Datei beschreibt, unabhängig vom aktiven Berechtigungsmodus. Der Hook wird mit einem Write|Edit-Matcher registriert, läuft also nur bei Datei-Schreib-Tools:
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher
async def protect_env_files(input_data, tool_use_id, context):
if input_data["hook_event_name"] != "PreToolUse":
return {}
file_path = input_data.get("tool_input", {}).get("file_path", "")
if ".env" in file_path:
return {
"hookSpecificOutput": {
"hookEventName": "PreToolUse",
"permissionDecision": "deny",
"permissionDecisionReason": "Writing to .env files is not allowed",
}
}
return {}
options = ClaudeAgentOptions(
hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)Der entscheidende Punkt: Ein Hook läuft noch vor Deny-Regeln, Ask-Regeln und dem Berechtigungsmodus. Eine Ablehnung im Hook gilt deshalb auch im bypassPermissions-Modus, während eine Freigabe im Hook die späteren Deny- und Ask-Regeln nicht überspringt, diese werden unabhängig vom Hook-Ergebnis trotzdem geprüft. Für Compliance-Zwecke eignet sich ein PostToolUse-Hook, der jede Dateiänderung in ein Audit-Log schreibt, etwa in eine lokale Datei oder an einen Webhook.
Hooks sind außerdem der richtige Ort, um sich gegen Prompt Injection abzusichern, also gegen Inhalte in gelesenen Dateien oder Websuchergebnissen, die versuchen, dem Agenten versteckte Anweisungen unterzuschieben. Ein PreToolUse-Hook kann Tool-Eingaben auf verdächtige Muster prüfen, bevor ein Befehl tatsächlich ausgeführt wird. Wer sich tiefer mit diesem Thema beschäftigen will, findet in unserer Anleitung zum Schutz vor Prompt Injection zusätzliche Techniken, die sich direkt auf Agent-SDK-Hooks übertragen lassen.
Schritt 10: Erweiterte Tools und eigenen System-Prompt freischalten
Sobald das Grundgerüst steht, lässt sich der Agent mit wenigen zusätzlichen Optionen deutlich leistungsfähiger machen. Websuche kommt über WebSearch in die Tool-Liste, ein eigener System-Prompt gibt dem Modell eine feste Rolle, und Bash erlaubt Terminalbefehle wie das Ausführen von Tests.
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "Bash"],
permission_mode="acceptEdits",
system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)Mit aktiviertem Bash-Tool lässt sich zum Beispiel der Prompt “Write unit tests for utils.py, run them, and fix any failures” direkt an den Agenten schicken, der dann eigenständig Tests schreibt, ausführt und bei Fehlschlägen nachbessert.
Schritt 11: Subagenten und MCP-Server anbinden
Für komplexere Aufgaben unterstützt das SDK Subagenten, also spezialisierte Agenten, die für eine fokussierte Teilaufgabe gestartet werden und danach wieder beendet sind. Ein Subagent läuft standardmäßig im Berechtigungsmodus der übergeordneten Sitzung, es sei denn, Sie setzen permissionMode explizit in seiner Agent-Definition. Wichtig für die Sicherheit: Ein Subagent erbt niemals automatisch bypassPermissions, außer die übergeordnete Sitzung läuft selbst in diesem Modus (ab Claude Code v2.1.267).
Über das Model Context Protocol (MCP) lassen sich zusätzlich externe Datenquellen anbinden, etwa Datenbanken, Browser-Automatisierung oder interne APIs. Wer bereits einen MCP-Server für ein anderes Projekt eingerichtet hat, kann ihn ohne größere Anpassung auch im Agent SDK registrieren. MCP-Tools, deren Server _meta["anthropic/requiresUserInteraction"] setzen, landen übrigens immer im canUseTool-Callback, auch wenn eine Allow-Regel eigentlich zutreffen würde. Diese Markierung erfordert mindestens Claude Code v2.1.199.
Schritt 12: Skills, Befehle und Memory aus dem .claude-Verzeichnis laden
Da das Agent SDK auf derselben Grundlage wie Claude Code läuft, liest es automatisch Projektkonfiguration aus dem Verzeichnis .claude/ Ihres Projekts und aus ~/.claude/. Dazu zählen projektspezifische Anweisungen in CLAUDE.md, Regeln, Skills und Plugins, die Skills, Agenten, Hooks und MCP-Server zusammen bündeln und per lokalem Pfad geladen werden. Wer bereits eigene Skills für Claude Code eingerichtet hat, kann diese also direkt in SDK-Agenten weiterverwenden, ohne sie neu zu schreiben.
Sitzungen verwalten: Kontext über mehrere Anfragen behalten
Jeder Aufruf von query() aus den bisherigen Beispielen startet eine neue, in sich abgeschlossene Sitzung ohne Gedächtnis an vorherige Läufe. Für einmalige Aufgaben wie den Bugfix aus Schritt 6 ist das genau richtig. Sobald ein Agent aber mehrstufig arbeiten soll, etwa in einem Chat-Interface, das über mehrere Nutzereingaben hinweg denselben Kontext braucht, kommen Sitzungen ins Spiel.
Mit dem ClaudeSDKClient, der im Abschnitt zu Berechtigungsmodi bereits für den dynamischen Moduswechsel genutzt wurde, bleibt eine Sitzung über mehrere query()-Aufrufe hinweg offen. Das erlaubt drei Dinge, die mit einzelnen, isolierten Aufrufen nicht möglich sind: Claude erinnert sich an frühere Nachrichten in derselben Sitzung, eine Sitzung lässt sich später fortsetzen, etwa nach einem Neustart des eigenen Dienstes, und ein Gesprächsverlauf lässt sich an einem bestimmten Punkt verzweigen, um zwei unterschiedliche Lösungswege parallel zu testen. Für einen Produktionsdienst, der mehrere parallele Nutzer bedient, bedeutet das in der Praxis eine Sitzung pro Nutzer oder pro Konversation, nicht eine einzige globale Sitzung für die gesamte Anwendung.
Komplettes Beispielprojekt: Ein automatischer Code-Review-Agent
Als Abschluss folgt ein vollständiges, lauffähiges Projekt, das die bisherigen Bausteine kombiniert: ein Agent, der ein Verzeichnis nach Python-Dateien durchsucht, jede Datei auf verbreitete Probleme prüft, Verbesserungsvorschläge in eine Markdown-Datei schreibt, dabei aber niemals selbst Code verändert. Das macht den Agenten sicher genug für den Einsatz in einer CI-Pipeline.
import asyncio
from pathlib import Path
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def review_codebase(target_dir: str, report_path: str = "review.md"):
prompt = (
f"Scan all .py files under {target_dir} for bugs, missing error "
f"handling, and PEP 8 violations. Write a structured report with "
f"one section per file to {report_path}. Do not modify any source "
f"file, only create or overwrite {report_path}."
)
options = ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep", "Write"],
disallowed_tools=["Edit", "Bash"],
permission_mode="acceptEdits",
system_prompt="You are a senior Python code reviewer. Be specific and cite line numbers.",
)
async for message in query(prompt=prompt, options=options):
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text)
elif hasattr(block, "name"):
print(f"Tool: {block.name}")
elif isinstance(message, ResultMessage):
print(f"Review finished: {message.subtype}")
if Path(report_path).exists():
print(f"Report written to {report_path}")
if __name__ == "__main__":
asyncio.run(review_codebase(target_dir="./src"))Der Trick liegt in disallowed_tools=["Edit", "Bash"]: Damit verschwinden beide Tools komplett aus Claudes Sichtfeld, der Agent kann sie nicht einmal versuchen, selbst wenn der Prompt ihn dazu verleiten würde. Gleichzeitig bleibt Write erlaubt, damit die Berichtsdatei entstehen kann. Diese Kombination aus gezielter Werkzeugauswahl und einer engen Aufgabenbeschreibung im Prompt ist in der Praxis der zuverlässigste Weg, einen Agenten auf exakt eine Aufgabe zu beschränken.
Häufige Fehler und Stolperfallen
Beim Einstieg in das Agent SDK wiederholen sich bestimmte Fehler auffällig oft. Die folgenden fünf kosten in der Praxis am meisten Zeit.
- Fehlende Typmodul-Konfiguration: Ohne
"type": "module"inpackage.jsonfunktioniert Top-Level-awaitin TypeScript-Agentenskripten nicht, der Code bricht mit einem Syntaxfehler ab. - .env-Dateien, die niemand lädt: Das SDK liest Umgebungsvariablen nur aus dem laufenden Prozess, nie automatisch aus einer
.env-Datei. Wer den Schlüssel dort speichert, braucht ein Paket wiedotenv, sonst folgt ein Authentifizierungsfehler. - allowed_tools mit bypassPermissions kombiniert und sich sicher gefühlt:
allowed_toolsschränktbypassPermissionsnicht ein. Wer nurReadfreigeben wollte, aber gleichzeitigbypassPermissionsaktiv hat, genehmigt trotzdem jedes Tool, inklusiveBashundWrite. Für echte Einschränkung gehört die Regel indisallowed_tools. - canUseTool-Callback, der nie aufgerufen wird: Automatisch genehmigte Tools, etwa durch
acceptEditsoder eine bloße Allow-Regel wie"Read", erreichen den eigenencanUseTool-Callback gar nicht. Prüfungen, die dort eingebaut wurden, laufen für diese Tools schlicht nie. - CommonJS-Projekte mit falscher Dateiendung: Wird ein bestehendes CommonJS-Projekt nicht umgestellt und die Agentendatei trotzdem
agent.tsstattagent.mtsgenannt, scheiterttsxam Top-Level-awaitmit einer wenig aussagekräftigen Fehlermeldung.
Am teuersten wird in der Praxis meist der dritte Punkt, die Verwechslung von allowed_tools und disallowed_tools. Beide Optionen klingen nach demselben Prinzip, wirken aber an völlig unterschiedlichen Stellen der Berechtigungsprüfung: Eine Allow-Regel genehmigt zusätzliche Aufrufe, schränkt aber nie einen bereits großzügigen Modus wie bypassPermissions ein. Nur eine Deny-Regel entfernt ein Tool wirklich aus Claudes Reichweite, unabhängig vom gewählten Modus. Wer Agenten mit echten Sicherheitsgarantien bauen will, sollte deshalb immer von einer Deny-Liste aus denken und nicht von einer Allow-Liste.
Fehlerbehebung: Die häufigsten Probleme im Detail
Über die fünf Stolperfallen hinaus tauchen beim produktiven Einsatz regelmäßig weitere, konkrete Fehlermeldungen auf. Die folgende Übersicht ordnet die häufigsten Symptome den jeweiligen Ursachen zu und nennt jeweils den schnellsten Weg zur Lösung, ohne dass eine erneute Komplettinstallation nötig wird.
| Symptom | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Not logged in beim Start | ANTHROPIC_API_KEY nicht in der aktuellen Shell gesetzt | Variable erneut exportieren oder dotenv vor dem SDK-Aufruf laden |
| Agent bearbeitet Dateien außerhalb des Projektordners nicht | Pfad liegt außerhalb des Arbeitsverzeichnisses oder additionalDirectories | Zielverzeichnis explizit zu additionalDirectories hinzufügen |
| CLI startet nicht, keine Ausgabe | Binärdatei fehlt, meist durch –omit=optional oder ARM64-Wheel-Problem | Claude Code separat installieren und pathToClaudeCodeExecutable setzen |
| Node.js-Warnung CLAUDE_SDK_CAN_USE_TOOL_SHADOWED | bypassPermissions oder ein bloßer allowedTools-Eintrag genehmigt Aufrufe, bevor canUseTool greift | Auf gezielte Regeln wie Bash(npm test *) wechseln oder PreToolUse-Hook nutzen |
| PowerShell blockiert Activate.ps1 | Standard-Ausführungsrichtlinie unter Windows | Set-ExecutionPolicy -Scope Process RemoteSigned einmalig ausführen |
| Agent führt rm im Projektordner nicht automatisch aus | Zielpfad wird als kritischer Systempfad erkannt | Löschung manuell bestätigen oder Pfad außerhalb kritischer Verzeichnisse verwenden |
| TypeScript-Agent läuft nicht mit Top-Level-await | package.json ohne “type”: “module” oder falsche Dateiendung | type: module setzen oder Datei in .mts umbenennen |
| Subagent erhält unerwartet vollen Systemzugriff | Übergeordnete Sitzung läuft in bypassPermissions, Subagent erbt den Modus | permissionMode in der AgentDefinition des Subagenten explizit einschränken |
Erweiterte Tipps für den Produktionseinsatz
Für den Einsatz jenseits lokaler Experimente lohnen sich einige zusätzliche Schritte. Erstens: Starten Sie neue Agenten-Projekte grundsätzlich im default– oder plan-Modus und lockern Sie die Berechtigungen erst, nachdem Sie Claudes ersten Ansatz überprüft haben, etwa per set_permission_mode("acceptEdits") mitten in der Sitzung. Das verhindert, dass ein schlecht formulierter Prompt sofort unkontrolliert Dateien verändert.
Zweitens: Nutzen Sie Sitzungen (Sessions), um Kontext über mehrere Anfragen hinweg zu erhalten, Agenten später fortzusetzen oder an einem bestimmten Punkt zu verzweigen, statt bei jedem Aufruf neuen Kontext aufzubauen. Drittens: Für Deployments in Docker, Cloud-Umgebungen oder CI/CD-Pipelines bietet die Dokumentation ein eigenes Hosting-Kapitel, das unter anderem beschreibt, wie sich die Binärdatei in einem Container ohne interaktives Terminal startet.
Fünftens: Schauen Sie sich fertige Beispielagenten an, bevor Sie eine Funktion komplett neu entwerfen. Anthropic pflegt im Repository claude-agent-sdk-demos mehrere vollständige Beispielprojekte, darunter einen E-Mail-Assistenten und einen Forschungsagenten, die sich als Ausgangspunkt für eigene Erweiterungen eignen. Wer zusätzlich verstehen will, wie das Claude-Code-Team selbst viele Subagenten gleichzeitig orchestriert, findet im Blogbeitrag zum Agent-Harness-Design einen Einblick in die internen Entwurfsentscheidungen hinter dynamischen Workflows, die sich teilweise auch auf eigene Multi-Agenten-Setups übertragen lassen.
Viertens: Beobachten Sie das Ökosystem rund um Agenten-Frameworks, bevor Sie Eigenbau-Komponenten schreiben. Mehrere etablierte Open-Source-Projekte decken ähnliche Teilprobleme ab und lassen sich oft über MCP einbinden, statt sie neu zu implementieren.
| Framework | GitHub-Stars (Stand Anfang Oktober 2026) | Fokus |
|---|---|---|
| LangChain | rund 147.000 | Allgemeine LLM-Orchestrierung |
| CrewAI | rund 59.000 | Rollenbasierte Multi-Agenten-Teams |
| LlamaIndex | rund 52.000 | Retrieval-Augmented Generation |
| LangGraph | rund 43.000 | Zustandsbasierte Agenten-Graphen |
| Agno | rund 43.000 | Leichtgewichtige Agenten-Laufzeit |
Diese Zahlen stammen aus einer Auswertung von kanerika.com vom 5. Oktober 2026 und bilden etablierte, allgemeine Frameworks ab, nicht das Agent SDK selbst, das als Bibliothek von Anthropic eine andere Kategorie darstellt. Sie zeigen aber, wie breit das Feld rund um Agenten-Infrastruktur inzwischen ist und warum sich ein Blick auf bestehende MCP-Integrationen fast immer lohnt, bevor eine Funktion komplett neu gebaut wird.
Wie verbreitet der Einsatz solcher Agenten inzwischen in Unternehmen ist, zeigt eine Analyse von Glide aus dem “State of AI in Operations”-Report 2025: “72% der Technologieunternehmen haben KI-Agenten bereits eingesetzt”, heißt es dort. Für Teams, die noch zögern, ist das ein Hinweis darauf, dass die Konkurrenz an dieser Front längst experimentiert, auch wenn nicht jeder Einsatz gleich produktionsreif ist.
Was kostet der Einstieg und wie zahlt man?
Das Agent SDK selbst ist eine kostenlose Open-Source-Bibliothek, Kosten entstehen durch die API-Aufrufe, die der Agent während seiner Arbeit auslöst, also pro verarbeitetem Token wie bei der regulären Claude API. Seit der Ankündigung vom 7. Oktober 2026 enthalten Claude Max- und Team-Pläne monatliche API-Guthaben, die genau für diesen Zweck gedacht sind: für das Agent SDK, den Headless-Modus claude -p, die Claude API und Claude Managed Agents. Wer bereits einen dieser Pläne bezahlt, muss also nicht zwingend ein separates API-Budget einrichten, sollte die enthaltenen Guthaben aber im Blick behalten, sobald ein Agent in einer Schleife viele Tool-Aufrufe produziert. Für einen einzelnen Testlauf wie den Bugfix-Agenten aus Schritt 6 oder 7 fällt der Verbrauch kaum auf, erst beim dauerhaften Betrieb mehrerer paralleler Agenten oder bei sehr langen Sitzungen mit vielen Tool-Aufrufen lohnt sich ein genauerer Blick auf die Abrechnung in der Claude-Konsole.
Wichtig für Drittanbieter: Anthropic erlaubt es nicht, claude.ai-Anmeldungen oder deren Rate-Limits in eigenen Produkten anzubieten, auch nicht über Agenten, die auf dem Agent SDK basieren, sofern dies nicht vorher genehmigt wurde. Für eigene Produkte bleibt also die API-Schlüssel-Authentifizierung der vorgesehene Weg.
Häufig gestellte Fragen zum Claude Agent SDK
Brauche ich eine separate Claude-Code-Installation für das Agent SDK?
In der Regel nicht. Sowohl das npm-Paket als auch das Python-Paket bündeln die native Claude-Code-Binärdatei als Abhängigkeit. Eine separate Installation wird nur nötig, wenn Ihre Plattform kein passendes Wheel oder optionale npm-Abhängigkeiten ausliefert, etwa bei ARM64 unter Windows oder bei npm ci --omit=optional.
Welcher Berechtigungsmodus eignet sich für den ersten Test?
acceptEdits ist ein guter Einstieg, weil Dateibearbeitungen automatisch genehmigt werden, während riskantere Aktionen wie Shell-Befehle außerhalb von Dateisystemoperationen weiterhin eine Bestätigung verlangen. Für produktionsnahe Tests ist plan sicherer, weil dort überhaupt keine Datei automatisch verändert wird.
Kann ich das Python- und das TypeScript-SDK im selben Projekt mischen?
Beide SDKs sind unabhängige Pakete mit identischem Funktionsumfang, aber es gibt keinen offiziellen Mechanismus, um sie innerhalb eines einzelnen Agentenprozesses zu kombinieren. Üblich ist, pro Dienst oder Microservice eine Sprache zu wählen und bei Bedarf über eine REST-Schnittstelle oder MCP zu verbinden.
Wie unterscheidet sich das Agent SDK von der klassischen Claude API?
Die Claude API liefert rohe Modellantworten, die Tool-Schleife, Kontextverwaltung und Wiederholungslogik müssen Entwickler selbst schreiben. Das Agent SDK übernimmt genau diesen Teil und liefert zusätzlich vorgefertigte Tools, Berechtigungen, Hooks, Sitzungen und Subagenten, die bei einer reinen API-Integration fehlen.
Funktioniert das Agent SDK auch mit Amazon Bedrock oder Google Vertex AI?
Ja. Über Umgebungsvariablen wie CLAUDE_CODE_USE_BEDROCK=1 oder CLAUDE_CODE_USE_VERTEX=1 lässt sich die Authentifizierung auf die jeweilige Cloud-Plattform umstellen, der restliche Agentencode bleibt dabei unverändert.
Was passiert, wenn ein Hook und eine Allow-Regel sich widersprechen?
Hooks werden immer zuerst ausgewertet. Lehnt ein Hook einen Tool-Aufruf ab, bleibt es bei der Ablehnung, unabhängig davon, was später als Allow-Regel oder Berechtigungsmodus folgen würde. Gibt der Hook dagegen frei, werden Deny- und Ask-Regeln trotzdem noch separat geprüft.
Lohnt sich das Agent SDK für kleine Projekte oder nur für große Teams?
Auch für kleine Projekte lohnt es sich, sobald wiederkehrende, mehrstufige Aufgaben automatisiert werden sollen, etwa Code-Reviews, Dokumentationspflege oder einfache Refactorings. Der Aufwand für die Ersteinrichtung liegt bei wenigen Minuten, die Komplexität wächst erst mit zusätzlichen Hooks, MCP-Servern und Berechtigungsregeln.
Wo finde ich den vollständigen Änderungsverlauf des SDK?
Anthropic pflegt für beide Sprachen eigene Änderungsprotokolle auf GitHub, im Repository claude-agent-sdk-typescript für TypeScript und im Repository claude-agent-sdk-python für Python. Dort lassen sich auch neue Versionen und Breaking Changes nachvollziehen, bevor ein Update eingespielt wird.
Funktioniert das Agent SDK auch mit anderen Sprachen als Python und TypeScript?
Offiziell gibt es nur Pakete für Python und TypeScript. Wer die gleiche Agent-Schleife aus einer anderen Sprache heraus steuern möchte, etwa aus Go, Rust oder Java, kann laut Dokumentation die Claude-Code-CLI als Unterprozess starten, mit dem Flag -p für den Headless-Modus und --output-format json für maschinenlesbare Ausgabe. Diese Variante liefert nicht ganz denselben Komfort wie die nativen SDK-Objekte, deckt aber die wichtigsten Funktionen für Sprachen ab, die sonst außen vor blieben.
Ich habe bereits die alten Claude Code SDK Pakete genutzt, wie steige ich um?
Anthropic hat das Agent SDK aus den älteren Claude Code SDK Paketen hervorgehen lassen und stellt dafür einen eigenen Migrationsleitfaden bereit. Der Kern der Umstellung betrifft meist nur Paketnamen und einzelne Importpfade, die grundlegende Architektur mit query(), Optionen und Nachrichtenstrom bleibt gleich. Vor einer Migration in produktiven Projekten lohnt sich trotzdem ein Testlauf in einer separaten Umgebung, insbesondere wenn eigene Hooks oder Berechtigungsregeln auf früheren Feldnamen basieren.
