DeepAgents-Architektur: Planning Tools, Sub-Agents und Dateisystem

Warum bricht Ihr KI-Agent bei komplexen Aufgaben immer wieder zusammen?

Sie lassen ihn ein Technologiethema recherchieren – nach 20 Schritten sinkt die Qualität. Sie lassen ihn eine Codebasis refaktorieren – am Ende funktioniert nichts mehr wie vorher. Sie lassen ihn einen langen Bericht schreiben – zur Hälfte wiederholt er sich oder driftet vom Thema ab.

Ich kenne das aus eigener Erfahrung. Mit einem klassischen Agent wollte ich LangGraph-Best-Practices recherchieren. Anfangs war die Ausgabe strukturiert – nach über dreißig Schritten „vergaß“ er frühere Quellen, das Analysegerüst wackelte, der Bericht wirkte zusammengestückelt und widersprüchlich.

Die Ursache ist immer dieselbe: klassische Agents sind „shallow“. Sie reagieren schrittweise, ohne Planung, ohne Gedächtnis, ohne Unteraufgaben. Wie jemandem einen 5000-Wörter-Bericht ohne Gliederung zu geben – zur Hälfte verliert er die Linie.

Claude Code, Deep Research und Manus schaffen dagegen komplexe Jobs: Refactoring über tausende Zeilen, Reports über Dutzende Seiten. Wie?

Mit der Deep-Agent-Architektur. LangChain hat sie im Paket DeepAgents verpackt. Heute zerlegen wir die vier Säulen: Planning Tools, Sub-Agents, Dateisystem und System Prompts.

Warum Deep Agents?

Fakt: Bei mehr als zehn Schritten fällt die Erfolgsrate klassischer Agents um über die Hälfte.

Das ist keine Behauptung. Daten vom Prompting Guide zeigen: Ab Schritt 11 sinkt die Qualität bei Shallow Agents deutlich. Warum? Es fehlt „Struktur im Kopf“.

Klassische Agents sind reaktiv: Anweisung → Tool → Ergebnis. Jeder Schritt steht für sich – keine Langzeitplanung, kein Zwischenzustand. Wie jemandem das ganze Haus putzen zu lassen, ohne Reihenfolge und ohne Notizen, welche Räume schon fertig sind.

Drei typische Absturzszenarien:

Deep Research. Der Agent recherchiert z. B. „LangGraph Best Practices in Produktion“. Er sucht, liest, extrahiert. Nach 20 Schritten sind frühere Funde aus dem Kontextfenster verdrängt; der Bericht passt nicht mehr zusammen.

Code-Refactoring. Tausende Zeilen, viele Module mit Abhängigkeiten – der Agent ändert eins, vergisst ein anderes. Am Ende läuft nichts mehr.

Lange Texte. Bei 5000 Wörtern wiederholt er sich oder verlässt das Thema.

Gemeinsamer Kern: Context-Kontrollverlust.

Claude Code, Deep Research und Manus nutzen dieselbe Idee: Planung, Aufgabenzerlegung, Memory, Fortschrittskontrolle. LangChain packt das in DeepAgents – im Folgenden das Design im Detail.

Die vier Säulen von DeepAgents

Philosophie: komplexe Arbeit in handhabbare Einheiten mit klaren Rollen.

KiloClaw - Managed OpenClaw für Unternehmen: AI-Agent-Orchestrierung und smartes Modell-Routing

Jetzt starten →Anzeige

Vier Säulen greifen ineinander: Planning Tools für Plan und Fortschritt, Sub-Agents für Facharbeit und Context-Isolation, File System für Speicher, System Prompts für Verhaltensgrenzen – wie Orchester: Dirigent, Instrumentengruppen, Partitur, Spielregeln.

Planning Tools: ein „Kopf“ für den Agent

Kern: todo_write.

Technisch ein No-Op – es führt keine Arbeit aus, sondern pflegt eine Aufgabenliste. Diese Liste lebt im Kontextfenster als Working Memory, sodass der Agent Plan und Fortschritt ständig „sieht“.

Beispiel Technologie-Recherche:

- [ ] LangGraph-Dokumentation suchen
- [ ] State-Machine-Design lesen
- [ ] Best-Practice-Fälle extrahieren
- [ ] Kernmuster zusammenfassen
- [ ] Strukturierten Bericht ausgeben

Nach jedem Schritt wird [ ] zu [x]. Egal wie viele Schritte – der Agent weiß, was offen, erledigt oder läuft.

Das sichert langfristige Zielkonsistenz. Ein klassischer Agent vergisst nach Schritt 20 oft das Ziel von Schritt 1. Die Todo-Liste ist wie ein Zettel am Kühlschrank: „Woran arbeitest du eigentlich?“

"Claude Code und Manus nutzen dasselbe Prinzip – Kontextfenster als Working Memory, damit der Agent nicht abdriftet"

Sub-Agents: Fachrollen und Context-Isolation

Ein Orchestrator plant und delegiert; Sub-Agents führen aus – jeweils mit eigenem Kontextfenster. Nach Abschluss geht nur das Endergebnis an den Orchestrator.

Vier Vorteile:

Context Preservation. Zwischenschritte (Suchtreffer, HTML, Extraktion) bleiben beim Sub-Agent. Der Orchestrator bekommt z. B. nur: „Diese fünf Kernpunkte gefunden.“

Specialized Expertise. research_subagent für Suche, writer_subagent für Text, coder_subagent für Code – jeweils fokussiert.

Reusability. Derselbe Sub-Agent in mehreren Workflows.

Fine-Grained Permissions. Lesen, Schreiben, Netzwerk – pro Sub-Agent getrennt.

"Empfohlen: Orchestrator-Sub-agent-Architektur (Task Decomposition Pattern) – komplexe Aufgaben in Teilaufgaben für spezialisierte Einheiten"

API-Beispiel:

from deepagents import create_deep_agent, create_subagent

# Sub-Agents definieren
research_subagent = create_subagent(
    name="research",
    tools=[internet_search, read_url],
    description="Spezialist für Recherche und Extraktion"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[write_file],
    description="Spezialist für Strukturierung und Ausgabe"
)

# Haupt-Agent
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file]
)

Context-Wechsel und Ergebnisübergabe übernimmt DeepAgents beim Aufruf.

File System: über die Kontextgrenze hinaus

Kontextfenster sind begrenzt (z. B. Claude ~200K, GPT-4 ~128K Tokens). Bei langen Jobs – große Codebasen, viele Dokumente – ist der Platz schnell voll.

Lösung: Dateireferenzen statt alles inline.

Zwischenergebnisse landen im Dateisystem; bei Bedarf read_file. Wie Forschung mit Ordnern statt alles auswendig.

Drei Backends:

StateBackend – RAM, Tests, kurze Tasks. Schnell, nicht persistent.

FilesystemBackend – lokale Dateien, Produktion. Persistent, IO-Overhead.

StoreBackend – Cloud, Enterprise, Audit. Versionierung und Logs, höherer Setup-Aufwand.

Standard oft Hybrid – Wichtiges im Context, Massendaten in Dateien.

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

System Prompts: unterschätzt, aber zentral

Viele denken: „Du bist ein hilfreicher Assistent.“ Bei Deep Agents sind System Prompts hunderte bis tausende Zeilen – Tool-Regeln, Datei-Flows, Stil.

Claude Code: hunderte Zeilen. Deep Research: tausende – Methodik, Extraktion, Output-Templates.

Warum so lang? Lange Tasks treffen Grenzfälle. Kurze Anweisungen reichen nicht. Detaillierte Prompts legen fest:

Verhaltensgrenzen – wann todo_write, wann Sub-Agent, wann direkt antworten.

Tool-Nutzung – Parameter, Rückgabeformat (Pfad vs. ID, Rohtext vs. Summary).

Output-Formate – Markdown für Reports, Diff für Refactoring, Templates für Content.

DeepAgents injiziert Prompts per Middleware – Sie müssen nicht alles selbst schreiben, sollten die Rolle aber kennen: die „Verfassung“ des Agents.

Praxis: Code durchgespielt

Technologie-Recherche-Agent – vollständiges Beispiel:

from deepagents import create_deep_agent, create_subagent
from langchain_community.tools import TavilyInternetSearch

# 1. Tools
search_tool = TavilyInternetSearch(
    name="internet_search",
    description="Internet-Recherche"
)

# 2. Sub-Agents
research_subagent = create_subagent(
    name="research",
    tools=[search_tool],
    system_prompt="Sie sind Recherche-Experte.\
                   Suchen und extrahieren Sie Kerninformationen.\
                   Nur strukturierte Ergebnisse zurückgeben, keine Zwischenschritte.",
    description="Sub-Agent für Recherche"
)

writer_subagent = create_subagent(
    name="writer",
    tools=[],
    system_prompt="Sie sind Content-Experte.\
                   Strukturieren Sie die Recherche als Bericht.\
                   Markdown mit klaren Abschnitten.",
    description="Sub-Agent für Ausgabe"
)

# 3. Deep Agent
agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    tools=[todo_write, read_file, write_file],
    backend="filesystem"
)

# 4. Ausführen
result = agent.invoke(
    "Recherchieren Sie LangGraph Best Practices\
     und liefern Sie einen strukturierten Bericht"
)

Ablauf:

Plan – todo_write:

todo_write([
    "LangGraph-Dokumentation suchen",
    "Kernarchitektur lesen",
    "Best Practices extrahieren",
    "Designmuster zusammenfassen",
    "Strukturierten Bericht ausgeben"
])

Delegate – research_subagent:

call_subagent("research", "LangGraph Best Practices recherchieren")

Der Orchestrator sieht nur die Zusammenfassung, nicht alle Roh-Suchergebnisse.

Update – Fortschritt in der Liste.

Weiter – writer_subagent, dann write_file.

Beispiel-Log:

[Step 1] todo_write: 5 Aufgaben angelegt
[Step 2] call_subagent(research): Recherche startet
[Step 3] internet_search: "LangGraph best practices"
[Step 4] read_url: 3 offizielle Docs gelesen
[Step 5] subagent_complete: research liefert Struktur
[Step 6] todo_write: 2 erledigt
[Step 7] call_subagent(writer): Bericht strukturieren
[Step 8] subagent_complete: Markdown-Bericht
[Step 9] write_file: Datei geschrieben
[Step 10] todo_write: alle erledigt

Der Orchestrator-Context bleibt schlank: Todos + Sub-Agent-Summaries, kein Rauschen der Zwischenschritte.

Vergleich mit anderen Agent-Frameworks

Neben DeepAgents gibt es LangGraph, AutoGen, CrewAI, SmolAgents – unterschiedliche Schwerpunkte.

DeepAgents vs LangGraph: DeepAgents baut auf LangGraph auf und liefert Planning, File Backend und Sub-Agent-Management fertig. LangGraph = Zustandsmaschine, freie Knoten/Kanten – Memory und Planning selbst bauen. Schnell Deep Agent → DeepAgents; tief anpassen → LangGraph.

DeepAgents vs AutoGen: AutoGen (Microsoft) betont Dialog zwischen Agents – Debatte, Verhandlung. DeepAgents betont Zerlegung und Ausführung. Team-Diskussion → AutoGen; Aufgabenzerlegung → DeepAgents.

DeepAgents vs CrewAI: CrewAI mit starken „Rollen“ (Forscher, Editor). Ähnlich Sub-Agents, aber CrewAI mehr Persona und Interaktion; DeepAgents mehr Task-Isolation.

DeepAgents vs SmolAgents: Hugging Face, Agent schreibt Python statt Tools – gut für Prototypen, schwächer bei langen Jobs. Einfach testen → SmolAgents; komplex und lang → DeepAgents.

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

"Die Wahl hängt vom Szenario ab – kein Universal-Framework, nur passende Werkzeuge"

Produktion und Best Practices

Backend-Wahl

StateBackend – Tests, kurz. Schnell, verliert Zustand beim Neustart.

FilesystemBackend – Produktion, Persistenz. Zuverlässig, IO-Kosten.

StoreBackend – Enterprise, Audit. Cloud-DB, Versionierung, mehr Setup.

from deepagents import create_deep_agent, FilesystemBackend

agent = create_deep_agent(
    subagents=[research_subagent, writer_subagent],
    backend=FilesystemBackend(
        base_path="/var/agent-state",
        max_file_size=10 * 1024 * 1024,
        cleanup_after_days=30
    )
)

Granularität der Sub-Agents

Nicht in zehn Micro-Agents zerlegen (search_google, search_bing, …) – Delegation frisst die Zeit.

3–5 Kern-Agents: research, analysis, writer, reviewer (optional). Klare Grenzen: research schreibt keinen finalen Bericht; writer sucht nicht im Web.

Performance

Dateien on demand – nicht alle Zwischendateien auf einmal laden. Pfade im Context, Inhalt bei Bedarf.

Context Summarization – bei langen Läufen komprimieren, letzte Schritte detailliert behalten:

agent = create_deep_agent(
    ...,
    context_management={
        "summarization_threshold": 50000,
        "preserve_last_n_steps": 5
    }
)

Fehler und Qualität

Lange Läufe = mehr Fehlerquellen.

LLM-as-a-Judge – zweites Modell prüft Output (z. B. reviewer_subagent für writer_subagent).

Human-in-the-loop – Checkpoint vor finaler Ausgabe:

agent = create_deep_agent(
    ...,
    verification={
        "auto_verify": True,
        "human_checkpoint": "before_output"
    }
)

Zusammenfassung

Planning Tools – todo_write als Working Memory, Zielkonsistenz über viele Schritte.

Sub-Agents – Fachrollen, sauberer Orchestrator-Context.

File System – Referenzen statt Vollload, Lesen bei Bedarf.

System Prompts – detaillierte Verhaltens- und Tool-Regeln.

Zusammen: von reaktiver Ausführung zu strukturiertem Reasoning – wie bei Claude Code, Deep Research und Manus.

Nächste Schritte:

• Ersten Langaufgaben-Agent mit DeepAgents bauen – Beispiele: GitHub langchain-ai/deepagents
• Dokumentation: docs.langchain.com/oss/python/deepagents
• Serie AI-Entwicklung in der Praxis – u. a. LangGraph-State-Machines und Agent-Memory