Warum das Claude Code SDK verwenden?

Das Claude Code SDK bietet alle Bausteine, die Sie benötigen, um produktionsreife Agenten zu erstellen:

  • Optimierte Claude-Integration: Automatisches Prompt-Caching und Leistungsoptimierungen
  • Reichhaltiges Tool-Ökosystem: Dateioperationen, Code-Ausführung, Websuche und MCP-Erweiterbarkeit
  • Erweiterte Berechtigungen: Feinkörnige Kontrolle über Agent-Fähigkeiten
  • Produktionsgrundlagen: Eingebaute Fehlerbehandlung, Session-Management und Überwachung

Was können Sie mit dem SDK erstellen?

Hier sind einige Beispiele für Agent-Typen, die Sie erstellen können:

Coding-Agenten:

  • SRE-Agenten, die Produktionsprobleme diagnostizieren und beheben
  • Sicherheitsüberprüfungs-Bots, die Code auf Schwachstellen prüfen
  • Bereitschafts-Engineering-Assistenten, die Vorfälle triagieren
  • Code-Review-Agenten, die Stil und bewährte Praktiken durchsetzen

Business-Agenten:

  • Rechtsassistenten, die Verträge und Compliance überprüfen
  • Finanzberater, die Berichte und Prognosen analysieren
  • Kundensupport-Agenten, die technische Probleme lösen
  • Content-Erstellungsassistenten für Marketing-Teams

Das SDK ist derzeit in TypeScript und Python verfügbar, mit einer Befehlszeilenschnittstelle (CLI) für schnelles Prototyping.

Schnellstart

Bringen Sie Ihren ersten Agenten in unter 5 Minuten zum Laufen:

1

SDK installieren

Installieren Sie @anthropic-ai/claude-code von NPM:

npm install -g @anthropic-ai/claude-code
2

API-Schlüssel setzen

Holen Sie sich Ihren API-Schlüssel aus der Anthropic Console und setzen Sie die Umgebungsvariable ANTHROPIC_API_KEY:

export ANTHROPIC_API_KEY="ihr-api-schlüssel-hier"
3

Ihren ersten Agenten erstellen

Erstellen Sie einen dieser Beispielagenten:

# Erstellen Sie einen einfachen Rechtsassistenten
claude -p "Überprüfen Sie diese Vertragsklausel auf potenzielle Probleme: 'Die Partei stimmt unbegrenzter Haftung zu...'" \
  --append-system-prompt "Sie sind ein Rechtsassistent. Identifizieren Sie Risiken und schlagen Sie Verbesserungen vor."
4

Den Agenten ausführen

Kopieren Sie den obigen Befehl und fügen Sie ihn direkt in Ihr Terminal ein.

Jedes Beispiel oben erstellt einen funktionierenden Agenten, der:

  • Den Prompt mit Claudes Reasoning-Fähigkeiten analysiert
  • Einen mehrstufigen Ansatz zur Problemlösung plant
  • Aktionen mit Tools wie Dateioperationen, Bash-Befehlen und Websuche ausführt
  • Umsetzbare Empfehlungen basierend auf der Analyse bereitstellt

Kernverwendung

Überblick

Das Claude Code SDK ermöglicht es Ihnen, mit Claude Code im nicht-interaktiven Modus aus Ihren Anwendungen zu interagieren.

Voraussetzungen

  • Node.js 18+
  • @anthropic-ai/claude-code von NPM

Grundlegende Verwendung

Die primäre Befehlszeilenschnittstelle zu Claude Code ist der claude-Befehl. Verwenden Sie das --print (oder -p) Flag, um im nicht-interaktiven Modus zu laufen und das Endergebnis zu drucken:

claude -p "Systemleistung analysieren" \
  --append-system-prompt "Sie sind ein Performance-Ingenieur" \
  --allowedTools "Bash,Read,WebSearch" \
  --permission-mode acceptEdits \
  --cwd /pfad/zum/projekt

Konfiguration

Das SDK nutzt alle CLI-Optionen, die in Claude Code verfügbar sind. Hier sind die wichtigsten für die SDK-Verwendung:

FlagBeschreibungBeispiel
--print, -pIm nicht-interaktiven Modus ausführenclaude -p "anfrage"
--output-formatAusgabeformat spezifizieren (text, json, stream-json)claude -p --output-format json
--resume, -rEine Unterhaltung nach Session-ID fortsetzenclaude --resume abc123
--continue, -cDie neueste Unterhaltung fortsetzenclaude --continue
--verboseAusführliche Protokollierung aktivierenclaude --verbose
--append-system-promptAn System-Prompt anhängen (nur mit --print)claude --append-system-prompt "Benutzerdefinierte Anweisung"
--allowedToolsLeerzeichen-getrennte Liste erlaubter Tools, oder

String mit Komma-getrennter Liste erlaubter Tools
claude --allowedTools mcp__slack mcp__filesystem

claude --allowedTools "Bash(npm install),mcp__filesystem"
--disallowedToolsLeerzeichen-getrennte Liste verweigerter Tools, oder

String mit Komma-getrennter Liste verweigerter Tools
claude --disallowedTools mcp__splunk mcp__github

claude --disallowedTools "Bash(git commit),mcp__github"
--mcp-configMCP-Server aus einer JSON-Datei ladenclaude --mcp-config servers.json
--permission-prompt-toolMCP-Tool für die Behandlung von Berechtigungsaufforderungen (nur mit --print)claude --permission-prompt-tool mcp__auth__prompt

Für eine vollständige Liste der CLI-Optionen und -Features siehe die CLI-Referenz Dokumentation.

Authentifizierung

Anthropic API-Schlüssel

Für die grundlegende Authentifizierung holen Sie sich einen Anthropic API-Schlüssel aus der Anthropic Console und setzen Sie die Umgebungsvariable ANTHROPIC_API_KEY, wie im Schnellstart demonstriert.

Drittanbieter-API-Anmeldedaten

Das SDK unterstützt auch die Authentifizierung über Drittanbieter-API-Provider:

  • Amazon Bedrock: Setzen Sie die Umgebungsvariable CLAUDE_CODE_USE_BEDROCK=1 und konfigurieren Sie AWS-Anmeldedaten
  • Google Vertex AI: Setzen Sie die Umgebungsvariable CLAUDE_CODE_USE_VERTEX=1 und konfigurieren Sie Google Cloud-Anmeldedaten

Für detaillierte Konfigurationsanweisungen für Drittanbieter-Provider siehe die Amazon Bedrock und Google Vertex AI Dokumentation.

Mehrstufige Unterhaltungen

Für mehrstufige Unterhaltungen können Sie Unterhaltungen fortsetzen oder von der neuesten Session fortfahren:

# Die neueste Unterhaltung fortsetzen
claude --continue "Refaktorieren Sie dies nun für bessere Leistung"

# Eine spezifische Unterhaltung nach Session-ID fortsetzen
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Die Tests aktualisieren"

# Im nicht-interaktiven Modus fortsetzen
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Alle Linting-Probleme beheben" --no-interactive

Benutzerdefinierte System-Prompts

System-Prompts definieren die Rolle, Expertise und das Verhalten Ihres Agenten. Hier spezifizieren Sie, welche Art von Agent Sie erstellen:

# SRE-Vorfallsreaktions-Agent
claude -p "API ist ausgefallen, untersuchen" \
  --append-system-prompt "Sie sind ein SRE-Experte. Diagnostizieren Sie Probleme systematisch und bieten Sie umsetzbare Lösungen."

# Rechtsdokument-Überprüfungs-Agent  
claude -p "Überprüfen Sie diesen Vertrag" \
  --append-system-prompt "Sie sind ein Unternehmensanwalt. Identifizieren Sie Risiken, schlagen Sie Verbesserungen vor und stellen Sie Compliance sicher."

# An Standard-System-Prompt anhängen
claude -p "Diese Funktion refaktorieren" \
  --append-system-prompt "Schließen Sie immer umfassende Fehlerbehandlung und Unit-Tests ein."

Erweiterte Verwendung

Benutzerdefinierte Tools über MCP

Das Model Context Protocol (MCP) ermöglicht es Ihnen, Ihren Agenten benutzerdefinierte Tools und Fähigkeiten zu geben. Dies ist entscheidend für die Erstellung spezialisierter Agenten, die domänenspezifische Integrationen benötigen.

Beispiel-Agent-Tool-Konfigurationen:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {"SLACK_TOKEN": "ihr-slack-token"}
    },
    "jira": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-jira"],
      "env": {"JIRA_TOKEN": "ihr-jira-token"}
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {"DB_CONNECTION_STRING": "ihre-db-url"}
    }
  }
}

Verwendungsbeispiele:

# SRE-Agent mit Überwachungstools
claude -p "Untersuchen Sie den Ausfall des Zahlungsdienstes" \
  --mcp-config sre-tools.json \
  --allowedTools "mcp__datadog,mcp__pagerduty,mcp__kubernetes" \
  --append-system-prompt "Sie sind ein SRE. Verwenden Sie Überwachungsdaten zur Diagnose von Problemen."

# Kundensupport-Agent mit CRM-Zugang
claude -p "Helfen Sie bei der Lösung des Kundentickets #12345" \
  --mcp-config support-tools.json \
  --allowedTools "mcp__zendesk,mcp__stripe,mcp__user_db" \
  --append-system-prompt "Sie sind ein technischer Support-Spezialist."

Bei der Verwendung von MCP-Tools müssen Sie diese explizit mit dem --allowedTools-Flag erlauben. MCP-Tool-Namen folgen dem Muster mcp__<serverName>__<toolName> wobei:

  • serverName der Schlüssel aus Ihrer MCP-Konfigurationsdatei ist
  • toolName das spezifische Tool ist, das von diesem Server bereitgestellt wird

Diese Sicherheitsmaßnahme stellt sicher, dass MCP-Tools nur verwendet werden, wenn sie explizit erlaubt sind.

Wenn Sie nur den Servernamen angeben (d.h. mcp__<serverName>), werden alle Tools von diesem Server erlaubt.

Glob-Muster (z.B. mcp__go*) werden nicht unterstützt.

Benutzerdefiniertes Berechtigungs-Prompt-Tool

Optional verwenden Sie --permission-prompt-tool, um ein MCP-Tool zu übergeben, das wir verwenden werden, um zu überprüfen, ob der Benutzer dem Modell Berechtigungen zur Ausführung eines bestimmten Tools erteilt. Wenn das Modell ein Tool aufruft, passiert Folgendes:

  1. Wir überprüfen zuerst die Berechtigungseinstellungen: alle settings.json-Dateien, sowie --allowedTools und --disallowedTools, die an das SDK übergeben wurden; wenn eine davon den Tool-Aufruf erlaubt oder verweigert, fahren wir mit dem Tool-Aufruf fort
  2. Andernfalls rufen wir das MCP-Tool auf, das Sie in --permission-prompt-tool bereitgestellt haben

Das --permission-prompt-tool MCP-Tool erhält den Tool-Namen und die Eingabe und muss eine JSON-stringifizierte Payload mit dem Ergebnis zurückgeben. Die Payload muss eine der folgenden sein:

// Tool-Aufruf ist erlaubt
{
  "behavior": "allow",
  "updatedInput": {...}, // aktualisierte Eingabe, oder geben Sie einfach die ursprüngliche Eingabe zurück
}

// Tool-Aufruf ist verweigert
{
  "behavior": "deny",
  "message": "..." // menschenlesbare Zeichenkette, die erklärt, warum die Berechtigung verweigert wurde
}

Implementierungsbeispiele:

# Mit Ihrer MCP-Server-Konfiguration verwenden
claude -p "Analysieren und beheben Sie die Sicherheitsprobleme" \
  --permission-prompt-tool mcp__security__approval_prompt \
  --mcp-config security-tools.json \
  --allowedTools "Read,Grep" \
  --disallowedTools "Bash(rm*),Write"

# Mit benutzerdefinierten Berechtigungsregeln
claude -p "Die Codebasis refaktorieren" \
  --permission-prompt-tool mcp__custom__permission_check \
  --mcp-config custom-config.json \
  --output-format json

Verwendungshinweise:

  • Verwenden Sie updatedInput, um dem Modell mitzuteilen, dass der Berechtigungs-Prompt seine Eingabe mutiert hat; andernfalls setzen Sie updatedInput auf die ursprüngliche Eingabe, wie im obigen Beispiel. Wenn das Tool beispielsweise einem Benutzer ein Dateibearbeitungs-Diff zeigt und ihm erlaubt, das Diff manuell zu bearbeiten, sollte das Berechtigungs-Prompt-Tool diese aktualisierte Bearbeitung zurückgeben.
  • Die Payload muss JSON-stringifiziert sein

Ausgabeformate

Das SDK unterstützt mehrere Ausgabeformate:

Textausgabe (Standard)

claude -p "Erklären Sie die Datei src/components/Header.tsx"
# Ausgabe: Dies ist eine React-Komponente, die...

JSON-Ausgabe

Gibt strukturierte Daten einschließlich Metadaten zurück:

claude -p "Wie funktioniert die Datenschicht?" --output-format json

Antwortformat:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "Der Antworttext hier...",
  "session_id": "abc123"
}

Streaming-JSON-Ausgabe

Streamt jede Nachricht, während sie empfangen wird:

$ claude -p "Eine Anwendung erstellen" --output-format stream-json

Jede Unterhaltung beginnt mit einer anfänglichen init-Systemnachricht, gefolgt von einer Liste von Benutzer- und Assistentennachrichten, gefolgt von einer finalen result-Systemnachricht mit Statistiken. Jede Nachricht wird als separates JSON-Objekt ausgegeben.

Nachrichtenschema

Nachrichten, die von der JSON-API zurückgegeben werden, sind streng typisiert nach folgendem Schema:

type SDKMessage =
  // Eine Assistentennachricht
  | {
      type: "assistant";
      message: Message; // aus Anthropic SDK
      session_id: string;
    }

  // Eine Benutzernachricht
  | {
      type: "user";
      message: MessageParam; // aus Anthropic SDK
      session_id: string;
    }

  // Als letzte Nachricht ausgegeben
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // Als letzte Nachricht ausgegeben, wenn wir die maximale Anzahl von Zügen erreicht haben
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // Als erste Nachricht zu Beginn einer Unterhaltung ausgegeben
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

Wir werden diese Typen bald in einem JSONSchema-kompatiblen Format veröffentlichen. Wir verwenden semantische Versionierung für das Haupt-Claude Code-Paket, um Breaking Changes an diesem Format zu kommunizieren.

Message- und MessageParam-Typen sind in Anthropic SDKs verfügbar. Siehe zum Beispiel die Anthropic TypeScript und Python SDKs.

Eingabeformate

Das SDK unterstützt mehrere Eingabeformate:

Texteingabe (Standard)

# Direktes Argument
claude -p "Erklären Sie diesen Code"

# Von stdin
echo "Erklären Sie diesen Code" | claude -p

Streaming-JSON-Eingabe

Ein Stream von Nachrichten, die über stdin bereitgestellt werden, wobei jede Nachricht einen Benutzerzug darstellt. Dies ermöglicht mehrere Züge einer Unterhaltung, ohne das claude-Binary neu zu starten, und ermöglicht es, dem Modell Anleitung zu geben, während es eine Anfrage verarbeitet.

Jede Nachricht ist ein JSON-‘Benutzernachricht’-Objekt, das demselben Format wie das Ausgabenachrichtenschema folgt. Nachrichten werden im jsonl-Format formatiert, wobei jede Eingabezeile ein vollständiges JSON-Objekt ist. Streaming-JSON-Eingabe erfordert -p und --output-format stream-json.

Derzeit ist dies auf reine Textnachrichten beschränkt.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Erklären Sie diesen Code"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Agent-Integrationsbeispiele

SRE-Vorfallsreaktions-Bot

#!/bin/bash

# Automatisierter Vorfallsreaktions-Agent
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"
    
    claude -p "Vorfall: $incident_description (Schweregrad: $severity)" \
      --append-system-prompt "Sie sind ein SRE-Experte. Diagnostizieren Sie das Problem, bewerten Sie die Auswirkungen und stellen Sie sofortige Aktionspunkte bereit." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Verwendung
investigate_incident "Zahlungs-API gibt 500-Fehler zurück" "hoch"

Automatisierte Sicherheitsüberprüfung

# Sicherheitsprüfungs-Agent für Pull Requests
audit_pr() {
    local pr_number="$1"
    
    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "Sie sind ein Sicherheitsingenieur. Überprüfen Sie diesen PR auf Schwachstellen, unsichere Muster und Compliance-Probleme." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Verwendung und in Datei speichern
audit_pr 123 > security-report.json

Mehrstufiger Rechtsassistent

# Rechtsdokument-Überprüfung mit Session-Persistenz
session_id=$(claude -p "Rechtsüberprüfungs-Session starten" --output-format json | jq -r '.session_id')

# Vertrag in mehreren Schritten überprüfen
claude -p --resume "$session_id" "Vertrag.pdf auf Haftungsklauseln überprüfen"
claude -p --resume "$session_id" "Compliance mit DSGVO-Anforderungen prüfen" 
claude -p --resume "$session_id" "Zusammenfassung der Risiken für Führungskräfte generieren"

Python-spezifische bewährte Praktiken

Schlüsselmuster

import asyncio
from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions

# Verwenden Sie immer Kontext-Manager
async with ClaudeSDKClient() as client:
    await client.query("Analysieren Sie diesen Code")
    async for msg in client.receive_response():
        # Streaming-Nachrichten verarbeiten
        pass

# Mehrere Agenten gleichzeitig ausführen
async with ClaudeSDKClient() as reviewer, ClaudeSDKClient() as tester:
    await asyncio.gather(
        reviewer.query("main.py überprüfen"),
        tester.query("Tests für main.py schreiben")
    )

# Fehlerbehandlung
from claude_code_sdk import CLINotFoundError, ProcessError

try:
    async with ClaudeSDKClient() as client:
        # Ihr Code hier
        pass
except CLINotFoundError:
    print("CLI installieren: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"Prozessfehler: {e}")

# Vollständige Antwort mit Metadaten sammeln
async def get_response(client, prompt):
    await client.query(prompt)
    text = []
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    text.append(block.text)
        if type(msg).__name__ == "ResultMessage":
            return {'text': ''.join(text), 'cost': msg.total_cost_usd}

IPython/Jupyter-Tipps

# In Jupyter verwenden Sie await direkt in Zellen
client = ClaudeSDKClient()
await client.connect()
await client.query("data.csv analysieren")
async for msg in client.receive_response():
    print(msg)
await client.disconnect()

# Wiederverwendbare Hilfsfunktionen erstellen
async def stream_print(client, prompt):
    await client.query(prompt)
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    print(block.text, end='', flush=True)

Bewährte Praktiken

  • JSON-Ausgabeformat verwenden für programmatisches Parsen von Antworten:

    # JSON-Antwort mit jq parsen
    result=$(claude -p "Code generieren" --output-format json)
    code=$(echo "$result" | jq -r '.result')
    cost=$(echo "$result" | jq -r '.cost_usd')
    
  • Fehler elegant behandeln - Exit-Codes und stderr prüfen:

    if ! claude -p "$prompt" 2>error.log; then
        echo "Fehler aufgetreten:" >&2
        cat error.log >&2
        exit 1
    fi
    
  • Session-Management verwenden für die Aufrechterhaltung des Kontexts in mehrstufigen Unterhaltungen

  • Timeouts berücksichtigen für langwierige Operationen:

    timeout 300 claude -p "$complex_prompt" || echo "Timeout nach 5 Minuten"
    
  • Rate Limits respektieren bei mehreren Anfragen durch Hinzufügen von Verzögerungen zwischen Aufrufen

Verwandte Ressourcen