Claude Code SDK (Claude Agent SDK): Python- und TypeScript-Anleitung

Das Claude Code SDK, das im Zuge der Veröffentlichung des Anthropic Agent SDK in Claude Agent SDK umbenannt wurde, ist eine Python- und TypeScript-Bibliothek zum Ausführen autonomer Coding-Agenten in Ihrer Anwendung. Es übernimmt Dateilesen, Befehle, Codebearbeitungen, Tool-Aufrufe und mehrschrittige Iterationen, ohne dass Sie eine eigene Tool-Schleife schreiben müssen. Mit dem Anthropic-kompatiblen Endpunkt von Novita AI kann dasselbe SDK auch unterstützte Open-Weight-Modelle ausführen und bietet Teams so einen Weg zur Modellauswahl und Kostenkontrolle über das standardmäßige Anthropic-Backend hinaus.

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

Wichtige Erkenntnisse

• 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, nach mehreren Aufrufen mit vollständigem Kontext weiterzuarbeiten.
• Hooks ermöglichen es Ihnen, Tool-Aufrufe an bestimmten Lebenszykluspunkten zu validieren, zu protokollieren oder zu blockieren.
• 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 zur Verfügung, die auch die Claude Code CLI interaktiv nutzt – jedoch als Bibliothek, die Sie in Ihren eigenen Code importieren und aufrufen.

Anthropic hat es ab der Generation 4.6 in Claude Agent SDK umbenannt, aber der ursprüngliche Suchbegriff „claude code sdk“ beschreibt immer noch genau, was es ist: die SDK-Schicht, die auf Claude Code aufsetzt und Ihnen ermöglicht, Agentenaufgaben in Software zu automatisieren.

Wofür es geeignet ist:

• Automatisierte Code-Reviews, Refactoring oder Testgenerierung in CI/CD
• Agenten, die Dateien lesen und ändern, Skripte ausführen oder das Web in Ihrem Namen durchsuchen
• Multi-Agent-Pipelines, bei denen ein Koordinator Teilaufgaben an spezialisierte Worker delegiert
• Jeder Workflow, bei dem Claude autonome mehrschrittige Aktionen ausführen soll und nicht nur eine Eingabeaufforderung beantworten

Wofür es nicht geeignet ist: Wenn Sie die direkte Kontrolle über jede Nachricht, strukturierte Ausgaben 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 übernommen	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 weitere	Keine – Sie definieren und führen alle Tools selbst aus
Sessions	Integriert – Fortsetzen mit einer Session-ID	Manuell – Sie verwalten den Gesprächsverlauf selbst
Am besten geeignet für	Agent-Pipelines, CI/CD, Dateioperationen	Chat-Apps, strukturierte Ausgaben, feinkörnige Steuerung

Wenn Claude selbstständig herausfinden soll, welche Dateien gelesen und bearbeitet werden müssen: Agent SDK. Wenn Claude auf eine bestimmte Eingabeaufforderung antworten und einen von Ihnen weiterverarbeiteten Wert zurückgeben soll: Client SDK.

Installieren 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 eine native Claude Code-Binärdatei für Ihre Plattform als optionale Abhängigkeit. Sie müssen Claude Code nicht separat installieren.

Um Ihre Python-Version vor der Installation zu überprüfen:

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

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

Schritt 1: Authentifizierung konfigurieren

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

export ANTHROPIC_API_KEY=ihr-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: Ihre erste Agent-Abfrage ausführen

Die gesamte SDK-Oberfläche ist auf eine einzige Funktion aufgebaut: query(). Sie akzeptiert eine Eingabeaufforderung 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 der Agent verwenden darf; Claude übernimmt die Ausführung.

Tool	Funktion
Read	Lesen einer beliebigen Datei im Arbeitsverzeichnis
Write	Erstellen neuer Dateien
Edit	Gezielte Änderungen an vorhandenen Dateien
Bash	Ausführen von Shell-Befehlen, Skripten, Git-Operationen
Glob	Finden von Dateien nach Muster (**/*.ts, src/**/*.py)
Grep	Durchsuchen von Dateiinhalten mit Regex
WebSearch	Durchsuchen des Webs nach aktuellen Informationen
WebFetch	Abrufen und Parsen von Webseiteninhalten
Monitor	Überwachen eines Hintergrundskripts und Reagieren auf Ausgabezeilen
AskUserQuestion	Den Benutzer während der Aufgabe um klärende Fragen bitten
Agent	Aufrufen eines definierten Subagenten

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

allowed_tools (Python) / allowedTools (TypeScript) genehmigt bestimmte Tools vorab ohne Bestätigungsaufforderung. Die Einschränkung des Toolsets begrenzt auch, was der Agent unbeabsichtigt tun kann – eine nützliche Sicherheitsvorkehrung für automatisierte Pipelines.

Schreibgeschützter Code-Review-Agent:

from claude_agent_sdk import query, ClaudeAgentOptions

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

Vollständiger Bearbeitungsagent (genehmigt Dateischreibvorgänge vorab):

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

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

Schritt 4: Hooks zur 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-Log, 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="Refaktoriere 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 zur Durchsetzung von Richtlinien wie „niemals Dateien löschen“ in automatisierten Kontexten.

Schritt 5: Arbeiten mit Sessions fortsetzen

Sessions bewahren den vollständigen Kontext des Agenten – welche Dateien er gelesen hat, was er gefunden hat, den Gesprächsverlauf – über mehrere query()-Aufrufe hinweg. So können Sie eine lange Aufgabe in Schritte aufteilen oder eine unterbrochene Arbeit fortsetzen.

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="Lesen Sie das Authentifizierungsmodul und identifizieren Sie 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 vollständigem Kontext aus der ersten fortsetzen
    async for message in query(
        prompt="Prüfen Sie nun, ob eine dieser Abhängigkeiten bekannte Schwachstellen aufweist",
        options=ClaudeAgentOptions(
            resume=session_id,
            allowed_tools=["Read", "Bash", "WebSearch"],
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

Die zweite Eingabeaufforderung verwendet „diese Abhängigkeiten“ – ein Verweis, der 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 gezielte 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üfen Sie diese Codebasis: Verwenden Sie 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="Auditieren Sie auth-bezogenen Code auf OWASP Top 10-Schwachstellen. Geben Sie konkrete Zeilennummern und Risikoschweregrade an.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Code-Stil- und Wartbarkeitsprüfer.",
                    prompt="Überprüfen Sie den 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 es Ihnen, dem Agenten externe Fähigkeiten hinzuzufügen – Datenbanken, Browser, interne APIs – ohne benutzerdefinierte Tools zu schreiben. Der Agent behandelt MCP-Tools genauso wie integrierte Tools.

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Öffnen Sie https://example.com und beschreiben Sie 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 Dateisystem-Varianten.

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 kostengünstige 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, bevor Sie Ihren Agenten ausführen:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="ihr-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 von Aufgaben betreiben, kann der Kostenunterschied pro Token erheblich sein. Siehe Novita AI LLM API für den aktuellen Modellkatalog und die Preise.

Wenn Sie Ihren Agenten in isolierter Sandbox-Infrastruktur bereitstellen müssen – nützlich für agentische Codeausführung, bei der der Agent Ihr Host-Dateisystem nicht berühren soll – bietet Novita Agent Sandbox eine E2B-kompatible Ausführungsumgebung, die speziell für auf dem Claude Agent SDK basierende Agenten entwickelt wurde.

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:

- 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üfen Sie alle geänderten Python-Dateien in diesem PR auf Korrektheit und Testabdeckungslücken. Geben Sie 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 Änderungen zurück ins Repository schreiben (automatisiertes Refactoring, Dokumentationserstellung), kombinieren Sie dies mit einem PostToolUse-Hook, der Änderungen validiert, bevor sie zu Git gelangen.

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 bei Bedarf.

ANTHROPIC_API_KEY is not set Das SDK benötigt die Umgebungsvariable. Exportieren Sie sie in Ihrer Shell oder .env-Datei, bevor Sie es ausführen.

TypeScript-Agent beendet vor Abschluss Stellen Sie sicher, dass Sie die gesamte 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 Toolset 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 Subagent-Ausgaben getrennt vom Hauptagenten zu identifizieren.

Session wird nicht korrekt fortgesetzt Erfassen Sie die session_id aus dem 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) stellt Ihnen einen autonomen Agenten zur Verfügung, 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 ist für das claude-agent-sdk erforderlich?

Python 3.10 oder neuer. Das Paket wird nicht auf Python 3.9 oder älter installiert.

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

Nein. Das Paket @anthropic-ai/claude-agent-sdk enthält eine eigene native Claude Code-Binärdatei als optionale Abhängigkeit.

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

Indem Sie ANTHROPIC_BASE_URL auf einen Anthropic-kompatiblen Endpunkt wie https://api.novita.ai/anthropic setzen, können Sie jedes von diesem Anbieter gehostete Modell verwenden – einschließlich Open-Weight-Modellen 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 Agentenschleife in Ihrem eigenen Prozess auf Ihrem eigenen Dateisystem ausführt. Das Agent SDK eignet sich besser für die lokale Entwicklung und für Agenten, die auf Ihre privaten Dateien oder Dienste zugreifen müssen.

Unterstützt das Claude Agent SDK Streaming-Ausgaben?

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 anthropic claude agent sdk Dokumentation sollte ich zuerst lesen?

Die offizielle Dokumentation finden Sie unter code.claude.com/docs/en/agent-sdk/overview. Beginnen Sie mit dem Quickstart 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ändige Entwickleranleitung zum Erstellen von 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