Python SDK Referenz

Funktionen

`query()`

Die primäre asynchrone Funktion für die Interaktion mit Claude Code. Gibt einen asynchronen Iterator zurück, der Nachrichten liefert, sobald sie eintreffen.

async def query(
    *,
    prompt: str | AsyncIterable[dict[str, Any]],
    options: ClaudeCodeOptions | None = None
) -> AsyncIterator[Message]

Parameter

Parameter	Typ	Beschreibung
`prompt`	`str \| AsyncIterable[dict]`	Der Eingabeprompt als String oder asynchrones Iterable für den Streaming-Modus
`options`	`ClaudeCodeOptions \| None`	Optionales Konfigurationsobjekt (standardmäßig `ClaudeCodeOptions()` wenn None)

Rückgabe

Gibt einen AsyncIterator[Message] zurück, der Nachrichten aus der Unterhaltung liefert.

Beispiel - Einfache Abfrage

import asyncio
from claude_code_sdk import query

async def main():
    async for message in query(prompt="Was ist 2+2?"):
        print(message)

asyncio.run(main())

Beispiel - Mit Optionen


import asyncio
from claude_code_sdk import query, ClaudeCodeOptions

async def main():
    options = ClaudeCodeOptions(
        system_prompt="Du bist ein erfahrener Python-Entwickler",
        permission_mode='acceptEdits',
        cwd="/home/user/project"
    )

    async for message in query(
        prompt="Erstelle einen Python-Webserver",
        options=options
    ):
        print(message)


asyncio.run(main())

`tool()`

Dekorator zur Definition von MCP-Tools mit Typsicherheit.

def tool(
    name: str,
    description: str,
    input_schema: type | dict[str, Any]
) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]

Parameter

Parameter	Typ	Beschreibung
`name`	`str`	Eindeutige Kennung für das Tool
`description`	`str`	Menschenlesbare Beschreibung dessen, was das Tool tut
`input_schema`	`type \| dict[str, Any]`	Schema zur Definition der Eingabeparameter des Tools (siehe unten)

Eingabeschema-Optionen

Einfache Typ-Zuordnung (empfohlen):

{"text": str, "count": int, "enabled": bool}

JSON-Schema-Format (für komplexe Validierung):

{
    "type": "object",
    "properties": {
        "text": {"type": "string"},
        "count": {"type": "integer", "minimum": 0}
    },
    "required": ["text"]
}

Rückgabe

Eine Dekoratorfunktion, die die Tool-Implementierung umhüllt und eine SdkMcpTool-Instanz zurückgibt.

Beispiel

from claude_code_sdk import tool
from typing import Any

@tool("greet", "Einen Benutzer begrüßen", {"name": str})
async def greet(args: dict[str, Any]) -> dict[str, Any]:
    return {
        "content": [{
            "type": "text",
            "text": f"Hallo, {args['name']}!"
        }]
    }

`create_sdk_mcp_server()`

Erstellt einen In-Process-MCP-Server, der innerhalb Ihrer Python-Anwendung läuft.

def create_sdk_mcp_server(
    name: str,
    version: str = "1.0.0",
    tools: list[SdkMcpTool[Any]] | None = None
) -> McpSdkServerConfig

Parameter

Parameter	Typ	Standard	Beschreibung
`name`	`str`	-	Eindeutige Kennung für den Server
`version`	`str`	`"1.0.0"`	Server-Versionsstring
`tools`	`list[SdkMcpTool[Any]] \| None`	`None`	Liste von Tool-Funktionen, die mit dem `@tool`-Dekorator erstellt wurden

Rückgabe

Gibt ein McpSdkServerConfig-Objekt zurück, das an ClaudeCodeOptions.mcp_servers übergeben werden kann.

Beispiel

from claude_code_sdk import tool, create_sdk_mcp_server

@tool("add", "Zwei Zahlen addieren", {"a": float, "b": float})
async def add(args):
    return {
        "content": [{
            "type": "text",
            "text": f"Summe: {args['a'] + args['b']}"
        }]
    }

@tool("multiply", "Zwei Zahlen multiplizieren", {"a": float, "b": float})
async def multiply(args):
    return {
        "content": [{
            "type": "text",
            "text": f"Produkt: {args['a'] * args['b']}"
        }]
    }

calculator = create_sdk_mcp_server(
    name="calculator",
    version="2.0.0",
    tools=[add, multiply]  # Dekorierte Funktionen übergeben
)

# Mit Claude verwenden
options = ClaudeCodeOptions(
    mcp_servers={"calc": calculator},
    allowed_tools=["mcp__calc__add", "mcp__calc__multiply"]
)

Klassen

`ClaudeSDKClient`

Client für bidirektionale, interaktive Unterhaltungen mit Claude Code. Bietet vollständige Kontrolle über den Unterhaltungsfluss mit Unterstützung für Streaming, Unterbrechungen und dynamisches Senden von Nachrichten.

class ClaudeSDKClient:
    def __init__(self, options: ClaudeCodeOptions | None = None)
    async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None
    async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None
    async def receive_messages(self) -> AsyncIterator[Message]
    async def receive_response(self) -> AsyncIterator[Message]
    async def interrupt(self) -> None
    async def disconnect(self) -> None

Methoden

Methode	Beschreibung
`__init__(options)`	Initialisiert den Client mit optionaler Konfiguration
`connect(prompt)`	Verbindet sich mit Claude mit einem optionalen anfänglichen Prompt oder Nachrichtenstrom
`query(prompt, session_id)`	Sendet eine neue Anfrage im Streaming-Modus
`receive_messages()`	Empfängt alle Nachrichten von Claude als asynchronen Iterator
`receive_response()`	Empfängt Nachrichten bis einschließlich einer ResultMessage
`interrupt()`	Sendet Unterbrechungssignal (funktioniert nur im Streaming-Modus)
`disconnect()`	Trennt die Verbindung zu Claude

Unterstützung für Context Manager

Der Client kann als asynchroner Context Manager für automatische Verbindungsverwaltung verwendet werden:

async with ClaudeSDKClient() as client:
    await client.query("Hallo Claude")
    async for message in client.receive_response():
        print(message)

Wichtig: Vermeiden Sie beim Iterieren über Nachrichten die Verwendung von break für einen vorzeitigen Ausstieg, da dies zu asyncio-Bereinigungsproblemen führen kann. Lassen Sie stattdessen die Iteration natürlich abschließen oder verwenden Sie Flags, um zu verfolgen, wann Sie gefunden haben, was Sie brauchen.

Beispiel - Interaktive Unterhaltung

import asyncio
from claude_code_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage

async def main():
    async with ClaudeSDKClient() as client:
        # Anfängliche Nachricht senden
        await client.query("Lass uns ein Mathematikproblem Schritt für Schritt lösen")
        
        # Antwort empfangen und verarbeiten
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(f"Assistent: {block.text[:100]}...")
            elif isinstance(message, ResultMessage):
                print("Antwort vollständig")
        
        # Nachfrage basierend auf Antwort senden
        await client.query("Was sind 15% von 80?")

asyncio.run(main())

Typen

`SdkMcpTool`

Definition für ein SDK-MCP-Tool, das mit dem @tool-Dekorator erstellt wurde.

@dataclass
class SdkMcpTool(Generic[T]):
    name: str
    description: str
    input_schema: type[T] | dict[str, Any]
    handler: Callable[[T], Awaitable[dict[str, Any]]]

Eigenschaft	Typ	Beschreibung
`name`	`str`	Eindeutige Kennung für das Tool
`description`	`str`	Menschenlesbare Beschreibung
`input_schema`	`type[T] \| dict[str, Any]`	Schema für Eingabevalidierung
`handler`	`Callable[[T], Awaitable[dict[str, Any]]]`	Asynchrone Funktion, die die Tool-Ausführung behandelt

`ClaudeCodeOptions`

Konfigurationsdatenklasse für Claude Code-Abfragen.

@dataclass
class ClaudeCodeOptions:
    allowed_tools: list[str] = field(default_factory=list)
    max_thinking_tokens: int = 8000
    system_prompt: str | None = None
    append_system_prompt: str | None = None
    mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
    permission_mode: PermissionMode | None = None
    continue_conversation: bool = False
    resume: str | None = None
    max_turns: int | None = None
    disallowed_tools: list[str] = field(default_factory=list)
    model: str | None = None
    permission_prompt_tool_name: str | None = None
    cwd: str | Path | None = None
    settings: str | None = None
    add_dirs: list[str | Path] = field(default_factory=list)
    env: dict[str, str] = field(default_factory=dict)
    extra_args: dict[str, str | None] = field(default_factory=dict)

Eigenschaft	Typ	Standard	Beschreibung
`allowed_tools`	`list[str]`	`[]`	Liste der erlaubten Tool-Namen
`max_thinking_tokens`	`int`	`8000`	Maximale Token für den Denkprozess
`system_prompt`	`str \| None`	`None`	Ersetzt den Standard-System-Prompt vollständig
`append_system_prompt`	`str \| None`	`None`	Text, der an den Standard-System-Prompt angehängt wird
`mcp_servers`	`dict[str, McpServerConfig] \| str \| Path`	`{}`	MCP-Server-Konfigurationen oder Pfad zur Konfigurationsdatei
`permission_mode`	`PermissionMode \| None`	`None`	Berechtigungsmodus für Tool-Nutzung
`continue_conversation`	`bool`	`False`	Setzt die neueste Unterhaltung fort
`resume`	`str \| None`	`None`	Session-ID zum Fortsetzen
`max_turns`	`int \| None`	`None`	Maximale Unterhaltungsrunden
`disallowed_tools`	`list[str]`	`[]`	Liste der nicht erlaubten Tool-Namen
`model`	`str \| None`	`None`	Zu verwendendes Claude-Modell
`permission_prompt_tool_name`	`str \| None`	`None`	MCP-Tool-Name für Berechtigungsprompts
`cwd`	`str \| Path \| None`	`None`	Aktuelles Arbeitsverzeichnis
`settings`	`str \| None`	`None`	Pfad zur Einstellungsdatei
`add_dirs`	`list[str \| Path]`	`[]`	Zusätzliche Verzeichnisse, auf die Claude zugreifen kann
`extra_args`	`dict[str, str \| None]`	`{}`	Zusätzliche CLI-Argumente, die direkt an die CLI übergeben werden
`can_use_tool`	`CanUseTool \| None`	`None`	Tool-Berechtigungs-Callback-Funktion
`hooks`	`dict[HookEvent, list[HookMatcher]] \| None`	`None`	Hook-Konfigurationen zum Abfangen von Ereignissen

`PermissionMode`

Berechtigungsmodi zur Kontrolle der Tool-Ausführung.

PermissionMode = Literal[
    "default",           # Standard-Berechtigungsverhalten
    "acceptEdits",       # Dateibearbeitungen automatisch akzeptieren
    "plan",              # Planungsmodus - keine Ausführung
    "bypassPermissions"  # Alle Berechtigungsprüfungen umgehen (mit Vorsicht verwenden)
]

`McpSdkServerConfig`

Konfiguration für SDK-MCP-Server, die mit create_sdk_mcp_server() erstellt wurden.

class McpSdkServerConfig(TypedDict):
    type: Literal["sdk"]
    name: str
    instance: Any  # MCP Server-Instanz

`McpServerConfig`

Union-Typ für MCP-Server-Konfigurationen.

McpServerConfig = McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig

`McpStdioServerConfig`

class McpStdioServerConfig(TypedDict):
    type: NotRequired[Literal["stdio"]]  # Optional für Rückwärtskompatibilität
    command: str
    args: NotRequired[list[str]]
    env: NotRequired[dict[str, str]]

`McpSSEServerConfig`

class McpSSEServerConfig(TypedDict):
    type: Literal["sse"]
    url: str
    headers: NotRequired[dict[str, str]]

`McpHttpServerConfig`

class McpHttpServerConfig(TypedDict):
    type: Literal["http"]
    url: str
    headers: NotRequired[dict[str, str]]

Nachrichtentypen

`Message`

Union-Typ aller möglichen Nachrichten.

Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage

`UserMessage`

Benutzereingabe-Nachricht.

@dataclass
class UserMessage:
    content: str | list[ContentBlock]

`AssistantMessage`

Assistenten-Antwortnachricht mit Inhaltsblöcken.

@dataclass
class AssistantMessage:
    content: list[ContentBlock]
    model: str

`SystemMessage`

System-Nachricht mit Metadaten.

@dataclass
class SystemMessage:
    subtype: str
    data: dict[str, Any]

`ResultMessage`

Abschließende Ergebnisnachricht mit Kosten- und Nutzungsinformationen.

@dataclass
class ResultMessage:
    subtype: str
    duration_ms: int
    duration_api_ms: int
    is_error: bool
    num_turns: int
    session_id: str
    total_cost_usd: float | None = None
    usage: dict[str, Any] | None = None
    result: str | None = None

Inhaltsblocktypen

`ContentBlock`

Union-Typ aller Inhaltsblöcke.

ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock

`TextBlock`

Text-Inhaltsblock.

@dataclass
class TextBlock:
    text: str

`ThinkingBlock`

Denk-Inhaltsblock (für Modelle mit Denkfähigkeit).

@dataclass
class ThinkingBlock:
    thinking: str
    signature: str

`ToolUseBlock`

Tool-Verwendungsanfrage-Block.

@dataclass
class ToolUseBlock:
    id: str
    name: str
    input: dict[str, Any]

`ToolResultBlock`

Tool-Ausführungsergebnis-Block.

@dataclass
class ToolResultBlock:
    tool_use_id: str
    content: str | list[dict[str, Any]] | None = None
    is_error: bool | None = None

Fehlertypen

`ClaudeSDKError`

Basis-Exception-Klasse für alle SDK-Fehler.

class ClaudeSDKError(Exception):
    """Basisfehler für Claude SDK."""

`CLINotFoundError`

Wird ausgelöst, wenn Claude Code CLI nicht installiert oder nicht gefunden wird.

class CLINotFoundError(CLIConnectionError):
    def __init__(self, message: str = "Claude Code nicht gefunden", cli_path: str | None = None):
        """
        Args:
            message: Fehlermeldung (Standard: "Claude Code nicht gefunden")
            cli_path: Optionaler Pfad zur CLI, die nicht gefunden wurde
        """

`CLIConnectionError`

Wird ausgelöst, wenn die Verbindung zu Claude Code fehlschlägt.

class CLIConnectionError(ClaudeSDKError):
    """Verbindung zu Claude Code fehlgeschlagen."""

`ProcessError`

Wird ausgelöst, wenn der Claude Code-Prozess fehlschlägt.

class ProcessError(ClaudeSDKError):
    def __init__(self, message: str, exit_code: int | None = None, stderr: str | None = None):
        self.exit_code = exit_code
        self.stderr = stderr

`CLIJSONDecodeError`

Wird ausgelöst, wenn das JSON-Parsing fehlschlägt.

class CLIJSONDecodeError(ClaudeSDKError):
    def __init__(self, line: str, original_error: Exception):
        """
        Args:
            line: Die Zeile, die nicht geparst werden konnte
            original_error: Die ursprüngliche JSON-Decode-Exception
        """
        self.line = line
        self.original_error = original_error

Hook-Typen

`HookEvent`

Unterstützte Hook-Ereignistypen. Beachten Sie, dass das Python SDK aufgrund von Setup-Einschränkungen keine SessionStart-, SessionEnd- und Notification-Hooks unterstützt.

HookEvent = Literal[
    "PreToolUse",      # Wird vor Tool-Ausführung aufgerufen
    "PostToolUse",     # Wird nach Tool-Ausführung aufgerufen
    "UserPromptSubmit", # Wird aufgerufen, wenn Benutzer einen Prompt einreicht
    "Stop",            # Wird beim Stoppen der Ausführung aufgerufen
    "SubagentStop",    # Wird aufgerufen, wenn ein Subagent stoppt
    "PreCompact"       # Wird vor Nachrichtenkompaktierung aufgerufen
]

`HookCallback`

Typdefinition für Hook-Callback-Funktionen.

HookCallback = Callable[
    [dict[str, Any], str | None, HookContext],
    Awaitable[dict[str, Any]]
]

Parameter:

input_data: Hook-spezifische Eingabedaten (siehe Hook-Dokumentation)
tool_use_id: Optionale Tool-Verwendungskennung (für tool-bezogene Hooks)
context: Hook-Kontext mit zusätzlichen Informationen

Gibt ein Dictionary zurück, das enthalten kann:

decision: "block" um die Aktion zu blockieren
systemMessage: System-Nachricht zum Hinzufügen zum Transkript
hookSpecificOutput: Hook-spezifische Ausgabedaten

`HookContext`

Kontextinformationen, die an Hook-Callbacks übergeben werden.

@dataclass
class HookContext:
    signal: Any | None = None  # Zukunft: Abort-Signal-Unterstützung

`HookMatcher`

Konfiguration zum Zuordnen von Hooks zu bestimmten Ereignissen oder Tools.

@dataclass
class HookMatcher:
    matcher: str | None = None        # Tool-Name oder Muster zum Abgleichen (z.B. "Bash", "Write|Edit")
    hooks: list[HookCallback] = field(default_factory=list)  # Liste der auszuführenden Callbacks

Hook-Verwendungsbeispiel

from claude_code_sdk import query, ClaudeCodeOptions, HookMatcher, HookContext
from typing import Any

async def validate_bash_command(
    input_data: dict[str, Any],
    tool_use_id: str | None,
    context: HookContext
) -> dict[str, Any]:
    """Validiert und blockiert potenziell gefährliche Bash-Befehle."""
    if input_data['tool_name'] == 'Bash':
        command = input_data['tool_input'].get('command', '')
        if 'rm -rf /' in command:
            return {
                'hookSpecificOutput': {
                    'hookEventName': 'PreToolUse',
                    'permissionDecision': 'deny',
                    'permissionDecisionReason': 'Gefährlicher Befehl blockiert'
                }
            }
    return {}

async def log_tool_use(
    input_data: dict[str, Any],
    tool_use_id: str | None,
    context: HookContext
) -> dict[str, Any]:
    """Protokolliert alle Tool-Verwendungen für Auditing."""
    print(f"Tool verwendet: {input_data.get('tool_name')}")
    return {}

options = ClaudeCodeOptions(
    hooks={
        'PreToolUse': [
            HookMatcher(matcher='Bash', hooks=[validate_bash_command]),
            HookMatcher(hooks=[log_tool_use])  # Gilt für alle Tools
        ],
        'PostToolUse': [
            HookMatcher(hooks=[log_tool_use])
        ]
    }
)

async for message in query(
    prompt="Analysiere diese Codebasis",
    options=options
):
    print(message)

Tool-Eingabe-/Ausgabetypen

Dokumentation der Eingabe-/Ausgabeschemata für alle eingebauten Claude Code-Tools. Obwohl das Python SDK diese nicht als Typen exportiert, repräsentieren sie die Struktur von Tool-Eingaben und -Ausgaben in Nachrichten.

Task

Tool-Name: Task Eingabe:

{
    "description": str,      # Eine kurze (3-5 Wörter) Beschreibung der Aufgabe
    "prompt": str,           # Die Aufgabe, die der Agent ausführen soll
    "subagent_type": str     # Der Typ des spezialisierten Agenten, der verwendet werden soll
}

Ausgabe:

{
    "result": str,                    # Endergebnis vom Subagenten
    "usage": dict | None,             # Token-Nutzungsstatistiken
    "total_cost_usd": float | None,  # Gesamtkosten in USD
    "duration_ms": int | None         # Ausführungsdauer in Millisekunden
}

Bash

Tool-Name: Bash Eingabe:

{
    "command": str,                  # Der auszuführende Befehl
    "timeout": int | None,           # Optionales Timeout in Millisekunden (max 600000)
    "description": str | None,       # Klare, prägnante Beschreibung (5-10 Wörter)
    "run_in_background": bool | None # Auf true setzen, um im Hintergrund zu laufen
}

Ausgabe:

{
    "output": str,              # Kombinierte stdout- und stderr-Ausgabe
    "exitCode": int,            # Exit-Code des Befehls
    "killed": bool | None,      # Ob Befehl wegen Timeout beendet wurde
    "shellId": str | None       # Shell-ID für Hintergrundprozesse
}

Edit

Tool-Name: Edit Eingabe:

{
    "file_path": str,           # Der absolute Pfad zur zu modifizierenden Datei
    "old_string": str,          # Der zu ersetzende Text
    "new_string": str,          # Der Text, durch den ersetzt werden soll
    "replace_all": bool | None  # Alle Vorkommen ersetzen (Standard False)
}

Ausgabe:

{
    "message": str,      # Bestätigungsnachricht
    "replacements": int, # Anzahl der vorgenommenen Ersetzungen
    "file_path": str     # Dateipfad, der bearbeitet wurde
}

MultiEdit

Tool-Name: MultiEdit Eingabe:

{
    "file_path": str,     # Der absolute Pfad zur zu modifizierenden Datei
    "edits": [            # Array von Bearbeitungsoperationen
        {
            "old_string": str,          # Der zu ersetzende Text
            "new_string": str,          # Der Text, durch den ersetzt werden soll
            "replace_all": bool | None  # Alle Vorkommen ersetzen
        }
    ]
}

Ausgabe:

{
    "message": str,       # Erfolgsnachricht
    "edits_applied": int, # Gesamtanzahl der angewendeten Bearbeitungen
    "file_path": str      # Dateipfad, der bearbeitet wurde
}

Read

Tool-Name: Read Eingabe:

{
    "file_path": str,       # Der absolute Pfad zur zu lesenden Datei
    "offset": int | None,   # Die Zeilennummer, ab der gelesen werden soll
    "limit": int | None     # Die Anzahl der zu lesenden Zeilen
}

Ausgabe (Textdateien):

{
    "content": str,         # Dateiinhalt mit Zeilennummern
    "total_lines": int,     # Gesamtanzahl der Zeilen in der Datei
    "lines_returned": int   # Tatsächlich zurückgegebene Zeilen
}

Ausgabe (Bilder):

{
    "image": str,       # Base64-kodierte Bilddaten
    "mime_type": str,   # Bild-MIME-Typ
    "file_size": int    # Dateigröße in Bytes
}

Write

Tool-Name: Write Eingabe:

{
    "file_path": str,  # Der absolute Pfad zur zu schreibenden Datei
    "content": str     # Der in die Datei zu schreibende Inhalt
}

Ausgabe:

{
    "message": str,        # Erfolgsnachricht
    "bytes_written": int,  # Anzahl der geschriebenen Bytes
    "file_path": str       # Dateipfad, der geschrieben wurde
}

Glob

Tool-Name: Glob Eingabe:

{
    "pattern": str,       # Das Glob-Muster zum Abgleichen von Dateien
    "path": str | None    # Das zu durchsuchende Verzeichnis (standardmäßig cwd)
}

Ausgabe:

{
    "matches": list[str],  # Array der übereinstimmenden Dateipfade
    "count": int,          # Anzahl der gefundenen Übereinstimmungen
    "search_path": str     # Verwendetes Suchverzeichnis
}

Grep

Tool-Name: Grep Eingabe:

{
    "pattern": str,                    # Das reguläre Ausdrucksmuster
    "path": str | None,                # Datei oder Verzeichnis zum Durchsuchen
    "glob": str | None,                # Glob-Muster zum Filtern von Dateien
    "type": str | None,                # Zu durchsuchender Dateityp
    "output_mode": str | None,         # "content", "files_with_matches" oder "count"
    "-i": bool | None,                 # Groß-/Kleinschreibung ignorieren
    "-n": bool | None,                 # Zeilennummern anzeigen
    "-B": int | None,                  # Zeilen vor jeder Übereinstimmung anzeigen
    "-A": int | None,                  # Zeilen nach jeder Übereinstimmung anzeigen
    "-C": int | None,                  # Zeilen vor und nach anzeigen
    "head_limit": int | None,          # Ausgabe auf erste N Zeilen/Einträge begrenzen
    "multiline": bool | None           # Mehrzeilenmodus aktivieren
}

Ausgabe (content-Modus):

{
    "matches": [
        {
            "file": str,
            "line_number": int | None,
            "line": str,
            "before_context": list[str] | None,
            "after_context": list[str] | None
        }
    ],
    "total_matches": int
}

Ausgabe (files_with_matches-Modus):

{
    "files": list[str],  # Dateien mit Übereinstimmungen
    "count": int         # Anzahl der Dateien mit Übereinstimmungen
}

NotebookEdit

Tool-Name: NotebookEdit Eingabe:

{
    "notebook_path": str,                     # Absoluter Pfad zum Jupyter-Notebook
    "cell_id": str | None,                    # Die ID der zu bearbeitenden Zelle
    "new_source": str,                        # Der neue Quellcode für die Zelle
    "cell_type": "code" | "markdown" | None,  # Der Typ der Zelle
    "edit_mode": "replace" | "insert" | "delete" | None  # Bearbeitungsoperationstyp
}

Ausgabe:

{
    "message": str, # Erfolgsnachricht
    "edit_type": "replaced" | "inserted" | "deleted",  # Typ der durchgeführten Bearbeitung
    "cell_id": str | None,                       # Zellen-ID, die betroffen war
    "total_cells": int                           # Gesamtzellen im Notebook nach Bearbeitung
}

WebFetch

Tool-Name: WebFetch Eingabe:

{
    "url": str,     # Die URL, von der Inhalt abgerufen werden soll
    "prompt": str   # Der Prompt, der auf den abgerufenen Inhalt angewendet werden soll
}

Ausgabe:

{
    "response": str,           # Antwort des KI-Modells auf den Prompt
    "url": str,                # URL, die abgerufen wurde
    "final_url": str | None,   # Endgültige URL nach Weiterleitungen
    "status_code": int | None  # HTTP-Statuscode
}

WebSearch

Tool-Name: WebSearch Eingabe:

{
    "query": str,                        # Die zu verwendende Suchanfrage
    "allowed_domains": list[str] | None, # Nur Ergebnisse von diesen Domains einschließen
    "blocked_domains": list[str] | None  # Niemals Ergebnisse von diesen Domains einschließen
}

Ausgabe:

{
    "results": [
        {
            "title": str,
            "url": str,
            "snippet": str,
            "metadata": dict | None
        }
    ],
    "total_results": int,
    "query": str
}

TodoWrite

Tool-Name: TodoWrite Eingabe:

{
    "todos": [
        {
            "content": str, # Die Aufgabenbeschreibung
            "status": "pending" | "in_progress" | "completed",  # Aufgabenstatus
            "activeForm": str                            # Aktive Form der Beschreibung
        }
    ]
}

Ausgabe:

{
    "message": str,  # Erfolgsnachricht
    "stats": {
        "total": int,
        "pending": int,
        "in_progress": int,
        "completed": int
    }
}

BashOutput

Tool-Name: BashOutput Eingabe:

{
    "bash_id": str,       # Die ID der Hintergrund-Shell
    "filter": str | None  # Optionaler Regex zum Filtern von Ausgabezeilen
}

Ausgabe:

{
    "output": str, # Neue Ausgabe seit der letzten Überprüfung
    "status": "running" | "completed" | "failed",       # Aktueller Shell-Status
    "exitCode": int | None # Exit-Code bei Abschluss
}

KillBash

Tool-Name: KillBash Eingabe:

{
    "shell_id": str  # Die ID der zu beendenden Hintergrund-Shell
}

Ausgabe:

{
    "message": str,  # Erfolgsnachricht
    "shell_id": str  # ID der beendeten Shell
}

ExitPlanMode

Tool-Name: ExitPlanMode Eingabe:

{
    "plan": str  # Der Plan, der vom Benutzer zur Genehmigung ausgeführt werden soll
}

Ausgabe:

{
    "message": str,          # Bestätigungsnachricht
    "approved": bool | None  # Ob der Benutzer den Plan genehmigt hat
}

ListMcpResources

Tool-Name: ListMcpResources Eingabe:

{
    "server": str | None  # Optionaler Servername zum Filtern von Ressourcen
}

Ausgabe:

{
    "resources": [
        {
            "uri": str,
            "name": str,
            "description": str | None,
            "mimeType": str | None,
            "server": str
        }
    ],
    "total": int
}

ReadMcpResource

Tool-Name: ReadMcpResource Eingabe:

{
    "server": str,  # Der MCP-Servername
    "uri": str      # Die zu lesende Ressourcen-URI
}

Ausgabe:

{
    "contents": [
        {
            "uri": str,
            "mimeType": str | None,
            "text": str | None,
            "blob": str | None
        }
    ],
    "server": str
}

Verwendungsbeispiele

Grundlegende Dateioperationen

from claude_code_sdk import query, ClaudeCodeOptions, AssistantMessage, ToolUseBlock
import asyncio

async def create_project():
    options = ClaudeCodeOptions(
        allowed_tools=["Read", "Write", "Bash"],
        permission_mode='acceptEdits',
        cwd="/home/user/project"
    )
    
    async for message in query(
        prompt="Erstelle eine Python-Projektstruktur mit setup.py",
        options=options
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, ToolUseBlock):
                    print(f"Tool verwendet: {block.name}")

asyncio.run(create_project())

Fehlerbehandlung

from claude_code_sdk import (
    query,
    CLINotFoundError,
    ProcessError,
    CLIJSONDecodeError
)

try:
    async for message in query(prompt="Hallo"):
        print(message)
except CLINotFoundError:
    print("Bitte installieren Sie Claude Code: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"Prozess fehlgeschlagen mit Exit-Code: {e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"Antwort konnte nicht geparst werden: {e}")

Streaming-Modus mit Client

from claude_code_sdk import ClaudeSDKClient
import asyncio

async def interactive_session():
    async with ClaudeSDKClient() as client:
        # Anfängliche Nachricht senden
        await client.query("Wie ist das Wetter?")
        
        # Antworten verarbeiten
        async for msg in client.receive_response():
            print(msg)
        
        # Nachfrage senden
        await client.query("Erzähl mir mehr darüber")
        
        # Nachfrage-Antwort verarbeiten
        async for msg in client.receive_response():
            print(msg)

asyncio.run(interactive_session())

Verwendung benutzerdefinierter Tools

from claude_code_sdk import (
    query,
    ClaudeCodeOptions,
    tool,
    create_sdk_mcp_server,
    AssistantMessage,
    TextBlock
)
import asyncio
from typing import Any

# Benutzerdefinierte Tools mit @tool-Dekorator definieren
@tool("calculate", "Mathematische Berechnungen durchführen", {"expression": str})
async def calculate(args: dict[str, Any]) -> dict[str, Any]:
    try:
        result = eval(args["expression"], {"__builtins__": {}})
        return {
            "content": [{
                "type": "text",
                "text": f"Ergebnis: {result}"
            }]
        }
    except Exception as e:
        return {
            "content": [{
                "type": "text",
                "text": f"Fehler: {str(e)}"
            }],
            "is_error": True
        }

@tool("get_time", "Aktuelle Zeit abrufen", {})
async def get_time(args: dict[str, Any]) -> dict[str, Any]:
    from datetime import datetime
    current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
    return {
        "content": [{
            "type": "text",
            "text": f"Aktuelle Zeit: {current_time}"
        }]
    }

async def main():
    # SDK-MCP-Server mit benutzerdefinierten Tools erstellen
    my_server = create_sdk_mcp_server(
        name="utilities",
        version="1.0.0",
        tools=[calculate, get_time]
    )
    
    # Optionen mit dem Server konfigurieren
    options = ClaudeCodeOptions(
        mcp_servers={"utils": my_server},
        allowed_tools=[
            "mcp__utils__calculate",
            "mcp__utils__get_time"
        ]
    )
    
    # Claude mit verfügbaren benutzerdefinierten Tools abfragen
    async for message in query(
        prompt="Was ist 123 * 456 und wie spät ist es?",
        options=options
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)

asyncio.run(main())

Siehe auch

Python SDK-Leitfaden - Tutorial und Beispiele
SDK-Übersicht - Allgemeine SDK-Konzepte
TypeScript SDK-Referenz - TypeScript SDK-Dokumentation
CLI-Referenz - Befehlszeilenschnittstelle
Häufige Arbeitsabläufe - Schritt-für-Schritt-Anleitungen

Erste Schritte

Mit Claude Code entwickeln

Claude Code SDK

Bereitstellung

Verwaltung

Konfiguration

Referenz

Ressourcen

​Funktionen

​query()

​Parameter

​Rückgabe

​Beispiel - Einfache Abfrage

​Beispiel - Mit Optionen

​tool()

​Parameter

​Eingabeschema-Optionen

​Rückgabe

​Beispiel

​create_sdk_mcp_server()

​Parameter

​Rückgabe

​Beispiel

​Klassen

​ClaudeSDKClient

​Methoden

​Unterstützung für Context Manager

​Beispiel - Interaktive Unterhaltung

​Typen

​SdkMcpTool

​ClaudeCodeOptions

​PermissionMode

​McpSdkServerConfig

​McpServerConfig

​McpStdioServerConfig

​McpSSEServerConfig

​McpHttpServerConfig

​Nachrichtentypen

​Message

​UserMessage

​AssistantMessage

​SystemMessage

​ResultMessage

​Inhaltsblocktypen

​ContentBlock

​TextBlock

​ThinkingBlock

​ToolUseBlock

​ToolResultBlock

​Fehlertypen

​ClaudeSDKError

​CLINotFoundError

​CLIConnectionError

​ProcessError

​CLIJSONDecodeError

​Hook-Typen

​HookEvent

​HookCallback

​HookContext

​HookMatcher

​Hook-Verwendungsbeispiel

​Tool-Eingabe-/Ausgabetypen

​Task

​Bash

​Edit

​MultiEdit

​Read

​Write

​Glob

​Grep

​NotebookEdit

​WebFetch

​WebSearch

​TodoWrite

​BashOutput

​KillBash

​ExitPlanMode

​ListMcpResources

​ReadMcpResource

​Verwendungsbeispiele

Funktionen

`query()`

Parameter

Rückgabe

Beispiel - Einfache Abfrage

Beispiel - Mit Optionen

`tool()`

Parameter

Eingabeschema-Optionen

Rückgabe

Beispiel

`create_sdk_mcp_server()`

Parameter

Rückgabe

Beispiel

Klassen

`ClaudeSDKClient`

Methoden

Unterstützung für Context Manager

Beispiel - Interaktive Unterhaltung

Typen

`SdkMcpTool`

`ClaudeCodeOptions`

`PermissionMode`

`McpSdkServerConfig`

`McpServerConfig`

`McpStdioServerConfig`

`McpSSEServerConfig`

`McpHttpServerConfig`

Nachrichtentypen

`Message`

`UserMessage`

`AssistantMessage`

`SystemMessage`

`ResultMessage`

Inhaltsblocktypen

`ContentBlock`

`TextBlock`

`ThinkingBlock`

`ToolUseBlock`

`ToolResultBlock`

Fehlertypen

`ClaudeSDKError`

`CLINotFoundError`

`CLIConnectionError`

`ProcessError`

`CLIJSONDecodeError`

Hook-Typen

`HookEvent`

`HookCallback`

`HookContext`

`HookMatcher`

Hook-Verwendungsbeispiel

Tool-Eingabe-/Ausgabetypen

Task

Bash

Edit

MultiEdit

Read

Write

Glob

Grep

NotebookEdit

WebFetch

WebSearch

TodoWrite

BashOutput

KillBash

ExitPlanMode

ListMcpResources

ReadMcpResource

Verwendungsbeispiele

Grundlegende Dateioperationen

Fehlerbehandlung

Streaming-Modus mit Client

Verwendung benutzerdefinierter Tools

Siehe auch