Eigene Agenten mit der API bauen

Ein Agent unterscheidet sich von einem einzelnen API-Aufruf durch eine Sache: Claude entscheidet selbst, welche Schritte nötig sind, und arbeitet sie in einer Schleife ab – Tools aufrufen, Ergebnisse verarbeiten, weiterdenken, bis die Aufgabe erledigt ist. Dieser Guide zeigt, wie dieser Loop funktioniert, wann er sich lohnt, und wo die Grenze zwischen selbst gebautem Agenten und Anthropics Managed Agents verläuft.

Für wen ist das?

Für erfahrene Entwickler, die schon mit Tool Use vertraut sind und Claude eigenständig mehrstufige Aufgaben mit eigenen Werkzeugen lösen lassen wollen – Recherche, Code-Änderungen, Datenpipelines.

Was lernst du?

Wann ein Agent die richtige Wahl ist – und wann nicht
Wie der Agent-Loop Schritt für Schritt abläuft
Der Unterschied zwischen manuellem Loop und SDK-Tool-Runner
Die Abgrenzung: selbst gehostet (API + Tool Use) vs. Anthropic-gehostet (Managed Agents)

Soll ich überhaupt einen Agenten bauen?

Ein Agent ist mächtig, aber auch teurer, langsamer und schwerer vorhersehbar als ein einzelner Aufruf. Prüfe vier Kriterien – ist bei einem die Antwort „nein”, bleib bei einer einfacheren Stufe (einzelner Aufruf oder fester Workflow):

Komplexität: Ist die Aufgabe mehrstufig und lässt sie sich schlecht vorab vollständig durchspezifizieren? („Mach aus diesem Design-Doc einen Pull Request” – ja. „Extrahiere den Titel aus dieser PDF” – nein.)
Wert: Rechtfertigt das Ergebnis die höheren Kosten und die längere Laufzeit?
Machbarkeit: Ist Claude bei dieser Art Aufgabe zuverlässig?
Fehlerkosten: Lassen sich Fehler auffangen – durch Tests, Review oder Rollback?

Der Agent-Loop

Im Kern ist ein Agent eine Schleife um denselben Tool-Use-Round-Trip, den du aus Tool Use kennst – nur wiederholt, bis Claude fertig ist.

1

Anfrage mit Tools senden

Du rufst die Messages-API mit deiner Aufgabe und dem tools-Parameter auf – der Liste der Werkzeuge, die Claude nutzen darf.

2

Claude will ein Tool nutzen

Die Antwort endet mit stop_reason: "tool_use". Im content steht ein tool_use-Block mit Name und Argumenten.

3

Tool ausführen

Deine Anwendung führt den eigentlichen Code aus – API-Aufruf, Datenbankabfrage, Dateizugriff. Claude selbst führt nie Code aus.

4

Ergebnis zurückgeben

Du schickst das Ergebnis als tool_result zurück, zusammen mit der bisherigen Konversation.

5

Wiederholen bis end_turn

Claude verarbeitet das Ergebnis und entscheidet: noch ein Tool (stop_reason: "tool_use") oder fertig (stop_reason: "end_turn"). Erst bei end_turn endet der Loop.

Tipp Baue immer eine Obergrenze für die Iterationen ein – sonst kann ein Agent im Extremfall endlos weiterlaufen.

Manueller Loop oder Tool Runner?

Du hast zwei Wege, diesen Loop zu betreiben:

Manueller Loop: Du schreibst die Schleife selbst. Maximale Kontrolle – ideal, wenn du Freigabe-Gates (der Nutzer bestätigt riskante Aktionen), eigenes Logging oder bedingte Ausführung brauchst.
Tool Runner: Der SDK-Helper client.beta.messages.tool_runner(...) übernimmt die Schleife für dich – er ruft die API, führt deine registrierten Funktionen aus und iteriert, bis Claude fertig ist. Weniger Code, wenn du keine Sonderlogik im Loop brauchst.

Es gibt zwei grundsätzlich verschiedene Architekturen für Agenten:

Claude API + Tool Use – du hostest den Loop und die Tool-Ausführung selbst. Maximale Flexibilität: eigene Compute, eigene Werkzeuge, volle Kontrolle über jeden Schritt.

Managed Agents – Anthropic betreibt den Agent-Loop und stellt pro Session einen Container als Workspace bereit, in dem Tools (Bash, Datei-Operationen, Code) laufen. Du legst eine persistente, versionierte Agent-Config einmal an und startest daraus Sessions.

Faustregel: Willst du eigene Infrastruktur und Werkzeuge kontrollieren, nimm API + Tool Use. Willst du einen server-verwalteten, zustandsbehafteten Agenten mit fertigem Workspace, nimm Managed Agents.

✗

Für 'Extrahiere die Rechnungsnummer aus diesem PDF' einen vollen Agenten mit Tool-Loop bauen. Overengineering: teurer, langsamer, fehleranfälliger als nötig.

✓

Klare Einzelaufgaben mit einem einzelnen Messages-Aufruf lösen (ggf. mit einem Tool für strukturierten Output). Den Agenten für das aufheben, was wirklich mehrstufig und offen ist.

Die Agenten-Stufe ist die teuerste und am schwersten kontrollierbare. Nutze sie nur, wenn die vier Kriterien es rechtfertigen – sonst gewinnt ein einzelner Aufruf oder ein fester Workflow.

Was beendet den Agent-Loop?

Stand Juli 2026: Der SDK-Tool-Runner und die Managed Agents sind als Beta verfügbar. Die grundsätzliche Abgrenzung – selbst gehosteter Loop (API + Tool Use) versus Anthropic-gehostete Managed Agents – ist stabil und die wichtigste Architekturentscheidung zu Beginn.

Typische Fehler

Agent, wo ein Workflow reicht: Die häufigste Fehlentscheidung. Prüfe die vier Kriterien, bevor du die teuerste Stufe wählst.
tool_result im Loop vergessen: Ohne das Ergebnis wartet Claude und der Loop hängt.
Keine Iterations-Obergrenze: Ein Agent ohne Abbruchbedingung kann im Extremfall endlos weiterlaufen und Kosten verbrennen.
Tool-Fehler verschlucken: Schlägt ein Tool fehl, gib den Fehler als tool_result mit is_error: true zurück – dann kann Claude sinnvoll reagieren, statt zu halluzinieren.

Nächster Schritt

Du kennst jetzt den Agent-Loop. Für Aufgaben, die nicht interaktiv, sondern in Masse laufen, lohnt sich ein Blick auf Batch & Files API – asynchrone Verarbeitung und wiederverwendbare Dokumente.

Glossar Practice Hub Alle Guides

War das hilfreich?

Damit kannst du jetzt: Ein Agent ist der wiederholte Loop model → tool_use → ausführen → tool_result. Bau ihn nur, wenn Komplexität, Wert, Machbarkeit und Fehlerkosten stimmen – sonst reicht ein einzelner Aufruf oder ein fester Workflow. Den Loop hostest du selbst (API + Tool Use) oder überlässt ihn Anthropic (Managed Agents).

Nächster Guide Batch & Files API: Masse und Dokumente →