Claude Code Agent SDK: Der komplette Einsteiger-Guide zum Erstellen von KI-Agenten (2026)

Möchten Sie Ihren ersten KI-Agenten bauen, wissen aber nicht, wo Sie anfangen sollen?

Das Claude Code Agent SDK von Anthropic macht es möglich – auch ohne tiefe Programmierkenntnisse. In diesem umfassenden Guide zeigen wir Ihnen Schritt für Schritt, wie Sie autonome KI-Agenten erstellen, die selbstständig komplexe Aufgaben erledigen können.

---

Was Sie in diesem Guide lernen werden — Claude Code Agent SDK

• Was KI-Agenten sind und wie sie sich von Chatbots unterscheiden
• Wie das Claude Code Agent SDK funktioniert
• Praktische Code-Beispiele für Ihren ersten Agenten
• Tools, Subagenten und MCP-Integration
• Best Practices für produktionsreife Agenten

---

Was ist ein KI-Agent? (Und warum ist er anders als ChatGPT?)

Bevor wir in den Code einsteigen, klären wir ein grundlegendes Konzept: Was unterscheidet einen KI-Agenten von einem gewöhnlichen Chatbot?

Chatbot vs. Agent

Ein Chatbot antwortet auf Ihre Fragen. Ein KI-Agent arbeitet selbstständig an einem Ziel, nutzt dabei verschiedene Werkzeuge und trifft eigene Entscheidungen.

Die Agent-Schleife (Agent Loop)

Jeder KI-Agent folgt einem fundamentalen Muster – der sogenannten Agent Loop:

┌─────────────────────────────────────────────────────────────┐
│                    AGENT LOOP PATTERN                       │
├─────────────────────────────────────────────────────────────┤
│  1. KONTEXT SAMMELN                                         │
│     └─▶ Verstehe die Aufgabe, lese relevante Daten          │
│                                                             │
│  2. AKTION AUSFÜHREN                                        │
│     └─▶ Nutze Tools, führe Operationen aus                  │
│                                                             │
│  3. ERGEBNIS ÜBERPRÜFEN                                     │
│     └─▶ War die Aktion erfolgreich?                         │
│                                                             │
│  4. WIEDERHOLEN                                             │
│     └─▶ Bis das Ziel erreicht ist                           │
└─────────────────────────────────────────────────────────────┘

Beispiel: Sie bitten einen Agenten, eine Reise zu planen. Der Agent:

1. Sammelt Kontext: Fragt nach Datum, Budget, Präferenzen
2. Führt Aktionen aus: Sucht Flüge, Hotels, Aktivitäten
3. Überprüft: Passt alles zum Budget? Sind die Zeiten kompatibel?
4. Wiederholt: Bis ein vollständiger Reiseplan steht

---

Was ist das Claude Code Agent SDK?

Das Claude Code Agent SDK ist das gleiche Framework, das Anthropic intern für Claude Code verwendet – ihrem leistungsstarken Coding-Assistenten.

Es bietet alles, was Sie zum Erstellen von produktionsreifen KI-Agenten brauchen:

Kernfunktionen des SDK

Warum Claude Code Agent SDK wählen?

1. Produktionserprobt: Dasselbe System, das Claude Code antreibt
2. Minimaler Boilerplate: Weniger Code, mehr Funktionalität
3. Integrierte Tools: Datei-Operationen, Bash, Web out-of-the-box
4. MCP-native: Nahtlose Integration mit Model Context Protocol

---

Schnellstart: Installation und Setup

Voraussetzungen

• Python 3.10 oder höher
• Anthropic API-Key (von console.anthropic.com)

Schritt 1: SDK installieren

# Mit pip installieren
pip install claude-agent-sdk

# Oder mit uv (empfohlen für schnellere Installation)
uv pip install claude-agent-sdk

Schritt 2: API-Key konfigurieren

# Als Umgebungsvariable setzen
export ANTHROPIC_API_KEY="sk-ant-..."

# Oder in einer .env Datei
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env

Schritt 3: Erste Verbindung testen

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

async def test_connection():
    options = ClaudeAgentOptions(
        model="sonnet",  # Claude Sonnet 4
        system_prompt="Du bist ein hilfreicher Assistent."
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Sage Hallo!")
        async for message in client.receive_response():
            print(message)

# Ausführen
import asyncio
asyncio.run(test_connection())

---

Praktisches Beispiel 1: Einfacher Q&A-Agent

Beginnen wir mit dem einfachsten Agenten – einem, der Fragen beantwortet:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock
import asyncio

SYSTEM_PROMPT = """Du bist ein freundlicher Assistent, der Fragen 
beantwortet. Sei präzise und hilfreich."""

async def simple_qa_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits"  # Erlaubt Lese-Operationen
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🤖 Q&A Agent bereit! (Eingabe 'exit' zum Beenden)\n")
        
        while True:
            user_input = input("Sie: ").strip()
            
            if user_input.lower() in ['exit', 'quit', 'ende']:
                print("Auf Wiedersehen!")
                break
            
            await client.query(user_input)
            
            print("Agent: ", end="")
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="")
            print("\n")

if __name__ == "__main__":
    asyncio.run(simple_qa_agent())

Was dieser Code macht:

1. Erstellt einen Client mit System-Prompt
2. Startet eine interaktive Schleife
3. Sendet Benutzereingaben an Claude
4. Streamt die Antwort zurück

---

Praktisches Beispiel 2: Agent mit Gedächtnis (Memory)

Ein Agent mit Konversationsgedächtnis kann sich an vorherige Nachrichten erinnern:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock
import asyncio

SYSTEM_PROMPT = """Du bist ein Assistent mit Gedächtnis. 
Du erinnerst dich an alles, was in dieser Konversation gesagt wurde.
Beziehe dich auf frühere Aussagen, wenn relevant."""

async def memory_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        # Das SDK verwaltet den Konversationsverlauf automatisch!
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🧠 Memory Agent bereit!\n")
        print("Tipp: Stelle Fragen, die sich auf frühere Antworten beziehen.\n")
        
        while True:
            user_input = input("Sie: ").strip()
            
            if not user_input:
                continue
                
            if user_input.lower() == 'exit':
                break
            
            await client.query(user_input)
            
            print("Agent: ", end="")
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(block.text, end="", flush=True)
            print("\n")

if __name__ == "__main__":
    asyncio.run(memory_agent())

Testen Sie das Gedächtnis:

Sie: Mein Name ist Max.
Agent: Hallo Max! Freut mich, dich kennenzulernen.

Sie: Was ist mein Name?
Agent: Dein Name ist Max – du hast dich gerade vorgestellt!

---

Praktisches Beispiel 3: Agent mit Tools

Hier wird es interessant! Agenten mit Tools können echte Aktionen ausführen:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock, ToolUseBlock
import asyncio

SYSTEM_PROMPT = """Du bist ein Forschungsassistent mit Zugriff auf Tools.
Nutze die verfügbaren Tools, um Aufgaben zu erledigen:

- WebFetch: Ruft Webseiten-Inhalte ab
- Read: Liest lokale Dateien
- Grep: Durchsucht Dateien nach Mustern
- Glob: Findet Dateien nach Mustern

Erkläre immer, welches Tool du nutzt und warum."""

async def tool_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=[
            "WebFetch",  # Web-Inhalte abrufen
            "Read",      # Dateien lesen
            "Grep",      # Text durchsuchen
            "Glob",      # Dateien finden
        ]
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("🔧 Tool Agent bereit!")
        print("Befehle: 'recherchiere [URL]', 'finde [Datei]', etc.\n")
        
        while True:
            user_input = input("Sie: ").strip()
            
            if user_input.lower() == 'exit':
                break
            
            await client.query(user_input)
            
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(f"Agent: {block.text}")
                        elif isinstance(block, ToolUseBlock):
                            print(f"🛠️ Nutze Tool: {block.name}")
                            print(f"   Parameter: {block.input}")
            print()

if __name__ == "__main__":
    asyncio.run(tool_agent())

Verfügbare Built-in Tools

---

Praktisches Beispiel 4: Autonomer Reiseplaner-Agent

Jetzt bauen wir einen vollständig autonomen Agenten:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
from claude_agent_sdk.types import TextBlock, ToolUseBlock, ToolResultBlock
import asyncio
import json

TRAVEL_SYSTEM_PROMPT = """Du bist ein autonomer Reiseplanungs-Agent.

DEIN ZIEL: Erstelle einen vollständigen Reiseplan basierend auf den 
Benutzeranforderungen.

DEIN WORKFLOW:
1. Sammle alle notwendigen Informationen (Datum, Budget, Präferenzen)
2. Recherchiere Optionen mit WebFetch
3. Erstelle einen strukturierten Reiseplan
4. Präsentiere den Plan und frage nach Feedback

WICHTIG:
- Frage ZUERST nach fehlenden Informationen
- Nutze WebFetch für aktuelle Informationen
- Erstelle einen klaren, strukturierten Plan
- Biete Alternativen an

Beginne IMMER mit einer freundlichen Begrüßung und frage nach dem Reiseziel."""

async def travel_planner_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=TRAVEL_SYSTEM_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=["WebFetch", "Read", "Write"],
        max_turns=20  # Erlaubt längere Agent-Schleifen
    )
    
    async with ClaudeSDKClient(options=options) as client:
        print("✈️ Reiseplaner-Agent gestartet!")
        print("=" * 50)
        
        # Initiale Begrüßung durch den Agenten
        await client.query("Starte die Reiseplanung für einen neuen Kunden.")
        
        async for message in client.receive_response():
            if hasattr(message, 'content'):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Agent: {block.text}")
        print()
        
        # Interaktive Schleife
        while True:
            user_input = input("Sie: ").strip()
            
            if user_input.lower() in ['exit', 'fertig', 'danke']:
                print("Agent: Gerne! Ich wünsche Ihnen eine wunderbare Reise! 🌍✨")
                break
            
            await client.query(user_input)
            
            async for message in client.receive_response():
                if hasattr(message, 'content'):
                    for block in message.content:
                        if isinstance(block, TextBlock):
                            print(f"Agent: {block.text}")
                        elif isinstance(block, ToolUseBlock):
                            print(f"🔍 Recherchiere: {block.name}...")
            print()

if __name__ == "__main__":
    asyncio.run(travel_planner_agent())

---

Erweiterte Funktionen: MCP-Integration

Das Model Context Protocol (MCP) ermöglicht die Integration externer Dienste:

MCP-Server einbinden

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# MCP-Server-Konfiguration
MCP_CONFIG = {
    "utils": {
        "command": "npx",
        "args": ["-y", "mcp-remote", "https://your-mcp-server.com/api"]
    }
}

async def mcp_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt="Du hast Zugriff auf MCP-Tools für erweiterte Funktionen.",
        permission_mode="acceptEdits",
        allowed_tools=[
            "WebFetch",
            "mcp__utils__save_note",   # MCP-Tools werden mit Prefix versehen
            "mcp__utils__find_note",
        ],
        mcp_servers=MCP_CONFIG
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query("Erstelle eine Notiz mit dem Titel 'Wichtig'")
        # ...

Eigenen MCP-Server erstellen

# mcp_server.py - Einfacher MCP-Server
from mcp import Server

server = Server("my-tools")

@server.tool(name="save_note")
async def save_note(title: str, content: str) -> dict:
    """Speichert eine Notiz."""
    # Ihre Logik hier
    return {"status": "success", "id": "note_123"}

@server.tool(name="find_note")
async def find_note(pattern: str) -> dict:
    """Findet Notizen nach Muster."""
    # Ihre Logik hier
    return {"notes": [...]}

if __name__ == "__main__":
    import asyncio
    asyncio.run(server.run())

---

Subagenten: Spezialisierte Unter-Agenten

Für komplexe Aufgaben können Sie Subagenten einsetzen – spezialisierte Agenten, die Teilaufgaben übernehmen:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

ORCHESTRATOR_PROMPT = """Du bist ein Koordinator, der Aufgaben an 
spezialisierte Subagenten delegiert:

- Recherche-Agent: Für Informationssuche
- Schreib-Agent: Für Content-Erstellung
- Analyse-Agent: Für Datenanalyse

Delegiere Aufgaben entsprechend ihrer Art."""

async def orchestrator_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt=ORCHESTRATOR_PROMPT,
        permission_mode="acceptEdits",
        allowed_tools=["SubAgent", "Read", "Write"],
        subagents_enabled=True  # Aktiviert Subagenten
    )
    
    async with ClaudeSDKClient(options=options) as client:
        await client.query(
            "Recherchiere die neuesten KI-Trends und erstelle einen Report."
        )
        # Der Agent delegiert automatisch an Subagenten

Wann Subagenten nutzen?

---

Hooks: Event-basierte Workflows

Hooks ermöglichen automatisierte Aktionen bei bestimmten Events:

from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher

# Hook-Funktion definieren
async def log_tool_usage(event):
    """Loggt jede Tool-Nutzung."""
    print(f"📝 Log: Tool '{event.tool_name}' wurde aufgerufen")
    return True  # Erlaubt die Ausführung

async def block_dangerous_commands(event):
    """Blockiert gefährliche Bash-Befehle."""
    dangerous = ['rm -rf', 'sudo', 'chmod 777']
    if any(cmd in str(event.arguments) for cmd in dangerous):
        print("⚠️ Gefährlicher Befehl blockiert!")
        return False  # Blockiert die Ausführung
    return True

async def hook_agent():
    options = ClaudeAgentOptions(
        model="sonnet",
        system_prompt="Du bist ein Assistent mit Sicherheits-Hooks.",
        permission_mode="acceptAll",
        allowed_tools=["Bash", "Write", "Read"],
        hooks={
            "PreToolUse": [
                HookMatcher(hooks=[log_tool_usage]),
                HookMatcher(
                    tool_name="Bash",
                    hooks=[block_dangerous_commands]
                )
            ]
        }
    )
    
    async with ClaudeSDKClient(options=options) as client:
        # ...

Hook-Typen

---

Best Practices für produktionsreife Agenten

1. Klare System-Prompts

# ❌ Schlecht: Vage Anweisungen
SYSTEM_PROMPT = "Sei hilfreich."

# ✅ Gut: Klare Rolle, Grenzen und Verhalten
SYSTEM_PROMPT = """Du bist ein Kundenservice-Agent für TechCorp.

DEINE ROLLE:
- Beantworte Fragen zu unseren Produkten
- Leite komplexe Anfragen an Menschen weiter
- Dokumentiere alle Interaktionen

GRENZEN:
- Keine Preisverhandlungen
- Keine technischen Änderungen ohne Genehmigung
- Bei Unsicherheit: Frage nach

VERHALTEN:
- Freundlich und professionell
- Antworte in der Sprache des Kunden
- Fasse komplexe Themen zusammen"""

2. Berechtigungen granular setzen

# ❌ Schlecht: Alles erlauben
permission_mode = "acceptAll"

# ✅ Gut: Nur notwendige Tools erlauben
permission_mode = "acceptEdits"
allowed_tools = ["Read", "WebFetch"]  # Nur was wirklich nötig ist

3. Fehlerbehandlung implementieren

async def resilient_agent():
    max_retries = 3
    
    for attempt in range(max_retries):
        try:
            async with ClaudeSDKClient(options=options) as client:
                await client.query(prompt)
                async for message in client.receive_response():
                    # Verarbeitung
                    pass
                break  # Erfolgreich, Schleife verlassen
                
        except RateLimitError:
            wait_time = 2 ** attempt  # Exponentielles Backoff
            print(f"Rate Limit erreicht. Warte {wait_time}s...")
            await asyncio.sleep(wait_time)
            
        except Exception as e:
            print(f"Fehler: {e}")
            if attempt == max_retries - 1:
                raise

4. Kontext-Management

# Bei langen Konversationen: Kontext komprimieren
options = ClaudeAgentOptions(
    model="sonnet",
    system_prompt=SYSTEM_PROMPT,
    # SDK komprimiert automatisch bei Bedarf
    max_context_tokens=100000,  # Maximale Kontextgröße
)

---

Kosten und Modell-Auswahl

Verfügbare Modelle

Modell-Empfehlung nach Anwendung

---

Zusammenfassung: Ihr Weg zum ersten Agenten

Checkliste für den Start

• Python 3.10+ installiert
• Anthropic API-Key erstellt
• claude-agent-sdk installiert
• Einfachen Q&A-Agent getestet
• Agent mit Memory ausprobiert
• Tools hinzugefügt
• Autonomen Agent gebaut

Nächste Schritte

1. Experimentieren: Starten Sie mit dem einfachen Q&A-Agent
2. Erweitern: Fügen Sie Tools nach Bedarf hinzu
3. Spezialisieren: Erstellen Sie domänenspezifische Agenten
4. Skalieren: Nutzen Sie Subagenten für komplexe Workflows
5. Absichern: Implementieren Sie Hooks für Produktionsumgebungen

---

Häufig gestellte Fragen (FAQ)

Was ist der Unterschied zwischen Claude Code und dem Claude Agent SDK?

Claude Code ist Anthropics vollständiger Coding-Assistent – ein fertiges Produkt, das Sie in Ihrem Terminal nutzen können.

Das Claude Agent SDK ist das darunterliegende Framework, mit dem Sie eigene Agenten für beliebige Anwendungsfälle bauen können. Das SDK gibt Ihnen die Bausteine, die auch Claude Code antreiben.

Brauche ich Programmierkenntnisse für das SDK?

Grundlegende Python-Kenntnisse sind hilfreich, aber nicht zwingend erforderlich. Die einfachen Beispiele in diesem Guide können Sie auch ohne tiefe Programmiererfahrung nachbauen.

Für produktionsreife Agenten empfehlen wir jedoch solide Python-Grundlagen.

Wie viel kostet die Nutzung des Claude Agent SDK?

Die SDK-Nutzung selbst ist kostenlos. Sie zahlen nur für die API-Aufrufe an Claude.

Sonnet kostet etwa $3 pro Million Input-Tokens und $15 pro Million Output-Tokens (Stand Januar 2026). Für Entwicklung und Tests empfehlen wir, mit kleinen Kontexten zu starten.

Kann ich das SDK mit anderen KI-Modellen nutzen?

Das Claude Agent SDK ist speziell für Claude-Modelle optimiert. Für andere Modelle wie GPT-4 oder Gemini gibt es alternative SDKs wie OpenAI Agents SDK oder Google ADK.

Die Konzepte (Agent Loop, Tools, Memory) sind jedoch übertragbar.

Wie sichere ich meinen Agenten für den Produktionseinsatz?

Drei wichtige Schritte:

1. Setzen Sie permission_mode auf "manual" oder "acceptEdits" statt "acceptAll"
2. Definieren Sie explizit allowed_tools mit nur den wirklich benötigten Tools
3. Implementieren Sie Hooks für Sicherheitsprüfungen und Logging

Für kritische Anwendungen fügen Sie Human-in-the-Loop-Genehmigungen hinzu.

---

Weiterführende Ressourcen

• Offizielle Dokumentation: docs.claude.com/en/api/agent-sdk
• Anthropic Engineering Blog: anthropic.com/engineering
• MCP Spezifikation: modelcontextprotocol.io
• Claude Code: anthropic.com/claude-code

---

Hinweis: Dieser Guide wurde für Entwickler und KI-Enthusiasten erstellt, die ihre ersten Schritte mit KI-Agenten machen möchten. Das Claude Code Agent SDK entwickelt sich ständig weiter – besuchen Sie die offizielle Dokumentation für die neuesten Updates.

---