Sub-Agents nutzen für parallele Workflows

Kennst du das? Du gibst deinem Agent eine komplexe Aufgabe, wie eine ausführliche Recherche oder das Analysieren großer Log-Dateien, und plötzlich steht das Gespräch still. Du musst warten, bis der Agent fertig ist, bevor du die nächste Frage stellen kannst. Das bremst deinen Workflow aus und ist besonders nervig, wenn du eigentlich parallel an anderen Dingen weiterarbeiten möchtest.

Mit Sub-Agents löst du dieses Problem. Sie ermöglichen es dir, Aufgaben in separate Hintergrund-Sessions auszulagern. Während der Sub-Agent arbeitet, bleibt dein Haupt-Agent sofort wieder einsatzbereit. Sobald der Sub-Agent fertig ist, meldet er seine Ergebnisse automatisch im Chat zurück.

Voraussetzungen

• Ein aktives Agent-Setup
• Zugriff auf das sessions_spawn Tool

Schnellstart

Der einfachste Weg, einen Sub-Agent zu starten, ist eine natürliche Anweisung im Chat. Du musst keine komplizierten Befehle auswendig lernen.

1. Einfacher Befehl: Sag deinem Agent einfach: „Erstelle einen Sub-Agent, um die neuesten Node.js Release Notes zu recherchieren.“
2. Hintergrund-Prozess: Der Agent ruft im Hintergrund das sessions_spawn Tool auf. Du erhältst sofort eine Bestätigung, während der Sub-Agent in einer isolierten Session startet.
3. Explizite Optionen: Du kannst auch direkt Vorgaben machen: „Erstelle einen Sub-Agent, um die Server-Logs von heute zu analysieren. Nutze gpt-5.2 und setze einen Timeout von 5 Minuten.“
4. Ergebnis: Sobald die Aufgabe erledigt ist, postet der Haupt-Agent eine Zusammenfassung der Ergebnisse direkt in deinen Chat.

How It Works

Der Prozess läuft in vier klaren Phasen ab:

1. Main Agent Spawn: Der Haupt-Agent ruft sessions_spawn mit der Aufgabenbeschreibung auf. Dieser Aufruf ist non-blocking. Er erhält sofort eine Antwort mit { status: "accepted", runId, childSessionKey }.
2. Hintergrund-Lauf: Eine neue isolierte Session wird erstellt (agent:<agentId>:subagent:<uuid>). Diese läuft auf einer eigenen Queue namens subagent.
3. Ankündigung der Ergebnisse: Wenn der Sub-Agent fertig ist, sendet er seine Erkenntnisse an den ursprünglichen Chat zurück. Der Haupt-Agent erstellt daraus eine Zusammenfassung in natürlicher Sprache.
4. Archivierung: Die Sub-Agent-Session wird nach 60 Minuten automatisch archiviert. Die Transcripts bleiben dabei erhalten.

Ich empfehle dir, für Sub-Agents ein günstigeres Modell zu wählen. Da sie oft spezialisierte Aufgaben wie Web Scraping oder Code-Analysen übernehmen, kannst du so massiv Token-Kosten sparen, ohne die Qualität der Hauptkonversation zu beeinflussen.

Configuration

Sub-Agents funktionieren ohne manuelle Konfiguration mit Standardwerten (8 maximale parallele Tasks, Archivierung nach 60 Minuten). Du kannst das Verhalten aber in deiner Konfiguration anpassen.

Ein Standard-Modell festlegen

Nutze ein günstigeres Modell für Sub-Agents, um Kosten zu optimieren:

{
  agents: {
    defaults: {
      subagents: {
        model: "minimax/MiniMax-M2.1",
      },
    },
  },
}

Thinking Level anpassen

{
  agents: {
    defaults: {
      subagents: {
        thinking: "low",
      },
    },
  },
}

Overrides pro Agent

In einem Setup mit mehreren Agents kannst du spezifische Regeln festlegen:

{
  agents: {
    list: [
      {
        id: "researcher",
        subagents: {
          model: "anthropic/claude-sonnet-4",
        },
      },
      {
        id: "assistant",
        subagents: {
          model: "minimax/MiniMax-M2.1",
        },
      },
    ],
  },
}

Concurrency und Archivierung

Steuere, wie viele Sub-Agents gleichzeitig laufen dürfen und wann Sessions archiviert werden:

{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 4, // Standard: 8
        archiveAfterMinutes: 120, // Standard: 60
      },
    },
  },
}

Die Archivierung benennt das Transcript in *.deleted.<timestamp> um. Die Daten werden also nicht gelöscht, sondern nur aus der aktiven Ansicht entfernt.

Fehlerbehebung

• Timer-Verlust: Die Auto-Archive-Timer basieren auf dem aktuellen Systemstatus. Wenn das Gateway neu startet, gehen laufende Timer verloren.
• Queue-Blockierung: Sub-Agents nutzen eine eigene Queue (subagent). Wenn Aufgaben dort hängen, blockiert das jedoch nicht die eingehenden Antworten deines Haupt-Agents.

Du hast Fragen zur Einrichtung? Nutze den AI Setup Assistant für schnelle Hilfe.

Nächste Schritte

• Setting a Default Model
• Multi-Agent Setups verstehen

Kennst du das? Du baust einen Agent, der eigentlich alles können soll, aber die Logik wird mit jedem Feature komplexer. Der Kontext quillt über und die Performance leidet, weil ein einzelner Agent versucht, zu viele verschiedene Aufgaben gleichzeitig zu jonglieren.

Anstatt alles in eine einzige Session zu packen, ist es besser, spezialisierte Sub-Agents für Teilaufgaben einzusetzen. Das sessions_spawn Tool ist genau dafür da. Es hilft dir dabei, Aufgaben sauber zu trennen und die Kontrolle über Ressourcen und Modelle zu behalten.

Voraussetzungen

• Zugriff auf das sessions_spawn Tool innerhalb deiner Agent-Umgebung.
• Eine bestehende Agent-Konfiguration (falls du Cross-Agent Spawning nutzen möchtest).

Schnellstart

Das Tool sessions_spawn wird vom Agent aufgerufen, um neue Sub-Agents zu instanziieren. Hier sind die verfügbaren Parameter:

Parameter	Typ	Standard	Beschreibung
task	string	(erforderlich)	Was der Sub-Agent tun soll.
label	string	—	Kurzes Label zur Identifizierung.
agentId	string	(Agent des Aufrufers)	Startet unter einer anderen Agent ID (muss erlaubt sein).
model	string	(optional)	Überschreibt das Modell für diesen Sub-Agent.
thinking	string	(optional)	Überschreibt das Thinking Level (off, low, medium, high, etc.).
runTimeoutSeconds	number	0 (kein Limit)	Bricht den Sub-Agent nach N Sekunden ab.
cleanup	"delete" | "keep"	"keep"	"delete" archiviert die Session sofort nach der Ankündigung.

So wird das Modell bestimmt

Wenn ein Sub-Agent gestartet wird, entscheidet das System nach dieser Priorität, welches Modell verwendet wird (der erste Treffer gewinnt):

1. Expliziter model Parameter im sessions_spawn Aufruf.
2. Agent-spezifische Config: agents.list[].subagents.model.
3. Globaler Default: agents.defaults.subagents.model.
4. Die normale Modell-Resolution des Ziel-Agents für diese neue Session.

So wird das Thinking Level bestimmt

Für das Thinking Level gilt eine ähnliche Logik:

1. Expliziter thinking Parameter im sessions_spawn Aufruf.
2. Agent-spezifische Config: agents.list[].subagents.thinking.
3. Globaler Default: agents.defaults.subagents.thinking.
4. Falls nichts davon zutrifft, wird kein spezifischer Thinking-Override angewendet.

Cross-Agent Spawning

Standardmäßig können Agents Sub-Agents nur unter ihrer eigenen agentId erstellen. Wenn du einem Agent erlauben willst, Sub-Agents unter anderen Identitäten zu starten, musst du das in der Konfiguration explizit freigeben:

{
  agents: {
    list: [
      {
        id: "orchestrator",
        subagents: {
          allowAgents: ["researcher", "coder"], // oder ["*"] für alle IDs
        },
      },
    ],
  },
}

Nutze am besten das agents_list Tool, um herauszufinden, welche Agent IDs für sessions_spawn aktuell autorisiert sind.

Fehlerbehebung

• Ungültige Modelle: Wenn du einen ungültigen Wert für model übergibst, wird dieser ignoriert. Der Sub-Agent nutzt stattdessen den nächsten validen Default-Wert. Du erhältst in diesem Fall eine Warnung innerhalb des Tool Results.
• Berechtigungsfehler: Falls das Spawning unter einer anderen agentId fehlschlägt, prüfe die allowAgents Liste in deiner Konfiguration.

Fragen zum Setup? Nutze den AI Setup Assistant.

Nächste Schritte

• Verwendung des agents_list Tools
• Agent Konfigurations-Schema

Kennst du das? Du startest einen komplexen Task, dein Agent spawnt mehrere Sub-Agenten und plötzlich fühlt sich alles wie eine Black Box an. Du weißt nicht genau, welcher Prozess gerade Ressourcen frisst oder warum ein bestimmter Teilschritt so lange dauert. Es ist frustrierend, wenn du die Kontrolle verlierst und nicht einfach “reinschauen” kannst, was im Hintergrund passiert.

Die Lösung ist der /subagents Command. Damit holst du dir die Transparenz zurück und steuerst deine Sub-Agenten direkt aus dem Chat heraus.

Voraussetzungen

• Eine aktive Session mit laufenden oder abgeschlossenen Sub-Agenten
• Zugriff auf das CLI oder das Chat-Interface deiner Agent-Umgebung

Schnellstart

In weniger als 5 Minuten hast du den vollen Überblick:

1. Nutze /subagents list, um alle aktiven und beendeten Runs zu sehen.
2. Identifiziere den Sub-Agenten über seinen Index (z. B. 1) oder die ID.
3. Verwende /subagents info 1, um Details zum Status und Task zu erhalten.
4. Falls ein Run hängt, stoppe ihn sofort mit /subagents stop 1.

Sub-Agenten verwalten (/subagents)

Verwende den /subagents Slash-Command, um Sub-Agent-Runs der aktuellen Session zu inspizieren und zu steuern:

Command	Beschreibung
/subagents list	Listet alle Sub-Agent-Runs auf (aktiv/beendet)
/subagents stop <id|#|all>	Stoppt einen laufenden Sub-Agenten
/subagents log <id|#> [limit] [tools]	Zeigt das Transkript des Sub-Agenten an
/subagents info <id|#>	Zeigt detaillierte Run-Metadaten
/subagents send <id|#> <message>	Sendet eine Nachricht an einen laufenden Run

Du kannst Sub-Agenten über den Listen-Index (1, 2), das Run-ID-Präfix, den vollständigen Session-Key oder last referenzieren.

Beispiel: Sub-Agent auflisten und stoppen

/subagents list

🧭 Subagents (current session)
Active: 1 · Done: 2
1) ✅ · research logs · 2m31s · run a1b2c3d4 · agent:main:subagent:...
2) ✅ · check deps · 45s · run e5f6g7h8 · agent:main:subagent:...
3) 🔄 · deploy staging · 1m12s · run i9j0k1l2 · agent:main:subagent:...

/subagents stop 3

⚙️ Stop requested for deploy staging.

Beispiel: Sub-Agent inspizieren

/subagents info 1

ℹ️ Subagent info
Status: ✅
Label: research logs
Task: Research the latest server error logs and summarize findings
Run: a1b2c3d4-...
Session: agent:main:subagent:...
Runtime: 2m31s
Cleanup: keep
Outcome: ok

Beispiel: Sub-Agent Log einsehen

/subagents log 1 10

Dies zeigt die letzten 10 Nachrichten aus dem Transkript des Sub-Agenten. Füge tools hinzu, um Tool-Calls einzuschließen:

/subagents log 1 10 tools

Beispiel: Follow-up Nachricht senden

/subagents send 3 "Also check the staging environment"

Dies sendet eine Nachricht in die Session des laufenden Sub-Agenten und wartet bis zu 30 Sekunden auf eine Antwort.

Announce (Wie Ergebnisse zurückkommen)

Wenn ein Sub-Agent fertig ist, durchläuft er einen Announce-Schritt:

1. Die finale Antwort des Sub-Agenten wird erfasst.
2. Eine Zusammenfassung mit Ergebnis, Status und Statistiken wird an die Session des Haupt-Agenten gesendet.
3. Der Haupt-Agent postet eine Zusammenfassung in natürlicher Sprache in deinen Chat.

Announce-Antworten behalten das Thread/Topic-Routing bei, sofern verfügbar (Slack Threads, Telegram Topics, Matrix Threads).

Announce Stats

Jeder Announce enthält eine Stats-Zeile mit folgenden Daten:

• Runtime Dauer
• Token-Verbrauch (Input/Output/Gesamt)
• Geschätzte Kosten (wenn die Modell-Preise über models.providers.*.models[].cost konfiguriert sind)
• Session-Key, Session-ID und Transkript-Pfad

Announce Status

Die Announce-Nachricht enthält einen Status, der vom Runtime-Ergebnis abgeleitet wird (nicht vom Modell-Output):

• successful completion (ok) — Task wurde normal abgeschlossen.
• error — Task ist fehlgeschlagen (Details in den Notes).
• timeout — Task hat runTimeoutSeconds überschritten.
• unknown — Status konnte nicht ermittelt werden.

[!TIP] Wenn keine für den User sichtbare Ankündigung benötigt wird, kann der Zusammenfassungs-Schritt des Haupt-Agenten NO_REPLY zurückgeben. Das unterscheidet sich von ANNOUNCE_SKIP, welches im Agent-zu-Agent Flow (sessions_send) verwendet wird.

Fehlerbehebung

• Status ist “error”: Überprüfe die Notes in der Zusammenfassung oder nutze /subagents log <id>, um den genauen Fehlerpunkt im Transkript zu finden.
• Sub-Agent reagiert nicht: Nutze /subagents info, um zu prüfen, ob der Status noch auf 🔄 steht. Falls er hängt, nutze /subagents stop.

Hast du Fragen zur Einrichtung? Frag den AI Setup Assistant.

Nächste Schritte

• Erfahre mehr über sessions_send für Agent-zu-Agent Kommunikation.
• Optimiere deine Kosten durch die Konfiguration der Modell-Preise.

Wenn du Sub-Agents einsetzt, kennst du das Problem: Manchmal versuchen sie, Aufgaben zu übernehmen, für die sie nicht gedacht sind. Es ist nervig, wenn ein Hintergrund-Task plötzlich versucht, Sessions zu verwalten oder tiefe System-Einstellungen zu ändern, anstatt einfach nur den zugewiesenen Job zu erledigen. Du möchtest, dass deine Sub-Agents fokussiert bleiben und keine unnötigen oder gefährlichen Tools nutzen.

Hier erfährst du, wie du die Tool Policy präzise konfigurierst, damit deine Agents genau das tun, was sie sollen – nicht mehr und nicht weniger.

Voraussetzungen

• Einen konfigurierten Main-Agent
• Sub-Agents, die über den Main-Agent gestartet werden
• Zugriff auf die Konfigurationsdateien deines Projekts

Quick Start: Tool-Zugriff einschränken

Standardmäßig erhalten Sub-Agents Zugriff auf fast alle Tools. Ausgenommen ist eine Liste von gesperrten Tools, die für Hintergrund-Tasks entweder unsicher oder schlicht unnötig sind.

Standardmäßig gesperrte Tools

Diese Tools sind für Sub-Agents im Standard-Setup deaktiviert:

Denied tool	Grund
sessions_list	Session management — Main-Agent orchestriert
sessions_history	Session management — Main-Agent orchestriert
sessions_send	Session management — Main-Agent orchestriert
sessions_spawn	Kein verschachteltes Fan-out (Sub-Agents können keine Sub-Agents starten)
gateway	System admin — Gefährlich aus einem Sub-Agent heraus
agents_list	System admin
whatsapp_login	Interactive setup — Keine Aufgabe für Sub-Agents
session_status	Status/Scheduling — Main-Agent koordiniert
cron	Status/Scheduling — Main-Agent koordiniert
memory_search	Relevante Infos sollten stattdessen im Spawn-Prompt übergeben werden
memory_get	Relevante Infos sollten stattdessen im Spawn-Prompt übergeben werden

Eigene Tool-Beschränkungen festlegen

Du kannst die Tools für Sub-Agents noch weiter einschränken. Nutze dafür die deny-Liste in deiner Konfiguration. Wichtig: deny gewinnt immer gegen allow.

{
  tools: {
    subagents: {
      tools: {
        // deny gewinnt immer gegen allow
        deny: ["browser", "firecrawl"],
      },
    },
  },
}

Wenn du möchtest, dass Sub-Agents ausschließlich bestimmte Tools nutzen dürfen, verwende die allow-Liste:

{
  tools: {
    subagents: {
      tools: {
        allow: ["read", "exec", "process", "write", "edit", "apply_patch"],
        // deny gewinnt weiterhin, falls gesetzt
      },
    },
  },
}

Eigene deny-Einträge werden zur Standard-Liste hinzugefügt. Wenn allow gesetzt ist, sind nur diese Tools verfügbar, wobei die Standard-Sperrliste trotzdem obenauf angewendet wird.

Authentication und Identität

Die Authentication für Sub-Agents wird über die agent id gelöst, nicht über den Session-Typ. Das funktioniert so:

1. Der Auth-Store wird aus dem agentDir des Ziel-Agents geladen.
2. Die Auth-Profile des Main-Agents werden als fallback hinzugefügt.
3. Bei Konflikten gewinnen die Profile des Sub-Agents.
4. Der Merge ist additiv – Main-Profile stehen immer als Fallback bereit.

Aktuell wird eine komplett isolierte Authentication pro Sub-Agent nicht unterstützt.

Context und System Prompt

Sub-Agents arbeiten mit einem reduzierten System Prompt. Das sorgt dafür, dass sie sich auf ihre spezifische Aufgabe konzentrieren und nicht versuchen, die Rolle des Main-Agents einzunehmen.

Diese Sektionen sind enthalten:

• Tooling, Workspace, Runtime
• AGENTS.md und TOOLS.md

Diese Sektionen fehlen:

• SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md

Zusätzlich erhält der Sub-Agent einen aufgabenbezogenen System Prompt. Dieser weist ihn an, fokussiert zu bleiben, die Aufgabe abzuschließen und nicht als Main-Agent zu agieren.

Fehlerbehebung

Hier sind Lösungen für bekannte Probleme bei der Tool-Konfiguration:

• Problem: Ein Tool in der allow-Liste taucht beim Sub-Agent nicht auf.
• Lösung: Prüfe, ob das Tool in der “Default denied tools”-Liste steht. Da deny immer Vorrang hat, kannst du Standard-Sperren nicht einfach über allow aufheben.
• Problem: Sub-Agent hat keinen Zugriff auf API-Credentials.
• Lösung: Stelle sicher, dass die Profile im agentDir des Sub-Agents korrekt hinterlegt sind oder im Main-Agent als Fallback existieren.

Hast du Fragen zu deinem Setup? Nutze den AI Setup Assistant für schnelle Hilfe.

Nächste Schritte

• Agent Configuration Guide
• Advanced Tooling
• Multi-Agent Orchestration
• Security Best Practices

---
title: Stopping Sub-Agents
description: So behältst du die volle Kontrolle über deine Sub-Agents und verwaltest Ressourcen effizient.
---

Es passiert schnell: Ein Task läuft länger als geplant oder ein Agent verfängt sich in einer unnötigen Schleife. Wenn du mit Sub-Agents arbeitest, willst du sicherstellen, dass Prozesse nicht endlos weiterlaufen und unnötig Ressourcen oder API-Kosten verursachen.

Die Kontrolle über den Lebenszyklus deiner Agents ist entscheidend, um dein System stabil zu halten. Hier erfährst du, wie du laufende Sub-Agents gezielt beendest und Timeouts konfigurierst.

## Voraussetzungen

- Zugriff auf das Gateway
- Eine bestehende Konfiguration für `agents.defaults.subagents`

## Schnellstart

Du hast verschiedene Möglichkeiten, Sub-Agents zu stoppen – entweder manuell per Chat oder automatisiert über die Konfiguration.

### Methoden zum Beenden

| Methode | Effekt |
| :--- | :--- |
| `/stop` im Chat | Bricht die Haupt-Session **und** alle aktiven Sub-Agent-Runs ab, die daraus gestartet wurden. |
| `/subagents stop <id>` | Stoppt einen spezifischen Sub-Agent, ohne die Haupt-Session zu beeinflussen. |
| `runTimeoutSeconds` | Bricht den Sub-Agent-Run automatisch nach der angegebenen Zeit ab. |
| Gateway Restart | Beendet alle laufenden Prozesse (beachte die Auswirkungen auf Timer unten). |

> [!NOTE]
> `runTimeoutSeconds` führt **keine** automatische Archivierung der Session durch. Die Session bleibt bestehen, bis der reguläre Archive-Timer greift.

## Konfigurationsbeispiel

Hier ist eine vollständige Konfiguration, die zeigt, wie du Sub-Agents definierst und Limits setzt:

```json
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4" },
      subagents: {
        model: "minimax/MiniMax-M2.1",
        thinking: "low",
        maxConcurrent: 4,
        archiveAfterMinutes: 30,
      },
    },
    list: [
      {
        id: "main",
        default: true,
        name: "Personal Assistant",
      },
      {
        id: "ops",
        name: "Ops Agent",
        subagents: {
          model: "anthropic/claude-sonnet-4",
          allowAgents: ["main"], // ops can spawn sub-agents under "main"
        },
      },
    ],
  },
  tools: {
    subagents: {
      tools: {
        deny: ["browser"], // sub-agents can't use the browser
      },
    },
  },
}

Fehlerbehebung

Beachte diese technischen Einschränkungen und Verhaltensweisen, wenn Sub-Agents nicht wie erwartet reagieren:

• Best-effort announce: Wenn das Gateway neu startet, gehen alle ausstehenden Announce-Aufgaben verloren.
• Keine Schachtelung: Sub-Agents können keine eigenen Sub-Agents starten (No nested spawning).
• Geteilte Ressourcen: Sub-Agents nutzen denselben Gateway-Prozess. Verwende maxConcurrent als Sicherheitsventil für deine Hardware.
• Auto-Archivierung: Die automatische Archivierung arbeitet nach dem Best-effort-Prinzip. Wenn das Gateway neu startet, gehen laufende Archive-Timer verloren.

Hast du spezifische Fragen zu deinem Setup? Nutze den AI Setup Assistant.

Nächste Schritte

• Session Tools — Details zu sessions_spawn und anderen Tools.
• Multi-Agent Sandbox and Tools — Tool-Einschränkungen pro Agent.
• Configuration — Referenz für agents.defaults.subagents.
• Queue — Funktionsweise der subagent Lane.