Schnellstart
Erste Schritte mit dem Python- oder TypeScript-Agent-SDK zum Erstellen von KI-Agenten, die autonom funktionieren
Verwenden Sie das Agent SDK, um einen KI-Agenten zu erstellen, der Ihren Code liest, Fehler findet und behebt – alles ohne manuelle Eingriffe.
Das werden Sie tun:
- 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 (hier registrieren)
Einrichtung
Erstellen Sie einen Projektordner
Erstellen Sie ein neues Verzeichnis für diesen Schnellstart:
mkdir my-agent
cd my-agent
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.
Installieren Sie das SDK
Installieren Sie das Agent SDK-Paket für Ihre Sprache:
npm install @anthropic-ai/claude-agent-sdk
uv ist ein schneller Python-Paketmanager, der virtuelle Umgebungen automatisch verwaltet:
uv init
uv add claude-agent-sdk
Erstellen und aktivieren Sie eine virtuelle Umgebung und installieren Sie dann das Paket.
Auf macOS oder Linux:
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
Unter Windows:
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk
Wenn PowerShell Activate.ps1 mit einem Ausführungsrichtlinienfehler blockiert, führen Sie zuerst Set-ExecutionPolicy -Scope Process RemoteSigned aus.
Das TypeScript SDK bündelt eine native Claude Code-Binärdatei für Ihre Plattform als optionale Abhängigkeit, sodass Sie Claude Code nicht separat installieren müssen.
Legen Sie Ihren API-Schlüssel fest
Rufen Sie einen API-Schlüssel von der Claude-Konsole ab und erstellen Sie dann eine .env-Datei in Ihrem Projektverzeichnis:
ANTHROPIC_API_KEY=your-api-key
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 Vertex AI: Setzen Sie die Umgebungsvariable
CLAUDE_CODE_USE_VERTEX=1und konfigurieren Sie Google Cloud-Anmeldedaten - Microsoft Azure: Setzen Sie die Umgebungsvariable
CLAUDE_CODE_USE_FOUNDRY=1und konfigurieren Sie Azure-Anmeldedaten
Weitere Informationen finden Sie in den Einrichtungsleitfäden für Bedrock, Claude Platform on AWS, Vertex AI oder Azure AI Foundry.
Sofern nicht zuvor genehmigt, erlaubt Anthropic Drittentwicklern nicht, claude.ai-Anmeldungen oder Ratenlimits 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 Sie utils.py im Verzeichnis my-agent und fügen Sie den folgenden Code ein:
def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers)
def get_user_name(user):
return user["name"].upper()
Dieser Code hat zwei Fehler:
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 Sie agent.py, wenn Sie das Python SDK verwenden, oder agent.ts für TypeScript:
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage
async def main():
# Agentic loop: streams messages as Claude works
async for message in query(
prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options=ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"], # Auto-approve these tools
permission_mode="acceptEdits", # Auto-approve file edits
),
):
# Print human-readable output
if isinstance(message, AssistantMessage):
for block in message.content:
if hasattr(block, "text"):
print(block.text) # Claude's reasoning
elif hasattr(block, "name"):
print(f"Tool: {block.name}") # Tool being called
elif isinstance(message, ResultMessage):
print(f"Done: {message.subtype}") # Final result
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
// Agentic loop: streams messages as Claude works
for await (const message of query({
prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
options: {
allowedTools: ["Read", "Edit", "Glob"], // Auto-approve these tools
permissionMode: "acceptEdits" // Auto-approve file edits
}
})) {
// Print human-readable output
if (message.type === "assistant" && message.message?.content) {
for (const block of message.message.content) {
if ("text" in block) {
console.log(block.text); // Claude's reasoning
} else if ("name" in block) {
console.log(`Tool: ${block.name}`); // Tool being called
}
}
} else if (message.type === "result") {
console.log(`Done: ${message.subtype}`); // Final result
}
}
Dieser Code hat drei Hauptteile:
-
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.
Die 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, 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:
npx tsx agent.ts
uv run agent.py
Mit Ihrer noch aktivierten virtuellen Umgebung:
python agent.py
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
Das macht das Agent SDK anders: Claude führt Tools direkt aus, anstatt Sie zu bitten, sie zu implementieren.
Wenn Sie „API-Schlüssel nicht gefunden" sehen, stellen Sie sicher, dass Sie die Umgebungsvariable ANTHROPIC_API_KEY in Ihrer .env-Datei oder Shell-Umgebung gesetzt haben. Weitere Hilfe finden Sie im vollständigen Fehlerbehebungsleitfaden.
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:
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
permissionMode: "acceptEdits"
}
};
Geben Sie Claude einen benutzerdefinierten System-Prompt:
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob"],
permission_mode="acceptEdits",
system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob"],
permissionMode: "acceptEdits",
systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
}
};
Führen Sie Befehle im Terminal aus:
options = ClaudeAgentOptions(
allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)
const _ = {
options: {
allowedTools: ["Read", "Edit", "Glob", "Bash"],
permissionMode: "acceptEdits"
}
};
Mit aktiviertem Bash versuchen Sie: "Write unit tests for utils.py, run them, and fix any failures"
Wichtige Konzepte
Tools steuern, was Ihr Agent tun kann:
| Tools | Was der Agent tun kann |
|---|---|
Read, Glob, Grep |
Schreibgeschützte Analyse |
Read, Edit, Glob |
Code analysieren und ändern |
Read, Edit, Bash, Glob, Grep |
Vollständige Automatisierung |
Genehmigungsmodi steuern, wie viel menschliche Aufsicht Sie möchten:
| Modus | Verhalten | Anwendungsfall |
|---|---|---|
acceptEdits |
Genehmigt Dateibearbeitungen und häufige Dateisystembefehle automatisch, fragt nach anderen Aktionen | Vertrauenswürdige Entwicklungs-Workflows |
dontAsk |
Lehnt alles ab, das nicht in allowedTools enthalten ist |
Gesperrte Headless-Agenten |
auto (nur TypeScript) |
Ein Modell-Klassifizierer genehmigt oder lehnt jeden Tool-Aufruf ab | Autonome Agenten mit Sicherheitsvorkehrungen |
bypassPermissions |
Führt jedes Tool ohne Eingabeaufforderungen aus | Sandboxed CI, vollständig vertrauenswürdige Umgebungen |
default |
Erfordert einen canUseTool-Callback zur Genehmigungsbehandlung |
Benutzerdefinierte Genehmigungsabläufe |
Das obige Beispiel verwendet den acceptEdits-Modus, der Dateivorgänge automatisch genehmigt, damit der Agent ohne interaktive Eingabeaufforderungen ausgeführt werden kann. Wenn Sie Benutzer zur Genehmigung auffordern möchten, verwenden Sie den default-Modus und stellen Sie einen canUseTool-Callback bereit, der Benutzereingaben sammelt. Für mehr Kontrolle siehe Berechtigungen.
Fehlerbehebung
API-Fehler `thinking.type.enabled` wird für dieses Modell nicht unterstützt
Claude Opus 4.7 ersetzt thinking.type.enabled durch thinking.type.adaptive. Ältere Agent SDK-Versionen schlagen mit dem folgenden API-Fehler fehl, wenn Sie claude-opus-4-7 auswählen:
API Error: 400 {"type":"invalid_request_error","message":"\"thinking.type.enabled\" is not supported for this model. Use \"thinking.type.adaptive\" and \"output_config.effort\" to control thinking behavior."}
Aktualisieren Sie auf Agent SDK v0.2.111 oder später, um Opus 4.7 zu verwenden.
Nächste Schritte
Jetzt, da Sie Ihren ersten Agenten erstellt haben, erfahren Sie, wie Sie seine Funktionen erweitern und ihn an Ihren Anwendungsfall anpassen:
- 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