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:

1. Ein Projekt mit dem Agent SDK einrichten
2. Eine Datei mit fehlerhaftem Code erstellen
3. 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

mkdir my-agent
cd my-agent

npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

uv init
uv add claude-agent-sdk

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

export ANTHROPIC_API_KEY=your-api-key

$env:ANTHROPIC_API_KEY = "your-api-key"

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:

1. calculate_average([]) stürzt mit Division durch Null ab
2. get_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. Verwenden Sie agent.mts stattdessen, wenn Ihr bestehendes Projekt CommonJS verwendet:

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:

1. query: der Haupteinstiegspunkt, der die agentic loop erstellt. Er gibt einen asynchronen Iterator zurück, daher verwenden Sie async for, um Nachrichten zu streamen, während Claude arbeitet. Siehe die vollständige API in der Python oder TypeScript SDK-Referenz.

2. prompt: was Sie Claude tun möchten. Claude ermittelt basierend auf der Aufgabe, welche Tools verwendet werden sollen.

3. options: Konfiguration für den Agenten. Dieses Beispiel verwendet allowedTools, um Read, Edit und Glob vorab zu genehmigen, und permissionMode: "acceptEdits", um Dateiänderungen automatisch zu genehmigen. Weitere Optionen sind systemPrompt, mcpServers und 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 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.

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

python agent.py

Während es arbeitet, druckt der Agent seine Überlegungen und jeden Tool-Aufruf aus und endet mit 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:

1. Gelesen utils.py, um den Code zu verstehen
2. Analysiert die Logik und identifiziert Grenzfälle, die zum Absturz führen würden
3. 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.

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"

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