- Ein Projekt mit dem Agent SDK einrichten
- Eine Datei mit fehlerhaftem Code erstellen
- Einen Agenten ausführen, der Fehler automatisch findet und behebt
Voraussetzungen
- Node.js 18+ oder Python 3.10+
- Ein Anthropic-Konto. Falls Sie noch kein Konto haben, registrieren Sie sich hier.
Einrichtung
1
Erstellen Sie einen Projektordner
Erstellen Sie ein neues Verzeichnis für diesen Schnellstart:Für Ihre eigenen Projekte können Sie das SDK aus jedem Ordner ausführen; es hat standardmäßig Zugriff auf Dateien in diesem Verzeichnis und seinen Unterverzeichnissen.
2
Installieren Sie das SDK
Installieren Sie das Agent SDK-Paket für Ihre Sprache:Das Setzen von
- TypeScript (neues Projekt)
- TypeScript (bestehendes Projekt)
- Python (uv)
- Python (pip)
"type": "module" in package.json ermöglicht Ihrem Agent-Skript die Verwendung von Top-Level-await, und tsx führt TypeScript-Dateien direkt aus. npm gibt added N packages aus, wenn die Installation erfolgreich ist.Sowohl das TypeScript als auch das Python SDK bündeln eine native Claude Code-Binärdatei, daher benötigen die meisten Installationen keine separate Claude Code-Installation. Einige Installationen haben keine gebündelte Binärdatei:
- Wenn pip die Python SDK-Quelldistribution anstelle eines Plattform-Wheels installiert, beispielsweise auf ARM64 Windows, wird keine Binärdatei gebündelt. Installieren Sie Claude Code nativ. Das Python SDK findet es auf Ihrem
PATH. - Das TypeScript SDK installiert seine Binärdatei über npm optionale Abhängigkeiten, daher erhält eine Installation, die diese überspringt, beispielsweise
npm ci --omit=optional, auch auf einer unterstützten Plattform keine Binärdatei. Installieren Sie erneut, ohne optionale Abhängigkeiten zu überspringen, oder installieren Sie Claude Code nativ und setzen SiepathToClaudeCodeExecutableauf seinen Pfad.
3
Legen Sie Ihren API-Schlüssel fest
Rufen Sie einen API-Schlüssel von der Claude-Konsole ab und legen Sie ihn dann als Umgebungsvariable in der Shell fest, in der Sie Ihren Agenten ausführen:Das SDK liest den Schlüssel aus der Umgebung des Prozesses, der Ihren Agenten ausführt; es lädt
- macOS / Linux
- Windows (PowerShell)
.env-Dateien nicht automatisch. Wenn Sie den Schlüssel in einer .env-Datei speichern, laden Sie ihn selbst, beispielsweise mit dem dotenv-Paket, bevor Sie das SDK aufrufen.Das SDK unterstützt auch Authentifizierung über Drittanbieter-API-Anbieter:- Amazon Bedrock: Setzen Sie die Umgebungsvariable
CLAUDE_CODE_USE_BEDROCK=1und konfigurieren Sie AWS-Anmeldedaten - Claude Platform on AWS: Setzen Sie
CLAUDE_CODE_USE_ANTHROPIC_AWS=1undANTHROPIC_AWS_WORKSPACE_IDund konfigurieren Sie AWS-Anmeldedaten - Google Cloud’s Agent Platform: Setzen Sie die Umgebungsvariable
CLAUDE_CODE_USE_VERTEX=1und konfigurieren Sie Google Cloud-Anmeldedaten - Microsoft Foundry: Setzen Sie die Umgebungsvariable
CLAUDE_CODE_USE_FOUNDRY=1und konfigurieren Sie Azure-Anmeldedaten
Sofern nicht zuvor genehmigt, erlaubt Anthropic Drittentwicklern nicht, claude.ai-Anmeldungen oder Rate-Limits für ihre Produkte anzubieten, einschließlich Agenten, die auf dem Claude Agent SDK basieren. Verwenden Sie stattdessen die in diesem Dokument beschriebenen API-Schlüssel-Authentifizierungsmethoden.
Erstellen Sie eine fehlerhafte Datei
Dieser Schnellstart führt Sie durch die Erstellung eines Agenten, der Fehler im Code finden und beheben kann. Zunächst benötigen Sie eine Datei mit einigen absichtlichen Fehlern, die der Agent beheben kann. Erstellen Sieutils.py im Verzeichnis my-agent und fügen Sie den folgenden Code ein:
calculate_average([])stürzt mit Division durch Null abget_user_name(None)stürzt mit einem TypeError ab
Erstellen Sie einen Agenten, der Fehler findet und behebt
Erstellen Sieagent.py, wenn Sie das Python SDK verwenden, oder agent.ts für TypeScript. Verwenden Sie agent.mts stattdessen, wenn Ihr bestehendes Projekt CommonJS verwendet:
-
query: der Haupteinstiegspunkt, der die agentic loop erstellt. Er gibt einen asynchronen Iterator zurück, daher verwenden Sieasync for, um Nachrichten zu streamen, während Claude arbeitet. Siehe die vollständige API in der Python oder TypeScript SDK-Referenz. -
prompt: was Sie Claude tun möchten. Claude ermittelt basierend auf der Aufgabe, welche Tools verwendet werden sollen. -
options: Konfiguration für den Agenten. Dieses Beispiel verwendetallowedTools, umRead,EditundGlobvorab zu genehmigen, undpermissionMode: "acceptEdits", um Dateiänderungen automatisch zu genehmigen. Weitere Optionen sindsystemPrompt,mcpServersund mehr. Siehe alle Optionen für Python oder TypeScript.
async for-Schleife läuft weiter, während Claude denkt, Tools aufruft, Ergebnisse beobachtet und entscheidet, was als nächstes zu tun ist. Jede Iteration ergibt eine Nachricht: Claudes Überlegung, ein Tool-Aufruf, ein Tool-Ergebnis oder das endgültige Ergebnis. Das SDK verwaltet die Orchestrierung, Tool-Ausführung, Kontextverwaltung und Wiederholungen, sodass Sie einfach den Stream verbrauchen. Die Schleife endet, wenn Claude die Aufgabe abschließt oder auf einen Fehler stößt.
Die Nachrichtenbehandlung in der Schleife filtert nach benutzerfreundlicher Ausgabe. Ohne Filterung würden Sie rohe Nachrichtenobjekte sehen, einschließlich Systeminitialisierung und internem Status, was zum Debuggen nützlich ist, aber sonst störend wirkt.
Dieses Beispiel verwendet Streaming, um den Fortschritt in Echtzeit anzuzeigen. Wenn Sie keine Live-Ausgabe benötigen (z. B. für Hintergrundaufträge oder CI-Pipelines), können Sie alle Nachrichten auf einmal sammeln. Weitere Informationen finden Sie unter Streaming vs. Single-Turn-Modus.
Führen Sie Ihren Agenten aus
Ihr Agent ist bereit. Führen Sie ihn mit dem folgenden Befehl aus:- TypeScript
- Python (uv)
- Python (pip)
agent.mts genannt haben, führen Sie stattdessen npx tsx agent.mts aus.Done: success. Nach der Ausführung überprüfen Sie utils.py. Sie sehen defensiven Code, der leere Listen und Null-Benutzer verarbeitet. Ihr Agent hat autonom:
- Gelesen
utils.py, um den Code zu verstehen - Analysiert die Logik und identifiziert Grenzfälle, die zum Absturz führen würden
- Bearbeitet die Datei, um ordnungsgemäße Fehlerbehandlung hinzuzufügen
Wenn Sie einen Authentifizierungsfehler wie
Not logged in oder Invalid API key sehen, stellen Sie sicher, dass Sie die Umgebungsvariable ANTHROPIC_API_KEY in der Shell gesetzt haben, in der Sie Ihren Agenten ausführen. Das SDK lädt .env-Dateien nicht automatisch.Informationen zu den Ursachen und Lösungen dieser und anderer Authentifizierungsfehler finden Sie unter Authentifizierungsfehler in der Fehlerreferenz.Versuchen Sie andere Prompts
Jetzt, da Ihr Agent eingerichtet ist, versuchen Sie einige verschiedene Prompts:"Add docstrings to all functions in utils.py""Add type hints to all functions in utils.py""Create a README.md documenting the functions in utils.py"
Passen Sie Ihren Agenten an
Sie können das Verhalten Ihres Agenten ändern, indem Sie die Optionen ändern. Hier sind einige Beispiele: Fügen Sie Web-Suchfunktion hinzu:Bash versuchen Sie: "Write unit tests for utils.py, run them, and fix any failures"
Jedes dieser Snippets setzt Felder auf demselben Optionsobjekt. Weitere Informationen finden Sie unter Konfigurieren Sie Ihren Agenten.
Wichtige Konzepte
Tools steuern, was Ihr Agent tun kann:
Genehmigungsmodi steuern, wie viel menschliche Aufsicht Sie möchten. Das SDK wertet den aktiven Modus zusammen mit Ihren Allow- und Deny-Regeln in einer festen Reihenfolge aus, die unter Wie Berechtigungen ausgewertet werden beschrieben ist. Die vollständige Liste der Modi, ihr Verhalten und wann Sie jeden verwenden sollten, finden Sie unter Genehmigungsmodus in Wie die Agent-Schleife funktioniert.
Nächste Schritte
Jetzt, da Sie Ihren ersten Agenten erstellt haben, erfahren Sie, wie Sie seine Funktionen erweitern und ihn an Ihren Anwendungsfall anpassen:- Konfigurieren Sie Ihren Agenten: Stellen Sie das Optionsobjekt zusammen und finden Sie die Seite, die jede Einstellung abdeckt
- Berechtigungen: Steuern Sie, was Ihr Agent tun kann und wann er Genehmigung benötigt
- Hooks: Führen Sie benutzerdefinierten Code vor oder nach Tool-Aufrufen aus
- Sitzungen: Erstellen Sie Multi-Turn-Agenten, die den Kontext beibehalten
- MCP-Server: Verbinden Sie sich mit Datenbanken, Browsern, APIs und anderen externen Systemen
- Hosting: Stellen Sie Agenten in Docker, Cloud und CI/CD bereit
- Beispiel-Agenten: Siehe vollständige Beispiele: E-Mail-Assistent, Forschungsagent und mehr
- Fehlerbehebung: Beheben Sie Fehler, wenn die CLI nicht startet oder beendet wird, oder wenn ein Ergebnis ohne strukturierte Ausgabe ankommt