Claude Code SDK
Erstellen Sie benutzerdefinierte KI-Agenten mit dem Claude Code SDK
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:
SDK installieren
Installieren Sie @anthropic-ai/claude-code
von NPM:
Installieren Sie @anthropic-ai/claude-code
von NPM:
Installieren Sie @anthropic-ai/claude-code
von NPM:
Installieren Sie claude-code-sdk
von PyPI und @anthropic-ai/claude-code
von NPM:
(Optional) Installieren Sie IPython für interaktive Entwicklung:
API-Schlüssel setzen
Holen Sie sich Ihren API-Schlüssel aus der Anthropic Console und setzen Sie die Umgebungsvariable ANTHROPIC_API_KEY
:
Ihren ersten Agenten erstellen
Erstellen Sie einen dieser Beispielagenten:
Den Agenten ausführen
Kopieren Sie den obigen Befehl und fügen Sie ihn direkt in Ihr Terminal ein.
Kopieren Sie den obigen Befehl und fügen Sie ihn direkt in Ihr Terminal ein.
- Projekt einrichten:
-
Fügen Sie
"type": "module"
zu Ihrer package.json hinzu -
Speichern Sie den obigen Code als
legal-agent.ts
und führen Sie dann aus:
Speichern Sie den obigen Code als legal-agent.py
und führen Sie dann aus:
Für IPython/Jupyter-Notebooks können Sie den Code direkt in einer Zelle ausführen:
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:
Konfiguration
Das SDK nutzt alle CLI-Optionen, die in Claude Code verfügbar sind. Hier sind die wichtigsten für die SDK-Verwendung:
Flag | Beschreibung | Beispiel |
---|---|---|
--print , -p | Im nicht-interaktiven Modus ausführen | claude -p "anfrage" |
--output-format | Ausgabeformat spezifizieren (text , json , stream-json ) | claude -p --output-format json |
--resume , -r | Eine Unterhaltung nach Session-ID fortsetzen | claude --resume abc123 |
--continue , -c | Die neueste Unterhaltung fortsetzen | claude --continue |
--verbose | Ausführliche Protokollierung aktivieren | claude --verbose |
--append-system-prompt | An System-Prompt anhängen (nur mit --print ) | claude --append-system-prompt "Benutzerdefinierte Anweisung" |
--allowedTools | Leerzeichen-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" |
--disallowedTools | Leerzeichen-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-config | MCP-Server aus einer JSON-Datei laden | claude --mcp-config servers.json |
--permission-prompt-tool | MCP-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.
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:
Konfiguration
Das SDK nutzt alle CLI-Optionen, die in Claude Code verfügbar sind. Hier sind die wichtigsten für die SDK-Verwendung:
Flag | Beschreibung | Beispiel |
---|---|---|
--print , -p | Im nicht-interaktiven Modus ausführen | claude -p "anfrage" |
--output-format | Ausgabeformat spezifizieren (text , json , stream-json ) | claude -p --output-format json |
--resume , -r | Eine Unterhaltung nach Session-ID fortsetzen | claude --resume abc123 |
--continue , -c | Die neueste Unterhaltung fortsetzen | claude --continue |
--verbose | Ausführliche Protokollierung aktivieren | claude --verbose |
--append-system-prompt | An System-Prompt anhängen (nur mit --print ) | claude --append-system-prompt "Benutzerdefinierte Anweisung" |
--allowedTools | Leerzeichen-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" |
--disallowedTools | Leerzeichen-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-config | MCP-Server aus einer JSON-Datei laden | claude --mcp-config servers.json |
--permission-prompt-tool | MCP-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.
Voraussetzungen
- Node.js 18+
@anthropic-ai/claude-code
von NPM
Um den TypeScript SDK-Quellcode anzuzeigen, besuchen Sie die @anthropic-ai/claude-code
Seite auf NPM.
Grundlegende Verwendung
Die primäre Schnittstelle über das TypeScript SDK ist die query
-Funktion, die einen async Iterator zurückgibt, der Nachrichten streamt, während sie ankommen:
Konfiguration
Das TypeScript SDK akzeptiert alle Argumente, die von der Befehlszeile unterstützt werden, sowie die folgenden zusätzlichen Optionen:
Argument | Beschreibung | Standard |
---|---|---|
abortController | Abort Controller | new AbortController() |
cwd | Aktuelles Arbeitsverzeichnis | process.cwd() |
executable | Welche JavaScript-Laufzeit zu verwenden | node beim Ausführen mit Node.js, bun beim Ausführen mit Bun |
executableArgs | Argumente an die ausführbare Datei zu übergeben | [] |
pathToClaudeCodeExecutable | Pfad zur Claude Code ausführbaren Datei | Ausführbare Datei, die mit @anthropic-ai/claude-code geliefert wird |
Voraussetzungen
- Python 3.10+
claude-code-sdk
von PyPI- Node.js 18+
@anthropic-ai/claude-code
von NPM
Um den Python SDK-Quellcode anzuzeigen, siehe das claude-code-sdk
Repository.
Für interaktive Entwicklung verwenden Sie IPython: pip install ipython
Grundlegende Verwendung
Das Python SDK bietet zwei primäre Schnittstellen:
- Die
ClaudeSDKClient
-Klasse (Empfohlen)
Am besten für Streaming-Antworten, mehrstufige Unterhaltungen und interaktive Anwendungen:
Das SDK unterstützt auch das Übergeben strukturierter Nachrichten und Bildeingaben:
Die Python-Beispiele auf dieser Seite verwenden asyncio
, aber Sie können auch anyio
verwenden.
- Die
query
-Funktion
Für einfache, einmalige Anfragen:
Konfiguration
Da das Python SDK alle Argumente akzeptiert, die von der Befehlszeile über die ClaudeCodeOptions
-Klasse unterstützt werden.
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:
Benutzerdefinierte System-Prompts
System-Prompts definieren die Rolle, Expertise und das Verhalten Ihres Agenten. Hier spezifizieren Sie, welche Art von Agent Sie erstellen:
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:
Verwendungsbeispiele:
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 isttoolName
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:
- 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 - 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:
Implementierungsbeispiele:
Verwendungshinweise:
- Verwenden Sie
updatedInput
, um dem Modell mitzuteilen, dass der Berechtigungs-Prompt seine Eingabe mutiert hat; andernfalls setzen SieupdatedInput
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)
JSON-Ausgabe
Gibt strukturierte Daten einschließlich Metadaten zurück:
Antwortformat:
Streaming-JSON-Ausgabe
Streamt jede Nachricht, während sie empfangen wird:
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:
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)
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.
Agent-Integrationsbeispiele
SRE-Vorfallsreaktions-Bot
Automatisierte Sicherheitsüberprüfung
Mehrstufiger Rechtsassistent
Python-spezifische bewährte Praktiken
Schlüsselmuster
IPython/Jupyter-Tipps
Bewährte Praktiken
-
JSON-Ausgabeformat verwenden für programmatisches Parsen von Antworten:
-
Fehler elegant behandeln - Exit-Codes und stderr prüfen:
-
Session-Management verwenden für die Aufrechterhaltung des Kontexts in mehrstufigen Unterhaltungen
-
Timeouts berücksichtigen für langwierige Operationen:
-
Rate Limits respektieren bei mehreren Anfragen durch Hinzufügen von Verzögerungen zwischen Aufrufen
Verwandte Ressourcen
- CLI-Verwendung und -Steuerung - Vollständige CLI-Dokumentation
- GitHub Actions-Integration - Automatisieren Sie Ihren GitHub-Workflow mit Claude
- Häufige Workflows - Schritt-für-Schritt-Anleitungen für häufige Anwendungsfälle