So erstellen Sie Ihren ersten KI-Agenten mit Claude: Vom ersten API-Aufruf zum autonomen System

90% des Codes bei Anthropic werden von Claude-Agenten geschrieben. Nicht von Entwicklern, die in einem Chat-Fenster tippen. Sondern von autonomen Agenten, die Schleifen ausführen, Tools ansteuern und Code ausliefern, während das Team schläft.

Folge meinem Substack, um frisches KI-Alpha zu erhalten:

movez.substack.com

Das ist der exakte Aufbau. Schritt für Schritt. Vom ersten API-Aufruf bis zu einem funktionierenden Agenten, den du auf jede Aufgabe ansetzen kannst.

Dieser Artikel behandelt:

1 - warum die meisten "Agenten", die Leute bauen, keine Agenten sind

2 - die 5 Teile, die jeder funktionierende Agent braucht

3 - wie du jeden Teil mit Claude und Code baust

4 - die Fehler, die Agenten töten, bevor sie ausgeliefert werden

Lesezeichen setzen. Jeder Code-Block unten funktioniert.

01. Die meisten "KI-Agenten" sind keine Agenten

Ich habe mehr Agenten gebaut und kaputt gemacht, als ich zählen kann. Habe zugesehen, wie sie die ganze Nacht Tokens verbrannt und nichts produziert haben. Habe zugesehen, wie sie dieselbe Datei 30 Mal neu geschrieben haben. Habe zugesehen, wie sie ihren eigenen Test bestanden haben, indem sie den Test gelöscht haben.

Jeder Fehlschlag hat mir die gleiche Lektion erteilt: Das Modell ist nicht das Problem. Die Architektur darum herum ist es. Dieser Leitfaden ist alles, was ich gelernt habe, komprimiert auf den kürzesten Weg, den ich dir geben kann.

Hier ist, was die meisten Leute bauen, wenn sie "KI-Agent" sagen:

1while True:
2    user_input = input("> ")
3    response = call_claude(user_input)
4    print(response)

Das ist ein Chatbot. Er wartet auf dich. Er tut, was du sagst. Er vergisst alles zwischen den Sitzungen. Wenn du den Tab schließt, hört er auf.

Ein Agent ist ein System, das auf ein Ziel hinarbeitet, ohne dass du davor sitzt. Er entdeckt, was getan werden muss, erstellt einen Plan, führt ihn aus, überprüft das Ergebnis, und wenn es noch nicht fertig ist – versucht er es erneut. Du gibst die Richtung vor. Der Agent erledigt die Arbeit.

"Claude Code ist in ein paar Monaten von null auf 400 Millionen Dollar Umsatz gewachsen. Es begann als Hackathon-Projekt. Es nutzt immer noch nur die öffentliche API." -

Boris Cherny, Leiter von Claude Code

Dieselbe API, auf die du gerade Zugriff hast. Dieselben Modelle. Der Unterschied ist die Architektur um das Modell herum.

02. Die 5 Teile eines echten Agenten

Jeder funktionierende Agent – Claude Code, Devin, Codex oder was auch immer du selbst baust – besteht aus fünf Teilen. Fehlt einer, bricht er.

03. Die API-Ebene

Alles beginnt hier. Du rufst Claude auf, Claude antwortet. Aber die Art, wie du es aufrufst, bestimmt, ob du einen Chatbot oder einen Agenten bekommst.

Drei Dinge sind wichtig: der System-Prompt, die strukturierte Ausgabe und die Temperatur.

System-Prompt ist keine Begrüßung. Es ist das Betriebshandbuch deines Agenten. Jede Regel, Einschränkung und Verhaltensweise gehört hier hinein. Ohne ihn rät Claude, was du willst. Mit ihm folgt Claude deiner Spezifikation.

1import anthropic
2
3client = anthropic.Anthropic()
4
5response = client.messages.create(
6    model="claude-sonnet-4-6",
7    max_tokens=4096,
8    system="""Du bist ein Code-Review-Agent.
9
10Regeln:
11- Lies den gesamten Diff, bevor du kommentierst
12- Markiere nur echte Fehler, keine Stilvorlieben
13- Wenn nichts falsch ist, sag "LGTM" und hör auf
14- Schlage niemals Änderungen vor, die du nicht mental getestet hast
15- Ausgabeformat: JSON-Array von {file, line, issue, fix}""",
16    messages=[{"role": "user", "content": diff_content}]
17)

Strukturierte Ausgabe macht die Antwort deines Agenten maschinenlesbar. Wenn Claude Freitext zurückgibt, muss dein Code ihn parsen. Wenn Claude JSON zurückgibt, kann dein Code es direkt verwenden.

1# Erzwinge JSON-Ausgabe, indem du Claude die genaue Form mitteilst
2system = """Gib NUR gültiges JSON zurück. Kein Markdown. Keine Erklärung.
3Schema:
4{
5  "status": "pass" | "fail",
6  "issues": [{"file": str, "line": int, "issue": str}],
7  "summary": str
8}"""

Temperatur. Setze sie auf 0 für deterministische Agenten. Setze sie auf 0,3-0,5 für kreative Arbeit. Der Standardwert (1,0) fügt Zufälligkeit hinzu, die du bei einem Agenten fast nie haben willst.

04. Tools

Ein Modell ohne Tools kann denken, aber nicht handeln. Es kann dir sagen, welche Datei du bearbeiten sollst, aber es kann sie nicht bearbeiten. Es kann eine Abfrage beschreiben, aber sie nicht ausführen.

Claudes Tool-Nutzung ermöglicht es dir, Funktionen zu definieren, die das Modell aufrufen kann. Du beschreibst die Funktion. Claude entscheidet, wann er sie aufruft. Du führst sie aus und gibst das Ergebnis zurück. Claude verwendet das Ergebnis, um weiterzudenken.

1tools = [{
2    "name": "run_sql",
3    "description": "Führe eine schreibgeschützte SQL-Abfrage gegen die Datenbank aus",
4    "input_schema": {
5        "type": "object",
6        "properties": {
7            "query": {
8                "type": "string",
9                "description": "SQL SELECT-Abfrage, die ausgeführt werden soll"
10            }
11        },
12        "required": ["query"]
13    }
14},
15{
16    "name": "write_file",
17    "description": "Schreibe Inhalt in eine Datei auf der Festplatte",
18    "input_schema": {
19        "type": "object",
20        "properties": {
21            "path": {"type": "string"},
22            "content": {"type": "string"}
23        },
24        "required": ["path", "content"]
25    }
26}]

Die Tool-Beschreibung ist wichtiger, als du denkst. Claude liest sie, um zu entscheiden, wann und wie er das Tool verwendet. Eine vage Beschreibung bedeutet falsche Aufrufe. Eine präzise Beschreibung bedeutet genaue Aufrufe.

Beginne mit 3-5 Tools. Datei lesen, Datei schreiben, Befehl ausführen, suchen und ein domainspezifisches Tool für deinen Anwendungsfall. Das deckt 90% der Agentenaufgaben ab.

05. Die Schleife

Das ist der Teil, der ein Skript in einen Agenten verwandelt. Ohne Schleife ruft dein Code Claude einmal auf und hört auf. Mit einer Schleife ruft dein Code Claude auf, überprüft das Ergebnis und ruft erneut auf, bis die Aufgabe erledigt ist.

Drei Komponenten:

• Prüfer. Etwas, das überprüft, ob die Ausgabe gut ist. Eine Testsuite, ein Typprüfer, ein Linter, ein zweiter Claude-Aufruf mit strengen Kriterien. Ohne das hast du den Agenten, der sich im Kreis wiederholt.
• Zustand. Eine Aufzeichnung dessen, was passiert ist. Was funktioniert hat, was fehlgeschlagen ist, was als nächstes zu versuchen ist. Ohne Zustand macht der Agent den gleichen Fehler bei jedem Durchlauf.
• Abbruchbedingung. Das Ziel ist erreicht, oder eine harte Grenze sagt "nach N Versuchen, aufhören und melden". Ohne diese läuft die Schleife ewig und leert dein Konto.

1import json
2from pathlib import Path
3
4def run_agent(task: str, max_attempts: int = 5):
5    state = {"task": task, "attempts": [], "done": False}
6
7    for i in range(max_attempts):
8        # Kontext aus dem Zustand erstellen
9        context = build_prompt(state)
10
11        # Claude mit Tools aufrufen
12        result = call_claude(context, tools)
13
14        # Alle Tool-Aufrufe ausführen
15        output = execute_tools(result)
16
17        # Ergebnis überprüfen
18        check = verify(output)
19
20        # Zustand aktualisieren
21        state["attempts"].append({
22            "attempt": i + 1,
23            "action": result.summary,
24            "passed": check.passed,
25            "reason": check.reason
26        })
27
28        if check.passed:
29            state["done"] = True
30            break
31
32    # Zustand für den nächsten Lauf speichern
33    Path("state.json").write_text(json.dumps(state, indent=2))
34    return state

Das ist das vollständige Grundgerüst. Jeder Produktionsagent ist eine Variation dieses Musters. Die Details ändern sich. Die Form nicht.

06. Gedächtnis

Ohne Gedächtnis beginnt jede Sitzung bei null. Der Agent entdeckt deine Projektstruktur neu. Lernt deine Konventionen neu. Macht die Fehler von gestern erneut.

Claude-Agenten verwenden drei Gedächtnisebenen:

CLAUDE.md ist eine Markdown-Datei im Stammverzeichnis deines Projekts. Claude Code liest sie automatisch zu Beginn jeder Sitzung. Deine Regeln, dein Stack, deine Konventionen. Einmal schreiben, für immer lesen.

1# CLAUDE.md
2
3## Projekt
4Task-Management-API. Python 3.12, FastAPI, PostgreSQL.
5
6## Regeln
7- Alle Antworten: {data, error, meta}-Schema
8- Tests für jeden neuen Endpunkt erforderlich
9- Commit-Nachrichten: type(scope): description
10- Niemals print() zum Loggen verwenden. structlog verwenden.
11
12## Bekannte Probleme
13- Auth-Middleware erwartet x-auth-token, nicht Authorization
14- Testsuite dauert vollständig 45s. --filter für Iteration verwenden.

Skills erfassen ganze Arbeitsabläufe. Nicht nur Prompts – die vollständige Form: Eingabeformat, Schritte, Ausgabeformat, Validierungsregeln. Erster Lauf dauert 20 Minuten. Wiederholung dauert 30 Sekunden.

Lerndatei ist ein fortlaufendes Protokoll der Fehler. Der Agent schreibt nach jeder Sitzung hinein. Die nächste Sitzung liest es. Fehler wiederholen sich, bis sie aufgeschrieben sind. Dann hören sie auf.

1# learnings.md
2
3- Payment-API erwartet Idempotency-Key im Header, nicht im Body
4- PostgreSQL NOTIFY benötigt explizites LISTEN im Connection-Pool
5- Rate-Limiter zählt pro Schlüssel, nicht pro IP. Tests benötigen eindeutige Schlüssel.

07. Das Verifikationstor

Das Tor ist der schwierigste Teil zu bauen und der am einfachsten zu überspringende. Die meisten Leute überspringen es. Deshalb brechen die meisten Agenten in der Produktion.

Ein Verifikationstor ist etwas, das die Arbeit des Agenten überprüft, ohne dass der Agent sich selbst benotet. Das Modell, das den Code geschrieben hat, ist zu großzügig bei der Benotung seiner eigenen Hausaufgaben. Du brauchst eine zweite Prüfung.

Drei Muster, die funktionieren:

1. Automatisierte Tests. Der Agent schreibt Code. Die Testsuite läuft. Wenn Tests fehlschlagen, bekommt der Agent die Fehlerausgabe und versucht es erneut. So funktioniert Claude Code intern.

1def verify(output):
2    # Testsuite ausführen
3    result = subprocess.run(
4        ["pytest", "tests/", "-x", "--tb=short"],
5        capture_output=True, text=True
6    )
7    return {
8        "passed": result.returncode == 0,
9        "reason": result.stdout if result.returncode != 0 else "alle Tests bestanden"
10    }

2. Typprüfer / Linter. Führe mypy, ruff oder tsc --noEmit nach jeder Änderung aus. Erfasst ganze Kategorien von Fehlern, ohne einen einzigen Test zu schreiben.

3. Zweites Modell als Prüfer. Verwende einen separaten Claude-Aufruf mit einem strengen System-Prompt, der nur nach Problemen sucht. Der Schreiber ist schnell und billig. Der Prüfer ist langsam und streng. Diese Trennung macht den Großteil der Qualität aus.

1# Prüfer-Prompt – getrennt vom Builder
2reviewer_system = """Du bist ein strenger Code-Reviewer.
3Deine EINZIGE Aufgabe ist es, Probleme zu finden.
4
5Prüfe:
6- Entspricht der Code der Spezifikation?
7- Gibt es nicht abgedeckte Randfälle?
8- Testen alle Tests tatsächlich das Richtige?
9
10Wenn alles korrekt ist, antworte: {"passed": true}
11Wenn etwas falsch ist, antworte: {"passed": false, "issues": [...]}
12
13Schlage KEINE Verbesserungen vor. Markiere nur echte Fehler."""

Der Schreiber ist schnell und billig. Der Prüfer ist langsam und streng. Diese Trennung macht den Großteil der Qualität aus.

08. Alles zusammenfügen

Hier ist ein vollständiger Agent, der eine GitHub-Issue-URL nimmt, das Issue liest, den Code schreibt, die Tests ausführt und einen PR eröffnet. Fünf Teile, die zusammenarbeiten.

1import anthropic, subprocess, json
2from pathlib import Path
3
4client = anthropic.Anthropic()
5CLAUDE_MD = Path("CLAUDE.md").read_text()
6LEARNINGS = Path("learnings.md").read_text()
7
8SYSTEM = f"""Du bist ein Code-Agent.
9Lies das Issue. Schreibe den Fix. Führe die Tests aus.
10
11Projektkontext:
12{CLAUDE_MD}
13
14Bekannte Probleme:
15{LEARNINGS}
16
17Regeln:
18- Lies die gesamte Codebasis, bevor du etwas änderst
19- Schreibe Tests für jede Änderung
20- Wenn Tests fehlschlagen, behebe den Code, nicht die Tests
21- Höre auf, wenn alle Tests bestanden sind"""
22
23TOOLS = [
24    read_file_tool,
25    write_file_tool,
26    run_command_tool,
27    search_codebase_tool,
28]
29
30def run(issue_text, max_attempts=5):
31    messages = [{"role": "user", "content": issue_text}]
32
33    for attempt in range(max_attempts):
34        # Claude aufrufen
35        response = client.messages.create(
36            model="claude-sonnet-4-6",
37            max_tokens=8192,
38            system=SYSTEM,
39            tools=TOOLS,
40            messages=messages
41        )
42
43        # Tool-Aufrufe ausführen
44        messages = handle_tool_use(response, messages)
45
46        # Verifizieren: Tests ausführen
47        test_result = subprocess.run(
48            ["pytest", "-x", "--tb=short"],
49            capture_output=True, text=True
50        )
51
52        if test_result.returncode == 0:
53            print(f"Erledigt in {attempt + 1} Versuchen")
54            return True
55
56        # Fehler zurück in die Schleife geben
57        messages.append({
58            "role": "user",
59            "content": f"Tests fehlgeschlagen:\n{test_result.stdout}\nBeheben und erneut versuchen."
60        })
61
62    return False

Das ist ein funktionierender Agent. API-Ebene mit System-Prompt und CLAUDE.md. Tools für Dateioperationen. Eine Schleife mit Wiederholungsversuch. Gedächtnis von learnings.md. Ein Verifikationstor via pytest.

Unter 50 Zeilen. Dieselbe Architektur, die Claude Code intern verwendet.

**

09. Die 5 Fehler, die jeden Agenten kaputt machen

1. Kein Verifikationstor. Der Agent benotet seine eigenen Hausaufgaben. Er schreibt Code, sagt "sieht gut aus" und macht weiter. Die Ausgabe sieht richtig aus und geht in der Produktion kaputt.
2. Keine Abbruchbedingung. Die Schleife läuft, bis deine API-Rechnung 200€ beträgt. Ohne eine harte Grenze versucht der Agent es ewig weiter und schreibt dieselbe Datei 40 Mal neu. Setze immer max_attempts. Immer.
3. Keine Zustandsdatei. Gleicher Fehler bei Versuch #1 und Versuch #50. Der Agent weiß nicht, was er schon versucht hat. Er schlägt denselben kaputten Fix drei Mal hintereinander vor, weil nichts den Fehler aufzeichnet.
4. Zu viele Tools. Du gibst Claude 20 Tools und er wählt das falsche aus. Ein Modell mit 5 klaren Tools trifft bessere Entscheidungen als ein Modell mit 20 überlappenden. Fang klein an. Füge Tools nur hinzu, wenn der Agent gegen eine Wand läuft.
5. Vager System-Prompt. "Sei ein guter Code-Assistent" gibt dir generische Ausgabe. "Alle Antworten müssen gültiges JSON sein, Tests für jede Änderung erforderlich, niemals Dateien außerhalb von /src ändern" gibt dir einen Agenten, der sich benimmt.

Fazit:

Ein funktionierender Agent ist kein besserer Prompt. Es ist ein System: API + Tools + Schleife + Gedächtnis + Verifikationstor. Fünf Teile. Fehlt einer, bricht er.

Die meisten Leute werden das lesen, ein Lesezeichen setzen und Claude weiterhin als Chatbot verwenden. Sie werden eine Frage nach der anderen einfügen und die Antwort per Hand in ihre Codebasis kopieren.

Diejenigen, die die Schleife bauen, werden Arbeit ausliefern, während sie schlafen. Gleiches Modell. Gleiche API. Gleicher Preis. Andere Architektur.

Die Code-Blöcke oben funktionieren alle. Kopiere sie. Führe sie aus. Passe sie an deinen Anwendungsfall an.

Baue diese Woche einen Agenten. Setze ihn auf eine Aufgabe an, die du jeden Tag erledigst. Lass ihn laufen.