Leitfaden zur Verwendung des Claude Agent SDK

Das Claude Agent SDK ermöglicht Ihnen, KI-Agenten zu erstellen, die autonom Dateien lesen, Befehle ausführen, das Web durchsuchen, Code bearbeiten und vieles mehr.

Das Claude Agent SDK stellt die Tools, den Agent-Loop und die Kontextverwaltungsfunktionen bereit, die Claude Code als programmierbare Python- und TypeScript-Bibliotheken antreiben.

Einfach ausgedrückt ist dies ein SDK, das Claude Code als Bibliothek verwendet. Sie können es in Ihre eigenen Anwendungen, CI-Pipelines oder Automatisierungsskripte einbetten, um KI-Agenten zu erstellen, die komplexe Aufgaben autonom erledigen können.

Kernfähigkeiten

Das SDK enthält integrierte Tools zum Lesen von Dateien, Ausführen von Befehlen und Bearbeiten von Code. Ihr Agent muss die Tool-Ausführungslogik nicht selbst implementieren und kann sofort mit der Arbeit beginnen. Zu den wichtigsten Funktionen gehören:

Fähigkeit	Beschreibung
Integrierte Tools	Dateien lesen/schreiben, Terminalbefehle, Codebearbeitung, Websuche usw.
Hooks	Benutzerdefinierte Logik vor und nach Tool-Aufrufen ausführen
Subagenten	Große Aufgaben in kleinere aufteilen und sie an unabhängige Subagenten zur parallelen Ausführung delegieren
MCP-Server	Verbindung zu Datenbanken, Browsern, externen APIs usw.
Berechtigungskontrolle	Steuern Sie präzise, was der Agent tun kann und wann eine Benutzergenehmigung erforderlich ist
Sitzungsverwaltung	Erstellen Sie Multi-Turn-Konversationsagenten, die den Kontext beibehalten

Voraussetzungen

Node.js 18+(TypeScript) oderPython 3.10+
EinAnthropic-Konto, und erhalten Sie einen API-Schlüssel (Hier registrieren）

Schritt 1: Installieren Sie das SDK

TypeScript

npm install @anthropic-ai/claude-agent-sdk

Das TypeScript-SDK bündelt die Claude-Code-Binärdatei für Ihre aktuelle Plattform als optionale Abhängigkeit, sodass Claude Code nicht separat installiert werden muss.

Python

# 使用 pip
pip install claude-agent-sdk

# 或使用 uv（推荐）
uv add claude-agent-sdk

Hinweis: Die Claude-Code-CLI wird automatisch mit dem Paket installiert – keine separate Installation erforderlich! Das SDK verwendet standardmäßig die mitgelieferte CLI.
Wenn Sie eine Installation auf Systemebene oder eine bestimmte Version bevorzugen, können Sie verwendenClaudeAgentOptions(cli_path="/path/to/claude")Geben Sie einen Pfad an.

Schritt 2: API-Schlüssel konfigurieren

VonClaude Consoleeinen API-Schlüssel abrufen und dann eine Datei im Projektverzeichnis erstellen:.envDatei:

ANTHROPIC_API_KEY=your-api-key-here

Oder legen Sie ihn direkt als Umgebungsvariable fest:

export ANTHROPIC_API_KEY=your-api-key-here

Unterstützung für Cloud-Plattformen von Drittanbietern

Das SDK unterstützt auch die Authentifizierung über API-Anbieter von Drittanbietern: Amazon Bedrock (setzen Sie dieCLAUDE_CODE_USE_BEDROCK=1Umgebungsvariable und konfigurieren Sie AWS-Anmeldeinformationen), Google Vertex AI (setzenCLAUDE_CODE_USE_VERTEX=1) und Microsoft Azure (setzenCLAUDE_CODE_USE_FOUNDRY=1）。

⚠️ Wichtig: Sofern keine vorherige Genehmigung von Anthropic eingeholt wurde, ist es Drittanbieter-Entwicklern nicht erlaubt, claude.ai-Login oder Ratenbegrenzung in Produkten anzubieten, die auf dem Claude Agent SDK basieren. Bitte verwenden Sie die in der Dokumentation beschriebene API-Schlüssel-Authentifizierungsmethode.

Schritt 3: Führen Sie Ihren ersten Agenten aus

Das folgende Beispiel erstellt einen Agenten, der Dateien im aktuellen Verzeichnis auflistet:

Python

Beispiel

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
async for message in query(
prompt="Welche Dateien sind in diesem Verzeichnis?",
options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
):
if hasattr(message, "result"):
print(message.result)

asyncio.run(main())

TypeScript

Beispiel

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
for await (const message of query({
prompt: "Welche Dateien sind in diesem Verzeichnis?",
options: { allowedTools: ["Bash", "Glob"] },
})) {
if ("result" in message) {
console.log(message.result);
}
}
}

main();

Praktisch: Erstellen Sie einen Agenten, der Fehler automatisch behebt

Das Folgende ist ein vollständiges Beispiel, das die Kernverwendung des Agent SDK demonstriert.

Bereiten Sie eine Datei mit einem Fehler vor

Erstelleutils.py, mit zwei absichtlichen Fehlern:

Beispiel

def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers) # Fehler: Division durch 0, wenn die Liste leer ist

def get_user_name(user):
return user["name"].upper() # Fehler: löst TypeError aus, wenn user None ist

Schreiben Sie den Agenten

Erstelleagent.py：

Beispiel

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
async for message in query(
prompt="Überprüfe utils.py auf Fehler, die Abstürze verursachen würden. Behebe alle Probleme, die du findest.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"], # Erlaubte Tools
permission_mode="acceptEdits", # Dateiänderungen automatisch genehmigen
),
):
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text) # Claudes Denkprozess
elif hasattr(block, "name"):
print(f"Werkzeug: {block.name}") # Werkzeug wird aufgerufen
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}") # Endergebnis

asyncio.run(main())

Führen Sie

python agent.py

Nach der Ausführung prüfenutils.py, werden Sie sehen, dass der Agent die folgenden Aktionen autonom ausgeführt hat:

Gelesenbereitsutils.pyDatei
Analysiertdie Codelogik, Randfälle identifiziert, die Abstürze verursachen könnten
Bearbeitetdie Datei, umfassende Fehlerbehandlung hinzugefügt

Kernkonzepte erklärt

Funktionen – Einstiegspunkt in die Agent-Schleife

queryist der Haupteinstiegspunkt zum Erstellen einer Agent-Schleife, gibt einen Async-Iterator zurück, sodass Sie ihn verwenden, umasync forNachrichten von Claude in Echtzeit zu streamen. Die Schleife endet, wenn Claude die Aufgabe abschließt oder auf einen Fehler stößt. Das SDK übernimmt die Orchestrierung (Tool-Ausführung, Kontextverwaltung, Wiederholungsversuche), und Sie müssen nur diesen Nachrichtenstrom konsumieren.

Jede Iteration erzeugt eine Nachricht, die Folgendes sein kann:

Claudes Denkprozess
Ein Tool-Aufruf
Ergebnis des Tool-Aufrufs
Endergebnis

Tools – Steuern, was der Agent tun kann

Tool-Kombinationen	Agent-Fähigkeiten
`Read`, `Glob`, `Grep`	Schreibgeschützte Analyse
`Read`, `Edit`, `Glob`	Code analysieren und ändern
`Read`, `Edit`, `Bash`, `Glob`, `Grep`	Vollautomatisierung
Plus`WebSearch`	Websuchfunktion hinzufügen

Berechtigungsmodi – Grad der menschlichen Aufsicht steuern

Mode	Verhalten	Anwendungsfall
`acceptEdits`	Dateibearbeitungen automatisch genehmigen, andere Vorgänge erfordern weiterhin eine Bestätigung	Vertrauenswürdiger Entwicklungsworkflow
`dontAsk`	Verweigern`allowedTools`alle Vorgänge außerhalb von	Abgeriegelter unbeaufsichtigter Agent
`auto`(nur TypeScript)	Modellklassifikator genehmigt/verweigert automatisch jeden Tool-Aufruf	Autonomer Agent mit Sicherheitsleitplanken
`bypassPermissions`	Alle Tools direkt ohne Nachfrage ausführen	CI-Umgebung in einer Sandbox
`default`	Muss bereitstellen`canUseTool`Callback zur Genehmigung	Benutzerdefinierter Genehmigungsprozess

Agent-Verhalten anpassen

Websuche hinzufügen

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"],
    permission_mode="acceptEdits"
)

Benutzerdefinierte System-Prompts hinzufügen

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

Ausführung von Terminal-Befehlen erlauben

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"],
    permission_mode="acceptEdits"
)
# 可以尝试：
# prompt="Write unit tests for utils.py, run them, and fix any failures"

Projektkonfiguration laden (CLAUDE.md usw.)

Das SDK basiert auf derselben Grundlage wie Claude Code, und SDK-Agents können auf dieselben dateisystembasierten Funktionen zugreifen: Projektanweisungen (CLAUDE.md und Hooks, Standardmäßig lädt das SDK keine Dateisystemeinstellungen.

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit"],
    # "user" 从 ~/.claude/ 加载，"project" 从 ./.claude/ 加载
    setting_sources=["user", "project"],
)

Fehlerbehandlung

from claude_agent_sdk import (
    ClaudeSDKError,      # 基础错误
    CLINotFoundError,    # Claude Code 未安装
    CLIConnectionError,  # 连接问题
    ProcessError,        # 进程失败
    CLIJSONDecodeError,  # JSON 解析失败
)

try:
    async for message in query(prompt="Hello"):
        pass
except CLINotFoundError:
    print("请先安装 Claude Code")
except ProcessError as e:
    print(f"进程失败，退出码：{e.exit_code}")
except CLIJSONDecodeError as e:
    print(f"响应解析失败：{e}")

Agent SDK vs. andere Claude-Tools

	Agent SDK	Client SDK（Messages API）	Claude Code CLI
Nutzung	Python/TypeScript-Bibliothek	HTTP-API-Aufrufe	Terminal-Kommandozeilenwerkzeug
Tool-Ausführung	Integriert, automatische Ausführung	Erfordert manuelle Implementierung	Integriert, interaktiv
Anwendungsfall	Aufbau autonomer Agenten, Anwendungsintegration	Allgemeine LLM-Aufrufe	Direkte Unterstützung beim Programmieren
Zustandsverwaltung	Zustandsbehaftet, unterstützt Sitzungen	Zustandslos	Zustandsbehaftet, interaktiv

SDK-Funktionsvergleichstabelle

Das SDK unterstützt auch die dateisystembasierte Konfiguration von Claude Code. Um diese Funktionen zu verwenden, legen Sie sie in den Optionen festsetting_sources=["project"](Python) odersettingSources: ['project'](TypeScript).

Merkmal	Beschreibung	Ort
Skills	Spezialisierte Funktionen, die in Markdown definiert sind	`.claude/skills/*/SKILL.md`
Slash-Befehle	Benutzerdefinierte Befehle für häufige Aufgaben	`.claude/commands/*.md`
Gedächtnis	Projektkontext und Anweisungen	`CLAUDE.md`
Plugins	Über`plugins`Optionserweiterungen	Über Code konfiguriert

Weitere Erweiterungen