Zum Hauptinhalt springen
Das Agent SDK bietet Ihnen die gleichen Tools, die Agent-Schleife und das Kontextmanagement, die Claude Code antreiben. Es ist als CLI für Skripte und CI/CD verfügbar oder als Python und TypeScript Pakete für vollständige programmgesteuerte Kontrolle.
Die CLI hieß früher „Headless-Modus”. Das Flag -p und alle CLI-Optionen funktionieren auf die gleiche Weise.
Um Claude Code programmgesteuert über die CLI auszuführen, übergeben Sie -p mit Ihrer Eingabeaufforderung und allen CLI-Optionen: 
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
Diese Seite behandelt die Verwendung des Agent SDK über die CLI (claude -p). Für die Python- und TypeScript-SDK-Pakete mit strukturierten Ausgaben, Tool-Genehmigungsrückrufen und nativen Nachrichtenobjekten siehe die vollständige Agent SDK-Dokumentation.

​
Grundlegende Verwendung

Fügen Sie das Flag -p (oder --print) zu jedem claude-Befehl hinzu, um ihn nicht-interaktiv auszuführen. Alle CLI-Optionen funktionieren mit -p, einschließlich: Dieses Beispiel stellt Claude eine Frage zu Ihrer Codebasis und gibt die Antwort aus: 
claude -p "What does the auth module do?"

​
Beispiele

Diese Beispiele zeigen häufige CLI-Muster.

​
Strukturierte Ausgabe abrufen

Verwenden Sie --output-format, um zu steuern, wie Antworten zurückgegeben werden:
  • text (Standard): einfache Textausgabe
  • json: strukturiertes JSON mit Ergebnis, Sitzungs-ID und Metadaten
  • stream-json: zeilengetrennte JSON für Echtzeit-Streaming
Dieses Beispiel gibt eine Projektzusammenfassung als JSON mit Sitzungsmetadaten zurück, wobei sich das Textergebnis im Feld result befindet: 
claude -p "Summarize this project" --output-format json
Um eine Ausgabe zu erhalten, die einem bestimmten Schema entspricht, verwenden Sie --output-format json mit --json-schema und einer JSON Schema-Definition. Die Antwort enthält Metadaten über die Anfrage (Sitzungs-ID, Nutzung usw.) mit der strukturierten Ausgabe im Feld structured_output. Dieses Beispiel extrahiert Funktionsnamen und gibt sie als Array von Zeichenketten zurück: 
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
Verwenden Sie ein Tool wie jq, um die Antwort zu analysieren und bestimmte Felder zu extrahieren:
# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

​
Antworten streamen

Verwenden Sie --output-format stream-json mit --verbose und --include-partial-messages, um Token zu empfangen, während sie generiert werden. Jede Zeile ist ein JSON-Objekt, das ein Ereignis darstellt: 
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages
Das folgende Beispiel verwendet jq, um nach Text-Deltas zu filtern und nur den Streaming-Text anzuzeigen. Das Flag -r gibt rohe Zeichenketten aus (keine Anführungszeichen) und -j verbindet ohne Zeilenumbrüche, sodass Token kontinuierlich streamen: 
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'
Für programmgesteuertes Streaming mit Rückrufen und Nachrichtenobjekten siehe Antworten in Echtzeit streamen in der Agent SDK-Dokumentation.

​
Tools automatisch genehmigen

Verwenden Sie --allowedTools, um Claude bestimmte Tools ohne Aufforderung zu verwenden. Dieses Beispiel führt eine Test-Suite aus und behebt Fehler, wobei Claude Bash-Befehle ausführen und Dateien lesen/bearbeiten kann, ohne um Erlaubnis zu fragen: 
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

​
Einen Commit erstellen

Dieses Beispiel überprüft bereitgestellte Änderungen und erstellt einen Commit mit einer angemessenen Nachricht: 
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"
Das Flag --allowedTools verwendet Berechtigungsregelsyntax. Das nachfolgende * ermöglicht Präfix-Matching, sodass Bash(git diff *) jeden Befehl erlaubt, der mit git diff beginnt. Das Leerzeichen vor * ist wichtig: ohne es würde Bash(git diff*) auch git diff-index entsprechen.
Benutzer-aufgerufene skills wie /commit und integrierte Befehle sind nur im interaktiven Modus verfügbar. Im -p-Modus beschreiben Sie stattdessen die Aufgabe, die Sie ausführen möchten.

​
System-Eingabeaufforderung anpassen

Verwenden Sie --append-system-prompt, um Anweisungen hinzuzufügen und dabei das Standardverhalten von Claude Code beizubehalten. Dieses Beispiel leitet einen PR-Diff an Claude weiter und weist ihn an, auf Sicherheitslücken zu überprüfen: 
gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json
Siehe System-Eingabeaufforderungs-Flags für weitere Optionen, einschließlich --system-prompt, um die Standardeingabeaufforderung vollständig zu ersetzen.

​
Gespräche fortsetzen

Verwenden Sie --continue, um das neueste Gespräch fortzusetzen, oder --resume mit einer Sitzungs-ID, um ein bestimmtes Gespräch fortzusetzen. Dieses Beispiel führt eine Überprüfung durch und sendet dann Folgeeingabeaufforderungen: 
# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
Wenn Sie mehrere Gespräche führen, erfassen Sie die Sitzungs-ID, um ein bestimmtes fortzusetzen: 
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

​
Nächste Schritte

Agent SDK Schnellstart

Erstellen Sie Ihren ersten Agent mit Python oder TypeScript

CLI-Referenz

Erkunden Sie alle CLI-Flags und Optionen

GitHub Actions

Verwenden Sie das Agent SDK in GitHub-Workflows

GitLab CI/CD

Verwenden Sie das Agent SDK in GitLab-Pipelines