Claude Code Agent SDK: Der vollständige Entwicklerleitfaden 2026

Anthropics Agent SDK verwandelt Claude Code von einem Terminal-Assistenten in einen programmierbaren, automatisierbaren KI-Agenten, den du in deine eigenen Workflows einbetten kannst. Dieser Leitfaden deckt alles ab: Installation, den Agenten-Loop, Tool-Integration, MCP-Server, Subagent-Orchestrierung und die Fähigkeitslücken, die du für den produktiven Einsatz schließen musst.

Was ist das Claude Code Agent SDK?

Das Claude Code Agent SDK (auch Claude Agent SDK oder Claude Code SDK genannt) ist Anthropics Python- und TypeScript-Bibliothek zum Erstellen autonomer KI-Agenten auf Basis von Claude. Es kapselt denselben Agenten-Loop, dasselbe Tool-System und dieselbe isolierte Ausführungsumgebung, die auch Claude Code als CLI antreiben, und stellt sie als SDK bereit, das du aus deinem eigenen Code aufrufen kannst.

Das SDK wurde Anfang 2026 veröffentlicht, als Teil von Anthropics Bestrebung, KI-Agenten programmierbar zu machen und nicht nur interaktiv.

Was es von der direkten Nutzung der Claude API unterscheidet

Wenn du derzeit die Claude API nutzt und deinen eigenen Agenten-Loop mit manueller Tool-Verarbeitung schreibst, ersetzt das Agent SDK Hunderte Zeilen Boilerplate.

Installation und Einrichtung

Voraussetzungen

• Python 3.10+ oder TypeScript/Node.js 20+
• Anthropic API-Schlüssel oder ein Claude Code Pro/Max/Enterprise-Abonnement
• Claude Code CLI installiert, da das SDK sie als Laufzeitumgebung nutzt

Schritt 1: Claude Code CLI installieren

npm install -g @anthropic-ai/claude-code

Oder verwende den nativen Installer von claude.ai/download.

Schritt 2: Das Agent SDK installieren

Python:

pip install claude-agent-sdk

TypeScript:

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

Schritt 3: Authentifizieren

claude login

Folge dem OAuth-Flow. Dein API-Schlüssel wird lokal gespeichert und vom SDK automatisch verwendet.

Dein erster Agent: Fehlerfinder

Hier ist ein minimaler Python-Agent, der ein Verzeichnis nach Fehlern durchsucht:

from claude_agent_sdk import Agent, tool

@tool
def read_file(path: str) -> str:
    """Eine Datei lesen und ihren Inhalt zurückgeben."""
    with open(path, 'r') as f:
        return f.read()

@tool  
def list_files(directory: str = ".") -> list:
    """Alle Dateien in einem Verzeichnis auflisten."""
    import os
    return os.listdir(directory)

agent = Agent(
    system_prompt="Du bist ein Code-Reviewer. Finde Fehler und schlage Korrekturen vor.",
    tools=[read_file, list_files],
    model="claude-sonnet-4-20250514"
)

result = agent.run("Untersuche den Code in ./src auf Sicherheitsprobleme")
print(result.output)

Was unter der Haube passiert

1. Der Agent erhält die Aufgabe und liest deinen System-Prompt
2. Er ruft list_files("./src") auf, um die Codebasis zu erkennen
3. Er ruft read_file(path) für jede Quelldatei auf
4. Er analysiert den Code mit Claudes Schlussfolgerungsfähigkeit
5. Er gibt Ergebnisse mit Zeilennummern und Korrekturvorschlägen zurück

Das SDK übernimmt den gesamten Loop — du schreibst keine Planen-Handeln-Beobachten-Logik selbst.

Kernkonzepte

Der Agenten-Loop

Aufgabe → Planen → Tool-Aufruf → Ergebnis beobachten → Neu planen → ... → Endgültige Antwort

Jede Iteration:

1. Claude entscheidet, was als Nächstes zu tun ist, also plant
2. Es ruft bei Bedarf Tools auf, also handelt
3. Es erhält die Tool-Ausgaben, also beobachtet es
4. Es entscheidet, ob es fortfahren oder fertig sein soll

Das SDK verwaltet die Kontextfenstergrenzen automatisch durch Komprimierung, also das Zusammenfassen älterer Schritte, und durch Subagent-Delegation.

Tools und der Tool-Decorator

Tools sind Funktionen, die du dem Agenten zur Verfügung stellst. Das SDK bietet mehrere integrierte Tools:

# Integrierte Dateioperationen, automatisch verfügbar
agent = Agent(
    tools=["read", "write", "edit", "glob", "grep", "bash", "task"]
)

Eigene Tools nutzen den @tool-Decorator:

from claude_agent_sdk import tool

@tool
def search_docs(query: str, max_results: int = 5) -> str:
    """Interne Dokumentation nach einer Anfrage durchsuchen."""
    # Deine Such-Implementierung
    return results

agent = Agent(tools=[search_docs])

Subagents: Parallele Verarbeitung

Subagents ermöglichen es dir, unabhängige Claude-Instanzen für parallele Arbeit zu starten:

agent = Agent(
    system_prompt="Du bist ein Tech Lead, der eine Codebasis prüft.",
    tools=["task"]  # aktiviert das Starten von Subagents
)

result = agent.run("""
    Prüfe ./frontend/ und ./backend/ parallel.
    Nutze für jedes Verzeichnis Subagents und führe dann die Ergebnisse zusammen.
""")

Subagents laufen in isolierten Kontexten und liefern Ergebnisse unabhängig zurück. So handhabt Claude Code selbst große Operationen.

MCP-Server-Integration

Das SDK unterstützt Model Context Protocol Server, also externe Dienste, die deinem Agenten Tools bereitstellen:

agent = Agent(
    mcp_servers=[
        {
            "command": "npx",
            "args": ["-y", "@anthropic-ai/mcp-server-filesystem"],
            "env": {"ALLOWED_DIRECTORIES": "/project"}
        }
    ]
)

MCP-Server können Datenbankzugriff, API-Integrationen, Drittanbieterdienste und mehr hinzufügen.

Was das Agent SDK nicht kann und wie du die Lücken schließt

Das Claude Code Agent SDK gibt deinen Agenten Dateizugriff, Shell-Ausführung und Code-Manipulation. Aber es hat fünf große Fähigkeitslücken:

1. Bilderzeugung

Dein Agent kann Code schreiben, der Bild-APIs aufruft, aber er kann Bilder nicht direkt erzeugen oder sehen. Für einen Agenten, der eine UI baut, ein Design prototypisiert oder Dokumentation erstellt, ist das eine echte Einschränkung.

Lösung: Gib deinem Agenten eine Laufzeitumgebung mit Zusatzfunktionen für die Bilderzeugung. Mit nur einer Konfigurationszeile kann dein Agent Bilder aus Text erzeugen, Designs iterieren und die Ergebnisse einbetten.

2. Videoerzeugung

Bei Video ist die Lücke noch größer. Dein Agent kann zwar ffmpeg-Befehle schreiben, aber keinen neuen Videoinhalt erzeugen.

3. Websuche mit belastbaren Ergebnissen

Claude Code Agents können curl oder Fetch-APIs nutzen, aber sie können keine semantische Websuche mit belastbaren, zitierten Ergebnissen durchführen. Das ist wichtig für Recherche-Agenten, Content-Agenten und alle Workflows, die aktuelle Informationen benötigen.

4. Cloud-Speicher und Dateifreigabe

Der Dateisystemzugriff des SDK ist nur lokal. Für Agenten, die Ausgaben speichern, Dateien mit Menschen teilen oder Daten über Sitzungen hinweg behalten müssen, brauchst du Cloud-Speicher.

5. Veröffentlichung und Deployment

Dein Agent erstellt das Artefakt, aber es online zu bringen — eine Webseite, ein teilbarer Bericht oder eine bereitgestellte App — erfordert eine separate Infrastruktur.

Die Lösung mit einem Befehl

Anstatt fünf separate MCP-Server zu konfigurieren, jeweils mit eigenem API-Schlüssel, Pflegeaufwand und Token-Overhead, kannst du eine Capability-Runtime nutzen — ein einzelnes CLI-Tool, das Bilderzeugung, Video, Websuche, Cloud-Speicher und Veröffentlichung hinter einem Endpoint bündelt.

AnyCap gibt Agenten zum Beispiel fünf Fähigkeiten in einem einzigen CLI mit: Bilderzeugung, Video, Websuche, Cloud-Speicher und Seitenveröffentlichung — so verbringst du Minuten mit der Konfiguration statt Stunden.

Überlegungen für den produktiven Einsatz

Kontextfenster-Management

Das Agent SDK übernimmt die Kontextkomprimierung automatisch, aber bei lang laufenden Agenten mit mehr als 100 Schritten solltest du:

• Subagents nutzen für große parallele Aufgaben statt sequentieller Verarbeitung
• System-Prompts knapp halten — jedes Token im System-Prompt ist bei jedem Schritt Overhead
• Große Dateien vermeiden, wenn Tools stattdessen Zusammenfassungen liefern können

Kostenkontrolle

Eine typische Agentensitzung mit dem SDK kostet je nach Aufgabenkomplexität 0,50 bis 3,00 US-Dollar. Um Kosten zu kontrollieren:

• Setze max_turns, um Endlosschleifen zu verhindern
• Verwende Haiku für einfache Subagents und Sonnet für den Hauptagenten
• Überwache die Nutzung über das Dashboard in der Anthropic-Konsole

Sicherheit

Das SDK führt Befehle in einer Sandbox aus, aber du solltest trotzdem:

• Den Dateisystemzugriff mit ALLOWED_DIRECTORIES einschränken
• Produktionsagenten niemals Zugriff auf Anmeldedaten oder .env-Dateien geben
• Agentenaktionen im nicht interaktiven Modus prüfen

Claude Code SDK vs. Claude Agent SDK: Was ist der Unterschied?

Diese Begriffe werden oft gleichbedeutend verwendet, aber es gibt einen Unterschied:

In der Praxis nutzen die meisten Entwickler das Agent SDK als Einstiegspunkt. Die APIs des niedrigeren SDKs sind für fortgeschrittene Anwendungsfälle wie benutzerdefiniertes Sitzungsmanagement gedacht.

Wann man das Agent SDK verwenden sollte statt der Claude Code CLI

Die Faustregel: Wenn du Befehle eintippst, nutze die CLI. Wenn du Code schreibst, der Claude aufrufen soll, nutze das SDK.

Fazit

Das Claude Code Agent SDK verwandelt Claude von einem Terminal-Begleiter in eine programmierbare Agentenlaufzeit. Mit integrierten Dateioperationen, Shell-Zugriff, Subagent-Orchestrierung und MCP-Server-Unterstützung übernimmt es die Schwerarbeit der Agenteninfrastruktur.

Aber ein Agent, der nur Dateien lesen und Bash ausführen kann, ist nur ein halber Agent. Um Agenten zu bauen, die im Web suchen, Bilder und Videos erzeugen, Ergebnisse in der Cloud speichern und Resultate veröffentlichen können, brauchst du eine Fähigkeitsschicht. Das SDK gibt deinem Agenten das Gehirn; eine Capability-Runtime wie AnyCap gibt ihm Augen, Hände und eine Stimme.