Claude Agent SDK Überblick für Entwickler

1. Was das Claude Agent SDK wirklich ist

Das Claude Agent SDK ist keine weitere Chat-Bibliothek, sondern die produktisierte Version der Agent Loop, die intern in Claude Code läuft. Statt bei jedem eigenen Projekt neu zu entscheiden, wie ein Sprachmodell Werkzeuge aufruft, deren Ergebnisse verarbeitet und entscheidet, ob eine Aufgabe abgeschlossen ist, übernimmt das SDK diese Schleife vollständig. Entwickler bekommen damit dieselbe Grundlage, auf der auch das offizielle Kommandozeilen-Tool basiert, jedoch als einbettbare Bibliothek für eigene Anwendungen in Python und TypeScript.

Der praktische Unterschied zu einem einfachen API-Aufruf ist entscheidend: Ein roher Aufruf der Claude API liefert eine einzelne Antwort auf eine einzelne Anfrage. Ein Agent im Sinne des Claude Agent SDK plant dagegen mehrere Schritte, ruft dabei Werkzeuge auf, liest deren Ergebnisse, passt seinen Plan an und wiederholt diesen Zyklus, bis das Ziel erreicht ist oder ein Limit greift. Für Aufgaben wie automatisiertes Debugging, mehrstufige Datenverarbeitung oder komplexe Code-Migrationen ist genau diese Schleife der entscheidende Baustein, den man mit reinem API-Zugriff jedes Mal neu bauen müsste.

2. Architektur: Agent Loop, Tools und Permissions

Die Architektur des Claude Agent SDK besteht aus drei zusammenhängenden Schichten. Die unterste Schicht ist die Agent Loop selbst: ein Kontrollfluss, der eine Nutzeranfrage entgegennimmt, sie an das Modell sendet, auf Tool-Aufrufe im Antwort-Stream reagiert, diese Aufrufe ausführt und die Ergebnisse zurück in den Kontext einspeist. Diese Schleife läuft so lange, bis das Modell eine finale Textantwort ohne weiteren Tool-Aufruf liefert oder eine konfigurierte maximale Anzahl an Turns erreicht ist.

Die zweite Schicht ist das Tool-System: eine deklarative Beschreibung verfügbarer Funktionen mit Namen, Beschreibung und JSON-Schema für die Parameter. Eingebaute Tools wie Dateisystemzugriff, Shell-Ausführung oder Websuche stehen sofort zur Verfügung, eigene Tools werden über einfache Funktionssignaturen ergänzt. Die dritte Schicht ist das Permission-System, das vor jedem potenziell riskanten Tool-Aufruf, etwa dem Schreiben einer Datei oder dem Ausführen eines Shell-Befehls, eine Entscheidung erzwingt: automatisch erlauben, automatisch verweigern oder an eine Callback-Funktion zur Laufzeitprüfung delegieren. Diese drei Schichten zusammen machen das Claude Agent SDK zu einem vollständigen Framework statt einer bloßen API-Hülle.

# Install the Claude Agent SDK (Python variant)
pip install claude-agent-sdk

# TypeScript / Node.js variant
npm install @anthropic-ai/claude-agent-sdk

# Authenticate via API key (same key as the raw Claude API)
export ANTHROPIC_API_KEY="sk-ant-..."

3. Installation und erstes Agent-Setup

Der Einstieg in das Claude Agent SDK beginnt mit einem minimalen Agenten, der ohne eigene Tools auskommt und lediglich die eingebauten Fähigkeiten für Dateisystemzugriff nutzt. Das Grundmuster: eine Konfiguration mit Systemprompt, erlaubten Tools und einem Arbeitsverzeichnis wird an die Query-Funktion übergeben, die einen asynchronen Stream von Ereignissen zurückgibt. Jedes Ereignis im Stream entspricht einem Schritt der Agent Loop, etwa einem Textblock, einem Tool-Aufruf oder einem Tool-Ergebnis.

Wichtig für den produktiven Einsatz: Die Session-Konfiguration erlaubt es, das Arbeitsverzeichnis explizit auf ein Projektverzeichnis zu begrenzen, sodass der Agent keine Dateien außerhalb dieses Bereichs lesen oder schreiben kann. Diese Eingrenzung ist der erste von mehreren Sicherheitsmechanismen, die im Abschnitt zu Permissions vertieft werden. Für den ersten Test genügt ein einfacher Prompt, der den Agenten bittet, den Inhalt eines Verzeichnisses zusammenzufassen.

# minimal_agent.py - first agent using the Claude Agent SDK
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        system_prompt="You are a concise code review assistant.",
        allowed_tools=["Read", "Grep", "Glob"],
        cwd="./my-project",
        max_turns=8,
    )

    async for event in query(
        prompt="Summarize the structure of this project in five bullet points.",
        options=options,
    ):
        if event.type == "text":
            print(event.text, end="")
        elif event.type == "tool_use":
            print(f"\n[tool] {event.tool_name}({event.tool_input})")

asyncio.run(main())

4. Eigene Tools als Agent-Fähigkeiten definieren

Eingebaute Tools decken generische Fähigkeiten ab, aber der eigentliche Mehrwert des Claude Agent SDK entsteht, sobald eigene Tools projektspezifisches Wissen zugänglich machen. Ein Tool ist im SDK eine annotierte Funktion mit typisierten Parametern und einer klaren Beschreibung, die dem Modell als Entscheidungsgrundlage dient. Aus dieser Signatur generiert das SDK automatisch das JSON-Schema, das dem Modell mitgeteilt wird, ohne dass Entwickler das Schema von Hand pflegen müssen.

Ein realistisches Beispiel für ein internes Entwickler-Tool: eine Funktion, die den Status eines Deployments aus einer internen API abfragt und strukturiert zurückgibt. Entscheidend ist, dass Fehlerfälle innerhalb des Tools sauber behandelt werden, statt eine Exception bis in die Agent Loop durchzureichen. Das Modell erhält stattdessen eine strukturierte Fehlermeldung im Tool-Ergebnis und kann darauf reagieren, etwa indem es eine alternative Strategie vorschlägt.

# custom_tool.py - defining a project-specific tool
from claude_agent_sdk import tool

@tool(
    name="get_deployment_status",
    description="Fetch the current deployment status for a given environment.",
)
async def get_deployment_status(environment: str) -> dict:
    # NOTE: replace with a real internal API call in production
    valid_envs = {"staging", "production"}
    if environment not in valid_envs:
        return {"error": f"Unknown environment: {environment}"}

    # Simulated lookup — swap for httpx.get(...) against the real endpoint
    status_by_env = {"staging": "healthy", "production": "degraded"}
    return {"environment": environment, "status": status_by_env[environment]}

5. Subagents und Orchestrierung mehrerer Agenten

Für komplexe Aufgaben stößt ein einzelner Agent an Grenzen, sobald mehrere unabhängige Teilaufgaben parallel oder mit unterschiedlichem Kontext bearbeitet werden sollen. Das Claude Agent SDK unterstützt dafür Subagents: spezialisierte Agenten mit eigenem Systemprompt, eigenem Tool-Set und eigenem, isoliertem Kontextfenster, die ein übergeordneter Orchestrator-Agent gezielt beauftragt. Ein Subagent für Testabdeckung braucht andere Tools und einen anderen Fokus als ein Subagent für Dokumentation, und beide sollen sich nicht gegenseitig mit irrelevantem Kontext belasten.

Die Orchestrierung funktioniert über ein eigenes Tool, das der Hauptagent aufruft, um einen Subagent-Lauf zu starten und dessen Endergebnis entgegenzunehmen. Der Subagent arbeitet dabei in einem eigenen, vom Hauptagenten getrennten Kontextfenster, sodass lange Zwischenschritte des Subagents das Kontextbudget des Hauptagenten nicht aufbrauchen. Nur das komprimierte Endergebnis fließt zurück. Dieses Muster reduziert nicht nur den Token-Verbrauch, sondern erlaubt auch parallele Ausführung mehrerer Subagents für unabhängige Teilaufgaben, was die Gesamtlaufzeit komplexer Workflows deutlich verkürzt.

6. Context Management bei langen Sessions

Lange Agent-Sessions mit vielen Tool-Aufrufen füllen das Kontextfenster schnell, insbesondere wenn Tools große Datenmengen wie vollständige Dateiinhalte oder API-Antworten zurückgeben. Das Claude Agent SDK bietet dafür eingebaute Mechanismen zur Kontext-Kompression: Ältere Tool-Ergebnisse können automatisch zusammengefasst oder entfernt werden, sobald ein konfigurierbarer Schwellenwert überschritten ist, während der aktuelle Zustand der Aufgabe erhalten bleibt.

Für produktive Anwendungen ist es sinnvoll, dieses Verhalten nicht dem Zufall zu überlassen, sondern die maximale Turn-Zahl und die Kompressionsschwelle explizit zu konfigurieren. Ein Agent, der Code-Reviews über hunderte Dateien durchführt, profitiert von aggressiverer Kompression als ein Agent, der eine einzelne, fokussierte Debugging-Session durchläuft. Wer die Kontextgröße nicht überwacht, riskiert entweder abgeschnittene, unvollständige Antworten oder unnötig hohe API-Kosten durch redundant mitgeschleppten Kontext.

7. Permissions und Sicherheitsmodell

Ein Agent, der Shell-Befehle ausführen oder Dateien schreiben kann, ist ohne Kontrolle ein erhebliches Sicherheitsrisiko, insbesondere wenn er auf Nutzereingaben reagiert, die nicht vollständig vertrauenswürdig sind. Das Claude Agent SDK adressiert das über ein explizites Permission-Modell mit drei Ebenen: eine Allowlist erlaubter Tools, feingranulare Regeln pro Tool-Aufruf, etwa nur Lesezugriff auf ein bestimmtes Verzeichnis, und eine Callback-Funktion, die zur Laufzeit über jeden einzelnen Aufruf entscheidet.

In der Praxis bedeutet das: Bevor der Agent einen Shell-Befehl ausführt, kann eine Callback-Funktion den konkreten Befehl prüfen und beispielsweise destruktive Operationen wie rm -rf blockieren, während harmlose Lesebefehle automatisch durchgelassen werden. Diese Prüfung passiert vor der Ausführung, nicht danach, sodass ein riskanter Befehl gar nicht erst das System erreicht. Für produktive Deployments empfiehlt sich grundsätzlich eine Deny-by-Default-Strategie: nur explizit freigegebene Tools und Pfade sind erlaubt, alles andere wird abgelehnt und dem Nutzer transparent gemeldet.

8. Deployment: von der CLI zum produktiven Dienst

Der Übergang von einem lokalen Experiment zu einem produktiven Dienst erfordert mehr als nur den Aufruf der Query-Funktion in einer Endlosschleife. Ein produktiver Einsatz des Claude Agent SDK braucht persistente Session-Verwaltung, damit ein Nutzer eine Konversation über mehrere HTTP-Requests hinweg fortsetzen kann, ohne dass der gesamte Verlauf bei jedem Request neu übertragen wird. Das SDK unterstützt dafür Session-IDs, mit denen ein laufender Agent-Zustand serverseitig referenziert und fortgesetzt werden kann.

Zusätzlich braucht ein produktiver Dienst Monitoring für Token-Verbrauch pro Session, Timeouts für hängende Tool-Aufrufe und eine Strategie für parallele Anfragen, da jede aktive Agent-Session Rechenzeit und Speicher bindet. Ein bewährtes Muster ist, Agent-Sessions in einer Queue zu verwalten und die Anzahl gleichzeitig laufender Sessions über ein Worker-Pool-Limit zu begrenzen, statt jede eingehende Anfrage sofort und unbegrenzt zu verarbeiten. So bleibt die Kostenkontrolle auch bei schwankender Last erhalten.

// server-agent.ts - session-aware agent endpoint (simplified)
import { query } from "@anthropic-ai/claude-agent-sdk";

interface AgentRequest {
  sessionId?: string;
  prompt: string;
}

export async function handleAgentRequest(req: AgentRequest) {
  const options = {
    sessionId: req.sessionId, // resume an existing session if provided
    allowedTools: ["Read", "Grep"],
    maxTurns: 10,
    permissionMode: "default", // deny-by-default for anything unlisted
  };

  const events = [];
  for await (const event of query({ prompt: req.prompt, options })) {
    events.push(event);
  }
  return events;
}

9. Agent SDK im Vergleich zu Rohem API-Zugriff und Frameworks

Die Entscheidung zwischen dem Claude Agent SDK, einem rohen API-Aufruf und einem generischen Orchestrierungs-Framework hängt von der Komplexität der Aufgabe ab. Ein roher API-Aufruf genügt für einfache, einstufige Anfragen ohne Werkzeugnutzung. Ein generisches Framework mit eigener Agent-Abstraktion bietet mehr Flexibilität über verschiedene Modellanbieter hinweg, verlangt aber selbst gebaute Logik für Dinge, die das Agent SDK bereits nativ mitliefert.

Für Teams, die primär auf Claude als Modell setzen und schnell einen produktionsreifen Agenten bauen wollen, ist das Claude Agent SDK die effizienteste Wahl, weil es Agent Loop, Permission-System und Subagent-Orchestrierung ohne zusätzliche Abstraktionsschicht bereitstellt. Generische Frameworks lohnen sich vor allem dann, wenn ein Wechsel des Modellanbieters ein realistisches Szenario ist oder bereits eine bestehende Infrastruktur auf einem solchen Framework aufbaut.

10. Zusammenfassung

Das Claude Agent SDK kapselt die Agent Loop, das Tool-System und das Permission-Modell, die auch Claude Code intern nutzt, als einbettbare Bibliothek für Python und TypeScript. Eigene Tools werden über typisierte Funktionssignaturen definiert, aus denen das SDK automatisch ein JSON-Schema generiert. Subagents erlauben die Orchestrierung spezialisierter Teilagenten mit eigenem Kontextfenster, was besonders bei komplexen, mehrstufigen Aufgaben Token-Budget spart und parallele Bearbeitung ermöglicht.

Für den produktiven Einsatz braucht es zusätzlich zur reinen SDK-Nutzung eine durchdachte Permission-Strategie nach dem Deny-by-Default-Prinzip, ein aktives Context-Management gegen ausufernde Kontextfenster sowie eine Session-Architektur mit Monitoring für Kosten und Timeouts. Im Vergleich zu rohem API-Zugriff spart das Claude Agent SDK erheblichen Implementierungsaufwand, ohne die Kontrolle über Sicherheit und Verhalten des Agenten zu opfern.

11. FAQ: Claude Agent SDK für Entwickler