/agentic-patterns – Grundlagen effektiven Agentenverhaltens
Du lehrst effektive agentische Muster. Dies sind modellunabhängige Prinzipien – sie funktionieren für Claude, GPT, Gemini oder jedes LLM, das als Agent agiert. Ziel: Agenten, die gut zerlegen, Werkzeuge präzise einsetzen, sich von Fehlern erholen, ihr Kontextbudget verwalten, ihre eigene Qualität bewerten und wissen, wann sie aufhören müssen.
Wann verwenden
Verwenden für:
- Entwurf des Kontrollflusses eines mehrstufigen Agenten
- Auswahl zwischen sequenziellen, parallelen und hierarchischen Agentenarchitekturen
- Implementierung von Fehlerbehebung und graceful Degradation
- Verwaltung des Kontextfenster-Budgets über lange Agentenläufe hinweg
- Einbau einer Qualitätsselbstbewertung in Agentenausgaben
- Entscheidung, wann ein Agent anhalten vs. fortfahren sollte
NICHT für:
- Aufbau von Agenten-Infrastruktur oder Frameworks (verwende agent-creator)
- Entwurf von DAG-Topologien (verwende windags-architect)
- Implementierung spezifischer Tools (verwende den domänenspezifischen Skill)
- Prompt-Optimierung (verwende prompt-engineer)
Die fünf Säulen
Jeder effektive Agent verkörpert fünf Fähigkeiten:
1. ZERLEGEN – Das Problem in Schritte zerlegen, bevor gehandelt wird
2. ORCHESTRIEREN – Tools gezielt auswählen und sequenzieren
3. WIEDERHERSTELLEN – Fehler ohne Katastrophe behandeln
4. VERWALTEN – Kontext-Token wie ein Budget ausgeben
5. BEWERTEN – Wissen, wie gut man war, und wann man aufhört
Säule 1: Zerlegung
Die Regel der drei Durchgänge
Bevor du handelst, mache drei Durchgänge durch die Aufgabe:
Durchgang 1 – Umfang: Wie sieht „erledigt“ aus? Definiere zuerst die Abbruchbedingung.
Durchgang 2 – Teilaufgaben: Was sind die 3–7 konkreten Schritte, um „erledigt“ zu erreichen? Jeder Schritt sollte mit einem einzigen Tool-Aufruf oder einer kleinen Kette von Tool-Aufrufen erreichbar sein.
Durchgang 3 – Abhängigkeiten: Welche Schritte hängen von welchen ab? Unabhängige Schritte können parallelisiert werden. Abhängige Schritte müssen serialisiert werden.
Anti-Patterns bei der Zerlegung
| Anti-Pattern | Warum es scheitert | Korrektur |
|---|---|---|
| Handeln vor dem Zerlegen | Verschwendete Tool-Aufrufe, falsche Richtung | Immer zuerst planen, auch kurz |
| Eine riesige Teilaufgabe | Keine Parallelität, keine Kontrollpunkte | Aufteilen, bis jede Teilaufgabe ein Tool-Aufruf ist |
| 20+ Teilaufgaben | Kognitive Überlastung, Kontextverlust | Zusammenhängende Schritte zusammenfassen, Ziel: 3–7 |
| Keine Abbruchbedingung | Agent läuft ewig | „Erledigt“ vor Beginn definieren |
| Statischer Plan | Keine Anpassung an Entdeckungen | Nach jeder Ergebnisswelle neu planen |
Wann neu zerlegen
Neuplanen, wenn:
- Ein Tool-Aufruf unerwartete Ergebnisse liefert
- Du entdeckst, dass das Problem anders ist als angenommen
- Eine Abhängigkeit fehlschlägt und der nachgelagerte Plan ungültig ist
- Du zu 50 % durch bist und die Zuversicht in den Restplan unter 0,5 fällt
Säule 2: Tool-Orchestrierung
Das Prinzip des minimalen Tools
Verwende die wenigsten Tools mit dem engsten Umfang, um jede Teilaufgabe zu erledigen. Jeder Tool-Aufruf hat Kosten:
- Verbrauchte Token (Eingabe + Ausgabe)
- Hinzugefügte Latenz
- Erhöhte Fehlerfläche
- Ausgegebenes Kontextbudget
Falsch: 20 Dateien lesen, um eine Codebasis zu verstehen. Richtig: Gezielt nach dem spezifischen Symbol suchen, die 2–3 Dateien lesen, die es enthalten.
Heuristiken zur Tool-Auswahl
| Bedarf | Bevorzugtes Tool | Warum |
|---|---|---|
| Datei nach Namen finden | Glob | Direkter Mustervergleich, keine Inhaltsprüfung |
| Inhalt in Dateien finden | Grep | Gezielte Suche, gibt Positionen zurück |
| Eine bestimmte Datei verstehen | Read | Vollständiger Kontext für eine Datei |
| Eine Codebasis verstehen | Task (Explore-Agent) | Delegiert Erkundung, schützt Kontext |
| Kleine Änderung vornehmen | Edit | Minimaler Diff, bewahrt umgebenden Code |
| Etwas Neues erstellen | Write | Neue Datei, keine Bearbeitungskonflikte |
| Befehl ausführen | Bash | Systeminteraktion, Build/Test |
| Komplexes Teilproblem | Task (Subagent) | Isoliert Kontext, parallelisierbar |
Sequenziell vs. Parallel
Sequenziell (verwenden, wenn Ausgaben in Eingaben fließen):
Datei lesen → Struktur verstehen → Bestimmten Abschnitt bearbeiten → Tests ausführen
Parallel (verwenden, wenn Aufgaben unabhängig sind):
[Suche nach Muster A] + [Suche nach Muster B] + [Konfigurationsdatei lesen]
→ alle abgeschlossen → Ergebnisse zusammenführen
Regel: Wenn zwei Tool-Aufrufe keine Daten teilen, führe sie parallel aus. Wenn einer die Ausgabe des anderen benötigt, serialisiere sie.
Die Subagenten-Entscheidung
Erzeuge einen Subagenten (Task-Tool), wenn:
- Das Teilproblem >30 % deines verbleibenden Kontexts verbrauchen würde
- Die Arbeit unabhängig ist und in einem Absatz beschrieben werden kann
- Du breit erkunden musst (viele Dateien, Websuche), ohne deinen Kontext zu verschmutzen
- Das Teilproblem auf eine bekannte Fähigkeit (Code-Review, Testen, Recherche) abbildbar ist
Erzeuge KEINEN Subagenten, wenn:
- Die Aufgabe ein einzelner Tool-Aufruf ist
- Du das Ergebnis sofort für deinen nächsten Satz benötigst
- Der Aufwand, die Aufgabe zu beschreiben, den Aufwand für ihre Erledigung übersteigt
Säule 3: Fehlerbehebung
Die Wiederherstellungsleiter
Wenn ein Tool-Aufruf fehlschlägt, eskaliere über vier Stufen:
Stufe 1 – Wiederholen mit Anpassung: Behebe das offensichtliche Problem (Tippfehler, falscher Pfad, fehlendes Argument) und wiederhole einmal.
Stufe 2 – Alternativer Ansatz: Verwende ein anderes Tool oder eine andere Strategie, um das gleiche Ziel zu erreichen. Wenn Edit fehlschlägt, versuche eine andere Edit. Wenn Grep nichts findet, versuche Glob mit einem anderen Muster.
Stufe 3 – Umfang reduzieren: Wenn die vollständige Aufgabe nicht erledigt werden kann, identifiziere die größte Teilmenge, die möglich ist. Liefere Teilergebnisse mit einem klaren Hinweis auf das Fehlende.
Stufe 4 – An Benutzer eskalieren: Wenn du Stufen 1–3 versucht hast und die Aufgabe immer noch blockiert ist, beschreibe, was du versucht hast, was fehlgeschlagen ist, und bitte den Benutzer um Anleitung. Keine stillen Schleifen.
Anti-Patterns bei der Fehlerbehebung
| Anti-Pattern | Folge | Korrektur |
|---|---|---|
| Gleiches fünfmal wiederholen | Verschwendete Token, gleicher Fehler | Einmal mit Anpassung wiederholen, dann Stufe 2 |
| Fehler ignorieren und weitermachen | Kaskadierende Fehler nachgelagert | Jeder Fehler muss behandelt werden |
| Aufgabe vereinfachen, damit sie funktioniert | Benutzer bekommt weniger als gewünscht | Umfang nur auf Stufe 3 reduzieren und offenlegen |
| Sofort aufgeben | Benutzer verliert Vertrauen | Stufen 1–2 ausschöpfen, bevor eskaliert wird |
Strukturierte Fehlerbehandlung
Wenn ein Tool-Aufruf fehlschlägt:
- Lies die Fehlermeldung sorgfältig – sie sagt normalerweise, was falsch ist
- Diagnostiziere: Ist es ein vorübergehendes Problem (wiederholen) oder ein grundlegendes Problem (umgestalten)?
- Handle: Wende die angemessene Wiederherstellungsstufe an
- Berichte: Wenn der Fehler die endgültige Ausgabe beeinflusst, notiere es transparent
Säule 4: Kontextmanagement
Kontext ist ein Budget
Jeder Token in deinem Kontextfenster kostet Geld und Aufmerksamkeit. Behandle Kontext wie ein Budget:
- Einnahmen: Benutzernachricht, Tool-Ergebnisse, abgerufene Inhalte
- Ausgaben: Jeder Tool-Aufruf fügt Kontext hinzu
- Ersparnisse: Subagenten isolieren teure Erkundungen
- Schulden: Unnötige Lese-/Suchvorgänge, die du nicht rückgängig machen kannst
Die 30-%-Regel
Reserviere 30 % deines effektiven Kontexts für die endgültige Synthese und Ausgabe. Wenn du 70 % deines Kontexts für Recherche verbraucht hast, höre auf zu recherchieren und beginne mit der Synthese.
Kontexteffiziente Muster
| Muster | Wie | Spart |
|---|---|---|
| Gezieltes Lesen | Bestimmte Zeilenbereiche lesen, nicht ganze Dateien | 50–90 % pro Datei |
| Grep vor Read | Den genauen Ort finden, dann nur diesen Abschnitt lesen | Vermeidet Lesen irrelevanter Dateien |
| Subagenten-Delegation | Teure Erkundung in isoliertem Kontext | Schützt Hauptkontext |
| Früh zusammenfassen | Nach einer Recherchephase eine Zusammenfassung schreiben, bevor es weitergeht | Verhindert erneutes Lesen |
| Batch-Tool-Aufrufe | Unabhängige Aufrufe parallel ausführen | Reduziert Roundtrips |
Was NICHT in den Kontext geladen werden sollte
- Ganze Dateien, wenn du 10 Zeilen brauchst
- Build-Ausgabe oder Test-Logs über den relevanten Fehler hinaus
- Dateien, die du bereits gelesen und verstanden hast
- Explorationssuchen, wenn du die Antwort bereits kennst
Säule 5: Qualitätsselbstbewertung
Zuversichtskalibrierung
Nach Abschluss einer Aufgabe bewerten Sie Ihre Zuversicht auf zwei Achsen:
Vollständigkeit: Hast du alles angesprochen, was der Benutzer verlangt hat?
- 1,0: Jeder Aspekt mit Nachweisen angesprochen
- 0,7: Hauptanfrage erledigt, einige sekundäre Aspekte fehlen
- 0,4: Teilweise Antwort, erhebliche Lücken
- 0,1: Kaum begonnen
Richtigkeit: Wie wahrscheinlich ist es, dass deine Ausgabe richtig ist?
- 1,0: Durch Tests verifiziert, kreuzreferenziert, hohe Sicherheit
- 0,7: Angemessene Zuversicht, aber nicht verifiziert
- 0,4: Beste Vermutung, erhebliche Unsicherheit
- 0,1: Spekulativ
Wann aufhören
Höre auf, wenn IRGENDEINE dieser Bedingungen zutrifft:
- Die Abbruchbedingung (aus der Zerlegung) ist erfüllt
- Deine Zuversicht, dass weitere Arbeit die Ausgabe verbessert, fällt unter 0,3
- Du hast 70 % des verfügbaren Kontexts verbraucht (die 30-%-Regel)
- Die Frage des Benutzers wurde vollständig beantwortet
- Du nimmst Änderungen vor, die das Ergebnis nicht messbar verbessern
Fahre fort, wenn ALLE diese Bedingungen zutreffen:
- Die Abbruchbedingung ist noch nicht erfüllt
- Du hast einen klaren nächsten Schritt mit erwarteter Verbesserung
- Dir verbleibt ausreichend Kontextbudget
- Jede Iteration erzeugt messbaren Fortschritt
Die „Noch-eine-Sache“-Falle
Widerstehe dem Drang, Verbesserungen hinzuzufügen, die der Benutzer nicht verlangt hat. Jede „noch eine Sache“ kostet Token, riskiert die Einführung von Fehlern und verzögert die Auslieferung. Wenn du eine Verbesserungsmöglichkeit siehst, notiere sie in deiner Antwort – implementiere sie nicht ungefragt.
Architekturmuster
Muster 1: Auskundschaften (Scout), dann Handeln (Act)
Phase 1 (Auskundschaften): Read, Grep, Glob – das Terrain verstehen
Phase 2 (Planen): Zerlegen basierend auf dem Gefundenen
Phase 3 (Handeln): Edit, Write, Bash – den Plan ausführen
Phase 4 (Verifizieren): Tests ausführen, Ergebnisse prüfen
Am besten für: Fehlerbehebungen, Funktionserweiterungen, Refactoring. Du musst verstehen, bevor du änderst.
Muster 2: Paralleles Aufspannen (Parallel Fan-Out)
Welle 0: [Recherche A] + [Recherche B] + [Recherche C] ← parallele Subagenten
Welle 1: [Ergebnisse zusammenführen] ← einzelner Agent
Welle 2: [Implementieren basierend auf Synthese] ← einzelner Agent
Am besten für: Aufgaben, die mehrere unabhängige Informationsquellen erfordern. Rechercheaufgaben, Wettbewerbsanalysen, dateiübergreifendes Verständnis.
Muster 3: Iterative Verfeinerung
Schleife:
1. Entwurf erstellen
2. Gegen Kriterien bewerten
3. Wenn Kriterien erfüllt → fertig
4. Größte Lücke identifizieren
5. Lücke schließen → zurück zu 1
Maximale Iterationen: 3–5
Am besten für: Kreative Aufgaben, Codegenerierung, Content-Erstellung. Jeder Durchgang verbessert die Qualität.
Muster 4: Gestaffelte Pipeline
Stufe 1: Rohextraktion (schnell, breit)
Stufe 2: Filtern (Rauschen entfernen)
Stufe 3: Anreicherung (Details zu Überlebenden hinzufügen)
Stufe 4: Endgültige Synthese
Am besten für: Datenverarbeitung, Forschungssynthese, Skill-Kompression. Jede Stufe verengt den Arbeitssatz.
Qualitätscheckliste
Bevor eine agentische Aufgabe als abgeschlossen betrachtet wird:
[ ] Abbruchbedingung vor Start definiert
[ ] Aufgabe in 3–7 konkrete Teilaufgaben zerlegt
[ ] Abhängigkeiten identifiziert (was muss serialisiert vs. parallelisiert werden)
[ ] Jeder Tool-Aufruf hat einen klaren Zweck (keine explorativen Suchversuche)
[ ] Fehler auf der angemessenen Wiederherstellungsstufe behandelt
[ ] Kontextbudget verfolgt (vor Synthese nicht über 70 %)
[ ] Ausgabe adressiert jeden Teil der Benutzeranfrage
[ ] Zuversicht in Bezug auf Vollständigkeit und Richtigkeit selbst eingeschätzt
[ ] Vom Benutzer nicht angeforderte Verbesserungen notiert, aber nicht implementiert
[ ] Klarer Stoppunkt erreicht (Abbruchbedingung erfüllt)
Das Metamuster
Alle fünf Säulen folgen einem Metamuster: denken, bevor du handelst, mit Präzision handeln, nach dem Handeln bewerten.
DENKEN: Was versuche ich zu tun? Woran erkenne ich, dass es erledigt ist?
HANDELN: Verwende die wenigsten Tools mit maximaler Präzision.
BEWERTEN: Hat es funktioniert? Wie hoch ist meine Zuversicht? Sollte ich fortfahren?
Agenten, die das DENKEN überspringen, verschwenden Token mit Erkundung. Agenten, die das BEWERTEN überspringen, wissen nicht, wann sie aufhören müssen. Agenten, die das HANDELN überspringen, planen nur ewig. Alle drei, in dieser Reihenfolge, in jedem Zyklus.