Was ist das Claude Agent SDK? Komplettanleitung zur KI-Agenten-Entwicklung

„Wenn ich der KI nur Anweisungen geben könnte und sie dann selbstständig denkt und die Arbeit erledigt...“ — Genau diesen Traum verwirklicht ein KI-Agent. Das von Anthropic bereitgestellte Claude Agent SDK ist eine Bibliothek, mit der Sie KI-Agenten in Python oder TypeScript entwickeln können, die Claude als Gehirn nutzen. Sie stellt Ihren eigenen Programmen dieselben Tools, dieselbe Agentenschleife und dasselbe Kontextmanagement zur Verfügung, mit denen Claude Code arbeitet, der offizielle Coding-Agent von Anthropic.

In diesem Artikel erklären wir systematisch die Grundkonzepte des Claude Agent SDK, Implementierungsmethoden und Anwendungsfälle.

Was ist ein KI-Agent?

Ein KI-Agent unterscheidet sich von der traditionellen „Frage → Antwort“-KI. Seine Besonderheit besteht darin, dass er eigenständig Aufgaben zerlegt, Werkzeuge einsetzt, Ergebnisse bewertet und die nächste Aktion bestimmt.

Wenn Sie beispielsweise sagen „Behebe den Bug in auth.py“, arbeitet der Agent folgendermaßen:

1. Die Datei lesen und den Code verstehen
2. Zugehörige Dateien suchen, um den Gesamtzusammenhang zu erfassen
3. Die Ursache des Bugs identifizieren
4. Den Code korrigieren
5. Tests ausführen, um die Funktion zu überprüfen
6. Die Ergebnisse berichten

Ohne menschliches Eingreifen entscheidet der Agent selbst und führt all diese Schritte durch. Das ist die Stärke eines Agenten.

Überblick über das Claude Agent SDK

Das Claude Agent SDK ist die offizielle Bibliothek von Anthropic zum Entwickeln von Agenten. Die offizielle Dokumentation beschreibt es als Bibliothek, die die Claude-Code-Binärdatei ausführt. Die Richtung ist also: Das SDK steuert Claude Code, nicht umgekehrt. Die SDKs für Python und TypeScript bringen diese Binärdatei mit, sodass Claude Code in den meisten Umgebungen nicht separat installiert werden muss.

Die wichtigsten Merkmale sind:

Das Agent SDK dient dazu, den Agenten aus Claudes Code (Claude Code) außerhalb dieser Oberfläche in eigene Anwendungen und Skripte einzubauen.

Wie die Agentenschleife funktioniert

Das Herzstück des Agent SDK ist die Agentenschleife. Sie ist ein Mechanismus, der automatisch den Zyklus „Claude denkt, nutzt ein Tool, prüft das Ergebnis und denkt erneut“ ausführt.

Der detaillierte Ablauf sieht so aus:

1. Prompt-Empfang: Die Anweisungen des Benutzers werden an Claude übergeben
2. Claudes Entscheidung: Die Anweisungen werden analysiert und die nötigen Aktionen bestimmt
3. Tool-Ausführung: Tools wie Bash, Edit, Read werden aufgerufen, um die Arbeit zu erledigen
4. Ergebnisverarbeitung: Die Ausführungsergebnisse werden an Claude zurückgemeldet
5. Schleife fortsetzen oder beenden: Falls noch Arbeit nötig ist, zurück zu Schritt 2. Bei Abschluss wird eine Textantwort zurückgegeben

Der entscheidende Punkt ist: Wenn keine Tool-Aufrufe mehr stattfinden, ist die Aufgabe abgeschlossen. Sobald Claude feststellt, dass kein weiteres Tool benötigt wird, wird die finale Textantwort zurückgegeben.

Erste Schritte: Installation und Grundcode

Installation

Verfügbar für Python oder TypeScript.

# Python
pip install claude-agent-sdk

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

Voraussetzung ist Node.js 18 oder neuer bzw. Python 3.10 oder neuer (offizieller Quickstart).

Authentifizierung: API-Schlüssel statt claude.ai-Login

Das SDK arbeitet mit dem API-Schlüssel aus der Umgebungsvariable ANTHROPIC_API_KEY. Für Amazon Bedrock, Google Cloud (die von Google betriebene Version) oder Microsoft Foundry setzen Sie stattdessen CLAUDE_CODE_USE_BEDROCK=1, CLAUDE_CODE_USE_VERTEX=1 oder CLAUDE_CODE_USE_FOUNDRY=1 und richten die Zugangsdaten der jeweiligen Cloud ein. Das SDK lädt .env-Dateien nicht automatisch; setzen Sie die Variable also in der Shell, in der der Agent läuft. Einrichtung und Preise von Claude auf Google Cloud erklärt der Artikel Claude auf Vertex AI nutzen.

Vorsicht beim claude.ai-Login (Pro, Max und andere Abos): Ohne vorherige Genehmigung erlaubt die offizielle Dokumentation Drittentwicklern nicht, in ihren Produkten den claude.ai-Login oder dessen Nutzungslimits anzubieten – auch nicht in Agenten, die mit dem Agent SDK gebaut sind. Anwendungen, die Sie mit dem SDK entwickeln, authentifizieren sich per API-Schlüssel.

Minimaler Agent (Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="Finde und behebe den Bug in src/auth.py",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Grep"],
            max_turns=30,
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success":
                print(message.result)
            if message.total_cost_usd is not None:
                print(f"Kosten: ${message.total_cost_usd:.4f}")

asyncio.run(main())

Minimaler Agent (TypeScript)

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Finde und behebe den Bug in src/auth.py",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
    maxTurns: 30,
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Mit nur diesem Code liest Claude Dateien, sucht den Bug, behebt ihn und berichtet das Ergebnis. Beachten Sie aber: allowed_tools ist keine Liste der Tools, die Claude nutzen darf, sondern eine Liste der Tools, die ohne Rückfrage automatisch genehmigt werden. Weil dieses Beispiel Bash enthält, laufen die Shell-Befehle, die Claude wählt, ohne Bestätigung (abgesehen von wenigen Aktionen wie bestimmten Löschvorgängen, die keine Einstellung automatisch genehmigt). Da dieses Beispiel kein permission_mode setzt, kommt der Modus aus permissions.defaultMode in Ihren Einstellungsdateien oder sonst aus dem eingebauten Standard, und der war seit v2.1.285 auto in Sitzungen, die keine Feature-Flags abrufen, etwa bei einem Drittanbieter (Bedrock, Google Cloud, Microsoft Foundry) oder mit ausgeschalteter Telemetrie (offizielle Dokumentation). Allerdings hat sich das mit v2.1.302 (16. Oktober 2026) geändert: Agent-SDK- und claude -p-Sitzungen, die keinen Berechtigungsmodus angeben, starten nun mit default, auch über Drittanbieter-Provider. Für auto muss man ihn ausdrücklich angeben (in der CLI mit --permission-mode auto; Änderungsprotokoll, am 18. Oktober 2026 geprüft). Der auto-Modus verwirft breite Erlaubnisregeln wie Bash; wenn Sie sich auf das obige Verhalten verlassen, übergeben Sie daher ausdrücklich permission_mode="default" (TS: permissionMode: "default") (offizielle Dokumentation). Probieren Sie es in einem Arbeitsverzeichnis aus, bei dem nichts kaputtgehen kann. Wie Sie die Tools tatsächlich einschränken, zeigt der nächste Abschnitt.

Liste der integrierten Tools

Das Agent SDK enthält zahlreiche Tools, die sofort und ohne eigenen Code verwendet werden können.

Für die integrierten Tools müssen Sie keinen eigenen Verarbeitungscode schreiben. Entscheidend ist: „Welche Tools Claude sieht“ und „welche Tools ohne Rückfrage laufen“ sind zwei getrennte Einstellungen. So beschreibt es die offizielle Dokumentation:

Kombinieren Sie zum Beispiel allowed_tools=["Read"] mit permission_mode="bypassPermissions", wird trotzdem alles genehmigt – auch die nicht aufgeführten Tools Bash, Write und Edit (die offizielle Dokumentation warnt ausdrücklich vor dieser Kombination). Soll ein Tool unerreichbar sein, entfernen Sie es mit tools oder disallowed_tools. Soll der Agent nur mit einem festen Satz von Tools arbeiten, kombinieren Sie allowed_tools mit permission_mode="dontAsk", das alles verweigert, was sonst eine Rückfrage auslösen würde.

Noch ein Detail: Unter macOS, Linux und WSL gehören Glob und Grep nicht zu den Standard-Tools (unter Windows schon). Dort sucht Claude stattdessen mit find und grep über das Bash-Tool. Wenn Sie eines der beiden in tools oder allowed_tools nennen, stehen sie wieder zur Verfügung (offizielle Tool-Referenz).

Eigene Tools erstellen

Wenn die integrierten Tools nicht ausreichen, können Sie eigene Tools erstellen. Erstellen wir beispielsweise ein Tool, das mit einer Wetter-API verbunden ist.

Python-Version

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool(
    "get_weather",
    "Aktuelles Wetter einer bestimmten Stadt abrufen",
    {"city": str}
)
async def get_weather(args: dict) -> dict:
    city = args["city"]
    # In der Praxis wird die API aufgerufen
    weather_data = await fetch_weather_api(city)
    return {
        "content": [
            {"type": "text", "text": f"Wetter in {city}: {weather_data}"}
        ]
    }

weather_server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_weather]
)

TypeScript-Version

import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getWeather = tool(
  "get_weather",
  "Aktuelles Wetter einer bestimmten Stadt abrufen",
  { city: z.string().describe("Stadtname") },
  async (args) => {
    const data = await fetchWeatherApi(args.city);
    return {
      content: [{ type: "text", text: `Wetter in ${args.city}: ${data}` }]
    };
  }
);

Benutzerdefinierte Tools werden als MCP-Server erstellt und dem Agenten über mcp_servers (TS: mcpServers) übergeben. Der vollständige Name jedes Tools lautet dann mcp__servername__toolname; damit es ohne Rückfrage läuft, tragen Sie diesen Namen in allowed_tools ein:

options=ClaudeAgentOptions(
    mcp_servers={"weather": weather_server},
    allowed_tools=["mcp__weather__get_weather"],
)

Löst Ihr Tool eine Exception aus, stoppt die Agentenschleife nicht. Der MCP-Server des SDK fängt sie ab und gibt die Exception-Meldung unverändert als Fehlerergebnis an Claude weiter. Fangen Sie den Fehler selbst ab und geben "is_error": True (TypeScript: isError: true) zurück, formulieren Sie die Meldung, die Claude liest, selbst – etwa welche Anfrage fehlschlug und was stattdessen zu versuchen ist. In beiden Fällen kann Claude es erneut versuchen, ein anderes Tool nutzen oder den Fehler erklären (offizielle Dokumentation: benutzerdefinierte Tools).

Parallelverarbeitung mit Subagenten

Große Aufgaben lassen sich effizient bearbeiten, indem sie in Subagenten aufgeteilt und parallel ausgeführt werden. Spezialisierte Aufgaben können an andere Agenten delegiert werden, ohne den Kontext (Speicher) des Hauptagenten zu belasten.

Wann sind Subagenten sinnvoll?

• Ausführung vieler Tests: Selbst bei umfangreichen Testprotokollen wird der Hauptkontext nicht beeinflusst
• Parallele Recherche: Mehrere Module gleichzeitig untersuchen und nur die Ergebnisse erhalten
• Trennung spezialisierter Aufgaben: „Code-Review“ und „Testausführung“ an separate Agenten delegieren

Benutzerdefinierte Subagenten in Claude Code

In Claude Code (CLI) können Sie benutzerdefinierte Subagenten definieren, indem Sie einfach eine Markdown-Datei in .claude/agents/ ablegen.

# .claude/agents/reviewer.md
---
name: code-reviewer
description: Auf Code-Review spezialisierter Agent
tools: Read, Glob, Grep
model: sonnet
---

Sie sind ein Senior Code-Reviewer.
Führen Sie ein Review unter den Gesichtspunkten
Codequalität, Sicherheit und Best Practices durch.

Durch die Einschränkung des Tool-Zugriffs (im obigen Beispiel nur Lese-Tools) wird verhindert, dass der Reviewer versehentlich Code ändert.

Berechtigungen, Hooks und Sessions

Diese drei Punkte zählen am meisten, sobald ein Agent in Produktion läuft. Die offizielle Dokumentation führt alle drei unter den Claude-Code-Funktionen auf, die im SDK verfügbar sind.

Berechtigungen: Jeder Aufruf wird in fester Reihenfolge geprüft

Fordert Claude ein Tool an, prüft das SDK Hooks → Verbotsregeln → Rückfrageregeln → Berechtigungsmodus → Erlaubnisregeln → den Callback can_use_tool in genau dieser Reihenfolge. Ein Aufruf, der auf eine Verbotsregel passt (etwa aus disallowed_tools), wird selbst im Modus bypassPermissions blockiert. Eine Ausnahme: Ein Mod (ein Plugin, dessen Hooks Funktionen sind) läuft auch in Agent-SDK-Sitzungen, die ihn laden (offizielle Dokumentation), und ein Mod, der auf tool.check antwortet, kann einen Aufruf genehmigen, den eine Verbotsregel abgelehnt hat – außer auf Rechnern mit verwalteten Einstellungen oder bei Anmeldung mit einem Team- oder Enterprise-Plan (offizielle Dokumentation). Installieren Sie Mods nur von Autoren, denen Sie vertrauen; Details in Claude Code Mods erklärt. Den Modus wählen Sie mit permission_mode (laut offizieller Dokumentation, Stand September 2026):

Hooks: Eigenen Code an wichtigen Stellen ausführen

Hooks sind Callbacks, die bei Ereignissen ausgelöst werden – etwa bevor ein Tool läuft (PreToolUse), danach (PostToolUse) oder wenn die Ausführung endet (Stop). Sie laufen vor der Berechtigungsprüfung; eine Aktion, die in jedem Modus blockiert werden soll, gehört also hierher. Dieses Beispiel, gekürzt aus der offiziellen Dokumentation, blockiert Schreibzugriffe auf .env-Dateien:

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")
    if file_path.split("/")[-1] == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)

Sessions: Dort weitermachen, wo Sie aufgehört haben, oder abzweigen

Das SDK speichert den Gesprächsverlauf (Prompts, Tool-Aufrufe, Ergebnisse und Antworten) automatisch als Session auf der Festplatte. Merken Sie sich die session_id aus der Ergebnisnachricht und übergeben Sie sie beim nächsten query() an resume: Der Agent arbeitet dann mit den bereits gelesenen Dateien und getroffenen Entscheidungen weiter. Für die jüngste Session nutzen Sie continue_conversation=True (TS: continue: true); um einen anderen Ansatz zu testen, ohne das Original zu verändern, fork_session=True (TS: forkSession: true). Sessions speichern nur das Gespräch; Dateiänderungen werden nicht zurückgesetzt (offizielle Dokumentation: Sessions).

Darüber hinaus werden Skills, Befehle und Memory aus dem .claude/-Verzeichnis Ihres Projekts und aus ~/.claude/ automatisch geladen, genau wie in Claude Code. Plugins, die Skills, Agenten, Hooks und MCP-Server bündeln, lassen sich über einen lokalen Pfad laden.

Agent SDK vs Client SDK vs Claude Code

Der offizielle Vergleich nennt vier Wege, mit Claude zu entwickeln: das Agent SDK, die Claude Code CLI, das Client SDK und Managed Agents. Wir beginnen mit den dreien, die Sie auf Ihrem eigenen Rechner oder Server betreiben.

So wählen Sie:

• Tägliche Entwicklungsarbeit → Claude Code CLI
• Automatisierungssystem aufbauen → Agent SDK
• Eigene KI-App entwickeln → Client SDK
• Auch den Betrieb von Schleife und Sandbox abgeben → Managed Agents (ein von Anthropic gehosteter Agent, der Sessions in einer von Anthropic verwalteten Cloud-Sandbox oder einer selbst gehosteten Sandbox ausführt; nutzbar über das SDK Ihrer Sprache, die ant CLI oder die REST-API)

Praktische Anwendungsbeispiele

Automatisierung der Code-Entwicklung

Der häufigste Anwendungsfall. Wenn Sie sagen „Implementiere dieses Feature“, untersucht der Agent die Dateistruktur, schreibt Code und führt sogar Tests aus.

# Automatisierte Bugbehebung
async for msg in query(
    prompt="Die Tests des Auth-Moduls schlagen fehl. Finde die Ursache und behebe sie",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Grep"],
        max_turns=20,
        max_budget_usd=2.00,  # Kostenlimit 2$
    ),
):
    pass

Integration in CI/CD-Pipelines

In Kombination mit Tools wie GitHub Actions können Sie Workflows erstellen, die bei jedem PR automatisch Code-Reviews durchführen oder bei fehlgeschlagenen Tests automatische Korrekturen versuchen.

Datenanalyse und Recherche

Auch mehrstufige Rechercheaufgaben wie „Analysiere die Fehlermuster in den Logs des letzten Monats“ können dem Agenten übertragen werden. In Kombination mit dem WebSearch-Tool lassen sich auch aktuelle Informationen einbeziehen.

Best Practices

1. Vergessen Sie die Kostenkontrolle nicht

Da der Agent in einer Schleife arbeitet, kann er mehr Tokens verbrauchen als erwartet. Setzen Sie immer max_budget_usd oder max_turns.

options=ClaudeAgentOptions(
    max_budget_usd=5.00,   # Stoppt bei 5$
    max_turns=30,           # Stoppt nach 30 Turns
    effort="medium",        # Reasoning-Tiefe (low/medium/high/xhigh/max)
)

xhigh wird bei Modellen, die es nicht unterstützen, als high behandelt. Beendet ein Limit den Lauf, hat die letzte Ergebnisnachricht den subtype "error_max_budget_usd" (bei max_budget_usd) bzw. "error_max_turns" (bei max_turns), und result ist leer (None). Am subtype erkennen Sie, warum der Agent angehalten hat.

Beachten Sie: Der Betrag ist eine Schätzung, die das SDK aus einer mitgelieferten Preistabelle berechnet, nicht Ihre tatsächliche Rechnung. Das Budget zählt nur die Ausgaben dieses Aufrufs; frühere Ausgaben einer mit resume fortgesetzten Session zählen nicht mit. Verbindliche Zahlen liefern die Usage-Seite der Claude Console oder die Usage and Cost API (offizielle Dokumentation: Kostenverfolgung).

2. Halten Sie die Tools minimal

Damit Claude unnötige Tools gar nicht erst sieht, listen Sie in tools nur die benötigten auf oder entfernen Sie Tools per bloßem Namen in disallowed_tools. allowed_tools spart nur die Rückfrage ein; die verfügbaren Tools schränkt es nicht ein. Halten Sie auch die Liste der automatisch genehmigten Tools so klein, wie es die Aufgabe erlaubt.

3. Tool-Fehler mit is_error melden

Eine Exception in einem benutzerdefinierten Tool stoppt die Agentenschleife nicht: Das SDK gibt die Exception-Meldung als Fehlerergebnis an Claude weiter. Eine rohe Exception-Meldung reicht Claude aber nicht immer, um den nächsten Schritt zu entscheiden. Fangen Sie sie selbst ab und geben Sie "is_error": True (TypeScript: isError: true) zusammen mit einer Beschreibung zurück, was fehlschlug und was stattdessen zu versuchen ist – dann kann Claude sich leichter wieder fangen.

4. Lagern Sie aufwändige Verarbeitung an Subagenten aus

Übertragen Sie Verarbeitungen mit großer Ausgabe wie Testausführungen oder Log-Analysen an Subagenten. So wird der Kontext des Hauptagenten nicht überlastet.

5. Formulieren Sie Prompts präzise

Statt „Verbessere den Code“ sagen Sie „Füge Rate Limiting zur Login-Funktion in auth.py hinzu und schreibe auch Tests dafür“. Konkrete Anweisungen ermöglichen dem Agenten effizientes Arbeiten.

Zusammenfassung

Das Claude Agent SDK ist ein Framework, das die Einstiegshürde in die KI-Agenten-Entwicklung erheblich senkt. Mit dem gleichen Motor wie Claude Code können Sie in Python oder TypeScript Agenten erstellen, die eigenständig Aufgaben ausführen.

Beginnen Sie damit, die Arbeitsweise eines Agenten interaktiv mit Claude Code kennenzulernen, und wechseln Sie zum Agent SDK, wenn Automatisierungsbedarf entsteht — dieser schrittweise Ansatz ist empfehlenswert.

Wenn Sie Loop, Sandbox und Status nicht selbst betreiben möchten, ist die vollständig verwaltete Alternative von Anthropic Claude Managed Agents.

Einen Überblick über die grundlegende Nutzung von Claude finden Sie auch unter Claudes Chat, Cowork und Code im Vergleich.