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 ein Framework, mit dem Sie KI-Agenten in Python oder TypeScript entwickeln können, die Claude als Gehirn nutzen. Dieselbe Technologie steckt auch hinter Claude Code (Anthropics offizielle CLI).

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 das offizielle Agenten-Entwicklungsframework von Anthropic. Sie können denselben Motor, der Claude Code antreibt, programmatisch nutzen.

Die wichtigsten Merkmale sind:

Von den drei Modi von Claude: Chat, Cowork und Code basiert der Code-Modus (Claude Code) auf der Technologie des Agent SDK.

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

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)
            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.

Liste der integrierten Tools

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

Diese Tools können einfach durch Angabe in allowed_tools verwendet werden. Sie müssen keinen eigenen Code für die Tool-Verarbeitung schreiben.

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 mit dem Agenten verbunden. Bei Fehlern sollte isError: true zurückgegeben werden statt eine Exception auszulösen. So wird die Agentenschleife nicht unterbrochen und Claude kann einen Retry oder einen anderen Ansatz versuchen.

Parallelverarbeitung mit Sub-Agenten

Große Aufgaben lassen sich effizient bearbeiten, indem sie in Sub-Agenten 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 Sub-Agenten 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 Sub-Agenten in Claude Code

In Claude Code (CLI) können Sie benutzerdefinierte Sub-Agenten 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.

Agent SDK vs Client SDK vs Claude Code

Claude bietet drei Schnittstellen für Entwickler. Jede hat ihre Stärken — wählen Sie je nach Ihrem Ziel.

So wählen Sie:

• Tägliche Entwicklungsarbeit → Claude Code CLI
• Automatisierungssystem aufbauen → Agent SDK
• Eigene KI-App entwickeln → Client SDK

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/max)
)

2. Halten Sie die Tools minimal

Unnötige Tool-Berechtigungen verbrauchen das Kontextfenster. Geben Sie in allowed_tools nur die für die Aufgabe benötigten Tools an.

3. Fehlerbehandlung mit isError

Wenn in einem benutzerdefinierten Tool eine Exception geworfen wird, stoppt die gesamte Agentenschleife. Geben Sie stattdessen isError: true zurück, damit Claude eine Wiederherstellung versuchen kann.

4. Lagern Sie aufwändige Verarbeitung an Sub-Agenten aus

Übertragen Sie Verarbeitungen mit großer Ausgabe wie Testausführungen oder Log-Analysen an Sub-Agenten. 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.

Einen Überblick über die grundlegende Nutzung von Claude finden Sie auch unter Detailvergleich der drei Claude-Tabs: Chat, Cowork und Code.