Claude Code SDK: Python- und TypeScript-Entwicklerleitfaden

Das Claude Code SDK — jetzt offiziell Claude Agent SDK genannt — ist eine Python- und TypeScript-Bibliothek, mit der Sie Claude als autonomen Agenten in Ihrer eigenen Anwendung ausführen können. Sie geben einen Prompt vor, und der Agent erledigt den Rest: Dateien lesen, Befehle ausführen, Code bearbeiten und iterieren, bis die Aufgabe erledigt ist. Keine Tool-Schleife zum Schreiben, keine Streaming-Infrastruktur zum Verwalten.

Dieser Leitfaden behandelt alles, was Entwickler für den Einstieg benötigen: Installation, die zentrale query()-API, integrierte Tools, Hooks, Sessions, Subagenten, MCP-Integration und die Verwendung der Novita AI LLM-API als Modell-Backend.

Auf einen Blick

• Das Claude Code SDK heißt jetzt Claude Agent SDK (claude-agent-sdk für Python, @anthropic-ai/claude-agent-sdk für TypeScript).
• Eine einzige query()-Funktion ersetzt die manuelle Tool-Ausführungsschleife, die Sie mit dem Anthropic Client SDK benötigen würden.
• Integrierte Tools decken Dateilesen, Bearbeitung, Bash-Ausführung, Websuche und mehr ab — keine Implementierung erforderlich.
• Sessions ermöglichen es Agenten, die Arbeit über mehrere Aufrufe hinweg mit vollständigem Kontext fortzusetzen.
• Hooks ermöglichen die Validierung, Protokollierung oder Blockierung von Tool-Aufrufen an bestimmten Lebenszykluspunkten.
• Der Anthropic-kompatible Endpunkt von Novita AI (https://api.novita.ai/anthropic) ermöglicht die Verwendung hochwertiger Open-Weight-Modelle mit demselben SDK-Code.

Was ist das Claude Code SDK?

Das Claude Code SDK ist eine programmatische Schnittstelle zu den Agent-Fähigkeiten von Claude Code. Es stellt dieselben Tools, die Reasoning-Schleife und das Kontextmanagement bereit, die das Claude Code CLI interaktiv nutzt — jedoch als Bibliothek, die Sie in Ihren eigenen Code importieren und aufrufen.

Anthropic hat es mit der Generation 4.6 in Claude Agent SDK umbenannt, aber der ursprüngliche Suchbegriff „claude code sdk“ beschreibt immer noch zutreffend, worum es sich handelt: die SDK-Schicht, die auf Claude Code aufsetzt und Ihnen die Automatisierung von Agentenaufgaben in Software ermöglicht.

Wofür es geeignet ist:

• Automatisierte Code-Reviews, Refactoring oder Testgenerierung in CI/CD
• Agenten, die Dateien lesen und ändern, Skripte ausführen oder in Ihrem Namen im Web suchen
• Multi-Agent-Pipelines, bei denen ein Koordinator Teilaufgaben an spezialisierte Worker delegiert
• Alle Workflows, bei denen Claude autonome mehrstufige Aktionen ausführen soll, nicht nur einen Prompt beantworten

Wofür es nicht geeignet ist: Wenn Sie die direkte Kontrolle über jede Nachricht, strukturierte Ausgabe aus einem einzelnen Aufruf oder Streaming-Antworten für eine Chat-Oberfläche benötigen, ist das Anthropic Client SDK besser geeignet.

Claude Code SDK vs. Anthropic Client SDK: Wann verwende ich was?

Beide SDKs bauen auf Claude auf, lösen jedoch unterschiedliche Probleme.

	Claude Agent SDK	Anthropic Client SDK
Tool-Ausführung	Wird autonom von Claude erledigt	Sie implementieren die Tool-Schleife
Schnittstelle	query() gibt einen asynchronen Iterator zurück	client.messages.create() gibt ein Antwortobjekt zurück
Integrierte Tools	Read, Write, Edit, Bash, Grep, Glob, WebSearch und mehr	Keine — Sie definieren und führen alle Tools selbst aus
Sessions	Integriert — Fortsetzung mit einer Session-ID	Manuell — Sie verwalten den Konversationsverlauf selbst
Am besten geeignet für	Agentische Pipelines, CI/CD, Dateioperationen	Chat-Apps, strukturierte Ausgabe, feingranulare Steuerung

Wenn Claude selbstständig herausfinden soll, welche Dateien zu lesen und zu bearbeiten sind: Agent SDK. Wenn Claude auf einen bestimmten Prompt antworten und einen von Ihnen verarbeiteten Wert zurückgeben soll: Client SDK.

Installation des Claude Agent SDK

Python (erfordert Python 3.10+):

pip install claude-agent-sdk

TypeScript / Node.js:

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

Das TypeScript-Paket enthält ein natives Claude Code-Binary für Ihre Plattform als optionale Abhängigkeit. Sie müssen Claude Code nicht separat installieren.

Überprüfen Sie Ihre Python-Version vor der Installation:

python3 --version  # macOS/Linux
py --version       # Windows

Wenn pip No matching distribution found for claude-agent-sdk meldet, ist Ihr Python-Interpreter älter als 3.10.

Schritt 1: Authentifizierung konfigurieren

Setzen Sie Ihren Anthropic-API-Schlüssel als Umgebungsvariable:

export ANTHROPIC_API_KEY=your-api-key

Das SDK unterstützt auch Amazon Bedrock, Google Vertex AI und Azure AI Foundry für Teams, die über Cloud-Anbieter routen:

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# plus Standard-AWS-Anmeldedaten

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# plus GOOGLE_CLOUD_PROJECT und gcloud-Anmeldedaten

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# plus Azure-Anmeldedaten

Schritt 2: Erste Agent-Abfrage ausführen

Die gesamte SDK-Oberfläche basiert auf einer einzigen Funktion: query(). Sie akzeptiert einen Prompt und Optionen und gibt einen asynchronen Iterator von Nachrichtenereignissen zurück.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Liste alle Python-Dateien in diesem Verzeichnis auf",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

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

for await (const message of query({
  prompt: "Liste alle Python-Dateien in diesem Verzeichnis auf",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

Der Iterator liefert verschiedene Nachrichtentypen. Die beiden nützlichsten:

• ResultMessage (oder Nachrichten mit einem result-Feld) — die endgültige Antwort des Agenten
• SystemMessage mit subtype === "init" — enthält die session_id für die spätere Fortsetzung

Schritt 3: Berechtigungen mit allowedTools steuern

Das SDK enthält vorimplementierte Tools. Sie legen fest, welche Tools der Agent verwenden darf; Claude übernimmt die Ausführung.

Tool	Funktion
Read	Liest jede Datei im Arbeitsverzeichnis
Write	Erstellt neue Dateien
Edit	Nimmt gezielte Änderungen an vorhandenen Dateien vor
Bash	Führt Shell-Befehle, Skripte, Git-Operationen aus
Glob	Findet Dateien nach Muster (**/*.ts, src/**/*.py)
Grep	Durchsucht Dateiinhalte mit Regex
WebSearch	Durchsucht das Web nach aktuellen Informationen
WebFetch	Ruft Webseiteninhalte ab und parst sie
Monitor	Überwacht ein Hintergrundskript und reagiert auf Ausgabezeilen
AskUserQuestion	Stellt dem Benutzer zwischendurch klärende Fragen
Agent	Ruft einen definierten Subagenten auf

Die Kombination aus Bash + Read + Edit ist für die meisten automatisierten Code-Aufgaben ausreichend. Fügen Sie WebSearch oder WebFetch hinzu, wenn der Agent externe Daten benötigt.

allowed_tools (Python) / allowedTools (TypeScript) genehmigt bestimmte Tools ohne Rückfrage vorab. Die Einschränkung des Tool-Sets begrenzt auch, was der Agent unbeabsichtigt tun kann — eine nützliche Schutzmaßnahme für automatisierte Pipelines.

Schreibgeschützter Code-Review-Agent:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Überprüfe diese Codebasis auf Sicherheitsprobleme und Code-Gerüche",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
    ),
):
    if hasattr(message, "result"):
        print(message.result)

Vollständiger Editier-Agent (genehmigt Dateischreibvorgänge vorab):

options=ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Edit", "Bash"],
    permission_mode="acceptEdits",
)

permission_mode="acceptEdits" genehmigt Dateibearbeitungen automatisch ohne interaktive Rückfrage, was bei der Ausführung in CI erforderlich ist.

Schritt 4: Hooks für Lebenszyklussteuerung verwenden

Hooks ermöglichen die Ausführung von benutzerdefiniertem Code an definierten Punkten der Agentenausführung. Sie können Aktionen protokollieren, Eingaben validieren, gefährliche Operationen blockieren oder den externen Zustand aktualisieren.

Verfügbare Hook-Ereignisse: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, Stop, SubagentStop, SubagentStart, PreCompact, Notification, PermissionRequest

Dieses Beispiel schreibt ein Audit-Protokoll, jedes Mal wenn der Agent eine Datei bearbeitet oder erstellt:

import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now().isoformat()}: modified {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="Refactoriere auth.py zur Verwendung von Dataclasses",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";

const logFileChange: HookCallback = async (input) => {
  const filePath = (input as any).tool_input?.file_path ?? "unknown";
  await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
  return {};
};

for await (const message of query({
  prompt: "Refaktoriere auth.ts zur Verwendung von Interfaces",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Ein PreToolUse-Hook, der { block: true } zurückgibt, verhindert den Tool-Aufruf vollständig — nützlich für die Durchsetzung von Richtlinien wie „niemals Dateien löschen“ in automatisierten Kontexten.

Schritt 5: Arbeit mit Sessions fortsetzen

Sessions bewahren den vollständigen Kontext des Agenten — welche Dateien er gelesen hat, was er gefunden hat, den Konversationsverlauf — über mehrere query()-Aufrufe hinweg. Dies ermöglicht die Aufteilung einer langen Aufgabe in Schritte oder die Fortsetzung einer unterbrochenen Arbeit.

Um eine Session fortzusetzen, erfassen Sie die session_id aus dem SystemMessage-Init-Ereignis und übergeben sie an resume:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, SystemMessage, ResultMessage

async def main():
    session_id = None

    # Erste Abfrage: Codebasis lesen und analysieren
    async for message in query(
        prompt="Lies das Authentifizierungsmodul und identifiziere alle externen Abhängigkeiten",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # Zweite Abfrage: Mit vollem Kontext aus der ersten Abfrage fortsetzen
    async for message in query(
        prompt="Überprüfe nun, ob eine dieser Abhängigkeiten bekannte Sicherheitslücken aufweist",
        options=ClaudeAgentOptions(
            resume=session_id,
            allowed_tools=["Read", "Bash", "WebSearch"],
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

Der zweite Prompt verwendet „dieser Abhängigkeiten“ — eine Referenz, die nur Sinn ergibt, weil die Session den Kontext aus dem ersten Aufruf überträgt. Ohne resume hätte Claude keine Ahnung, worauf Sie sich beziehen.

Schritt 6: Aufgaben mit Subagenten delegieren

Subagenten sind spezialisierte Agenten, die Ihr Hauptagent über das Agent-Tool aufrufen kann. Der Hauptagent koordiniert; Subagenten erledigen fokussierte Arbeit. Ergebnisse fließen zurück in den Hauptkontext.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Überprüfe diese Codebasis: Verwende den Security-Auditor-Agenten für Auth-Dateien und den Style-Checker-Agenten für alles andere",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Spezialist für Authentifizierungs- und Autorisierungssicherheit.",
                    prompt="Prüfe auth-bezogenen Code auf OWASP Top 10 Schwachstellen. Gib konkrete Zeilennummern und Risikostufen an.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Code-Stil- und Wartbarkeitsprüfer.",
                    prompt="Überprüfe Code auf Namenskonventionen, Komplexität und Dokumentationslücken.",
                    tools=["Read", "Glob"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Fügen Sie "Agent" in allowed_tools ein, um Subagenten-Aufrufe vorab zu genehmigen. Nachrichten von einem Subagenten enthalten ein parent_tool_use_id-Feld, sodass Sie nachverfolgen können, welche Ausgabe von welchem Subagenten stammt.

Schritt 7: Externe Systeme über MCP anbinden

Das Model Context Protocol (MCP) ermöglicht das Hinzufügen externer Fähigkeiten zum Agenten — Datenbanken, Browser, interne APIs — ohne benutzerdefinierte Tools zu schreiben. Der Agent behandelt MCP-Tools genauso wie integrierte Tools.

Dieses Beispiel fügt Browserautomatisierung über den Playwright MCP-Server hinzu:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Öffne https://example.com und beschreibe die Seitenstruktur",
        options=ClaudeAgentOptions(
            mcp_servers={
                "playwright": {
                    "command": "npx",
                    "args": ["@playwright/mcp@latest"]
                }
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Die Option mcp_servers akzeptiert jeden Server, der der MCP-Spezifikation folgt. Das Community-MCP-Register unter github.com/modelcontextprotocol/servers listet hunderte Integrationen auf, darunter Postgres, Puppeteer, Slack, GitHub und Dateisystemvarianten.

Novita AI als Modell-Backend verwenden

Das Claude Agent SDK verwendet standardmäßig die Anthropic-API, Sie können es jedoch auf den Anthropic-kompatiblen Endpunkt von Novita AI ausrichten, um kosteneffektive Open-Weight-Modelle zu nutzen — ohne Codeänderungen.

Der Endpunkt von Novita AI spiegelt das Anthropic-API-Format wider:

https://api.novita.ai/anthropic

Setzen Sie diese beiden Umgebungsvariablen vor der Ausführung Ihres Agenten:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="your-novita-api-key"
"

Ihre vorhandenen `query()`-Aufrufe funktionieren ohne Änderungen. Das SDK liest `ANTHROPIC_BASE_URL` automatisch aus.

Novita AI hostet eine Reihe von Modellen — darunter Kimi K2.5, GLM 5.2, MiniMax M2.1 und Qwen 3.5 — die über diesen Endpunkt zugänglich sind. Für Teams, die Agent-Pipelines mit tausenden Aufgaben ausführen, kann der Unterschied bei den Kosten pro Token erheblich sein. Siehe [Novita AI LLM API](https://novita.ai/llm-api) für den aktuellen Modellkatalog und die Preisgestaltung.

Wenn Sie Ihren Agenten in isolierter Sandbox-Infrastruktur bereitstellen müssen — nützlich für agentische Code-Ausführung, bei der der Agent Ihr Host-Dateisystem nicht berühren soll — bietet die [Novita Agent Sandbox](/how-to-deploy-and-host-claude-agent-sdk-with-novita-sandbox/) eine E2B-kompatible Ausführungsumgebung, die speziell für Agenten entwickelt wurde, die auf dem Claude Agent SDK basieren.

## Claude Code SDK in CI/CD-Pipelines

Die `permission_mode="acceptEdits"`- und `allowed_tools`-Einschränkungen des SDKs machen es praktikabel, Agenten unbeaufsichtigt in CI auszuführen. Ein typisches GitHub Actions-Muster:

```yaml
- name: Automatisiertes Code-Review ausführen
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    python review_agent.py

Wobei review_agent.py etwa Folgendes enthält:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Überprüfe alle geänderten Python-Dateien in diesem PR auf Korrektheit und Testabdeckungslücken. Gib einen JSON-Bericht aus.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            permission_mode="acceptEdits",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

Für Agenten, die zurück ins Repository schreiben (automatisiertes Refactoring, Dokugenerierung), kombinieren Sie dies mit einem PostToolUse-Hook, der Änderungen validiert, bevor sie Git erreichen.

Fehlerbehebung

No matching distribution found for claude-agent-sdk Ihre Python-Version ist niedriger als 3.10. Führen Sie python3 --version aus und aktualisieren Sie gegebenenfalls.

ANTHROPIC_API_KEY is not set Das SDK benötigt diese Umgebungsvariable. Exportieren Sie sie in Ihrer Shell oder .env-Datei vor der Ausführung.

TypeScript-Agent beendet vor Abschluss Stellen Sie sicher, dass Sie die vollständige Iterator-Schleife mit await abwarten. Das SDK muss alle Nachrichtenereignisse verarbeiten, bevor Ihr Prozess beendet wird.

Agent verwendet unerwartete Tools Verwenden Sie allowed_tools, um das Tool-Set explizit einzuschränken. Wenn Sie es nicht angeben, hat der Agent Zugriff auf alle integrierten Tools.

Subagent-Nachrichten erscheinen nicht in der Ausgabe Filtern Sie nach Nachrichten, bei denen parent_tool_use_id gesetzt ist, um Subagenten-Ausgaben getrennt vom Hauptagenten zu identifizieren.

Session wird nicht korrekt fortgesetzt Erfassen Sie session_id aus der SystemMessage mit subtype === "init" zu Beginn der ersten Abfrage, nicht aus einer Ergebnisnachricht.

FAQ

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

Das Claude Agent SDK (ehemals Claude Code SDK) bietet Ihnen einen autonomen Agenten, der die Tool-Ausführung automatisch übernimmt. Das Anthropic Client SDK bietet Ihnen direkten API-Zugriff, bei dem Sie die Tool-Schleife selbst implementieren. Verwenden Sie das Agent SDK für agentische Pipelines; verwenden Sie das Client SDK für direkte Modellaufrufe mit präziser Steuerung.

Welche Python-Version wird für das claude-agent-sdk benötigt?

Python 3.10 oder höher. Das Paket wird nicht auf Python 3.9 oder älter installiert.

Muss ich das Claude Code CLI installieren, um das TypeScript-SDK zu verwenden?

Nein. Das Paket @anthropic-ai/claude-agent-sdk enthält ein eigenes natives Claude Code-Binary als optionale Abhängigkeit.

Kann das Claude Agent SDK andere Modelle als Anthropics Claude verwenden?

Durch Setzen von ANTHROPIC_BASE_URL auf einen Anthropic-kompatiblen Endpunkt wie https://api.novita.ai/anthropic können Sie jedes Modell verwenden, das dieser Anbieter hostet — einschließlich Open-Weight-Modelle von Kimi, GLM, MiniMax oder Qwen.

Wie unterscheidet sich das Agent SDK von Claude Managed Agents?

Managed Agents ist eine gehostete REST-API, bei der Anthropic den Agenten in seiner Infrastruktur ausführt. Das Agent SDK ist eine Bibliothek, die die Agenten-Schleife in Ihrem eigenen Prozess auf Ihrem eigenen Dateisystem ausführt. Das Agent SDK ist besser für die lokale Entwicklung und für Agenten geeignet, die auf Ihre privaten Dateien oder Dienste zugreifen müssen.

Unterstützt das Claude Agent SDK Streaming-Ausgabe?

Die query()-Funktion gibt einen asynchronen Iterator zurück, der Nachrichten liefert, während der Agent arbeitet. Dies bietet ein streaming-ähnliches Verhalten — Sie sehen Zwischenergebnisse vor der endgültigen Antwort.

Kann ich das Agent SDK mit Amazon Bedrock oder Vertex AI verwenden?

Ja. Setzen Sie CLAUDE_CODE_USE_BEDROCK=1 plus AWS-Anmeldedaten für Bedrock oder CLAUDE_CODE_USE_VERTEX=1 plus Google Cloud-Anmeldedaten für Vertex AI.

Welche Dokumentation zum anthropic claude agent sdk sollte ich zuerst lesen?

Die offiziellen Dokumente finden Sie unter code.claude.com/docs/en/agent-sdk/overview. Beginnen Sie mit dem Schnellstart, und lesen Sie dann die Anleitungen zu Sessions und Hooks, sobald Sie einen funktionierenden Agenten haben.

Empfohlene Artikel

• Claude Code CLI Dokumentation: Einrichtung, Slash-Befehle und LLM-API-Integration
• Vercel AI SDK: Vollständiger Entwicklerleitfaden für KI-Anwendungen
• So stellen Sie das Claude Agent SDK mit Novita Sandbox bereit und hosten es

---

Quellen geprüft am 3. Juli 2026: Claude Agent SDK Dokumentation, Novita AI LLM API