Sub-Agenten

An Subagenten delegieren. Arbeit auf spezialisierte Agenten verteilen. Sub-Agenten sind Hintergrund-Agentenläufe, die aus einem bestehenden Agentenlauf gestartet werden. Sie laufen in einer eigenen Sitzung (agent:<agentId>:subagent:<uuid>) und melden bei Fertigstellung ihr Ergebnis zurück an den anfragenden Chat-Kanal.

Slash-Befehl

/subagents zum Inspizieren oder Steuern von Sub-Agenten-Läufen der aktuellen Sitzung:

/subagents list
/subagents stop <id|#|all>
/subagents log <id|#> [limit] [tools]
/subagents info <id|#>
/subagents send <id|#> <message>

/subagents info zeigt Lauf-Metadaten (Status, Zeitstempel, Sitzungs-ID, Transkript-Pfad, Cleanup). Hauptziele:

„Recherche / lange Aufgabe / langsames Tool“ parallelisieren, ohne den Hauptlauf zu blockieren.
Sub-Agenten standardmäßig isoliert halten (Sitzungstrennung + optionales Sandboxing).
Die Tool-Oberfläche schwer missbrauchbar halten: Sub-Agenten erhalten standardmäßig keine Sitzungs-Tools.
Verschachteltes Fan-Out vermeiden: Sub-Agenten können keine Sub-Agenten starten.

Kosten-Hinweis: Jeder Sub-Agent hat eigenen Kontext und Token-Verbrauch. Für schwere oder wiederholte Aufgaben ein günstigeres Modell für Sub-Agenten setzen und den Hauptagenten auf einem höherwertigen Modell lassen. Konfigurierbar über agents.defaults.subagents.model oder pro-Agent-Überschreibungen.

Tool

sessions_spawn nutzen:

Startet einen Sub-Agenten-Lauf (deliver: false, globale Lane: subagent)
Führt dann einen Announce-Schritt aus und postet die Announce-Antwort in den anfragenden Chat-Kanal
Standardmodell: erbt vom Aufrufer, außer du setzt agents.defaults.subagents.model (oder pro Agent agents.list[].subagents.model); ein explizites sessions_spawn.model gewinnt weiterhin.

Tool-Parameter:

task (erforderlich)
label? (optional)
agentId? (optional; unter anderer Agent-ID starten, wenn erlaubt)
model? (optional; überschreibt das Sub-Agenten-Modell; ungültige Werte werden übersprungen, Sub-Agent läuft mit Default-Modell mit Warnung im Tool-Ergebnis)
thinking? (optional; überschreibt Thinking-Level für den Sub-Agenten-Lauf)
runTimeoutSeconds? (Standard 0; wenn gesetzt, wird der Sub-Agenten-Lauf nach N Sekunden abgebrochen)
cleanup? (delete|keep, Standard keep)

Allowlist:

agents.list[].subagents.allowAgents: Liste der Agent-IDs, die per agentId ansprechbar sind (["*"] für beliebige). Standard: nur der anfragende Agent.

Discovery:

agents_list nutzen, um zu sehen, welche Agent-IDs aktuell für sessions_spawn erlaubt sind.

Auto-Archiv:

Sub-Agenten-Sitzungen werden automatisch nach agents.defaults.subagents.archiveAfterMinutes (Standard: 60) archiviert.
Archiv nutzt sessions.delete und benennt das Transkript in *.deleted.<timestamp> um (gleicher Ordner).
cleanup: "delete" archiviert sofort nach Announce (Transkript bleibt per Umbenennung erhalten).
Auto-Archiv ist Best-Effort; ausstehende Timer gehen bei Gateway-Neustart verloren.
runTimeoutSeconds archiviert nicht automatisch; es stoppt nur den Lauf. Die Sitzung bleibt bis Auto-Archiv.

Authentifizierung

Sub-Agenten-Auth wird nach Agent-ID aufgelöst, nicht nach Sitzungstyp:

Der Sub-Agenten-Sitzungs-Key ist agent:<agentId>:subagent:<uuid>.
Der Auth-Store wird aus dem agentDir dieses Agenten geladen.
Die Auth-Profile des Hauptagenten werden als Fallback eingemischt; Agent-Profile überschreiben Haupt-Profile bei Konflikten.

Hinweis: Die Zusammenführung ist additiv, Haupt-Profile sind also immer als Fallback verfügbar. Vollständig getrennte Auth pro Agent wird noch nicht unterstützt.

Announce

Sub-Agenten melden per Announce-Schritt zurück:

Der Announce-Schritt läuft in der Sub-Agenten-Sitzung (nicht der anfragenden Sitzung).
Antwortet der Sub-Agent exakt ANNOUNCE_SKIP, wird nichts gepostet.
Sonst wird die Announce-Antwort per Follow-up-agent-Aufruf (deliver=true) in den anfragenden Chat-Kanal gepostet.
Announce-Antworten bewahren Thread/Topic-Routing, wenn verfügbar (Slack-Threads, Telegram-Topics, Matrix-Threads).
Announce-Nachrichten werden auf eine stabile Vorlage normalisiert:
- Status: aus dem Lauf-Ergebnis (success, error, timeout oder unknown).
- Result: die Zusammenfassung aus dem Announce-Schritt (oder (not available) wenn fehlend).
- Notes: Fehlerdetails und anderer nützlicher Kontext.
Status wird nicht aus der Modellausgabe abgeleitet; er kommt von Laufzeit-Ergebnis-Signalen.

Announce-Payloads enthalten am Ende eine Stats-Zeile (auch bei Umbrüchen):

Laufzeit (z. B. runtime 5m12s)
Token-Verbrauch (Input/Output/Gesamt)
Geschätzte Kosten, wenn Modell-Preise konfiguriert sind (models.providers.*.models[].cost)
sessionKey, sessionId und Transkript-Pfad (damit der Hauptagent per sessions_history die Historie holen oder die Datei auf Disk prüfen kann)

Tool-Richtlinie (Sub-Agenten-Tools)

Standardmäßig erhalten Sub-Agenten alle Tools außer Sitzungs-Tools:

sessions_list
sessions_history
sessions_send
sessions_spawn

Überschreiben per Config:


{
  agents: {
    defaults: {
      subagents: {
        maxConcurrent: 1
      }
    }
  },
  tools: {
    subagents: {
      tools: {
        // deny gewinnt
        deny: ["gateway", "cron"],
        // bei allow wird es allow-only (deny gewinnt weiter)
        // allow: ["read", "exec", "process"]
      }
    }
  }
}

Parallelität

Sub-Agenten nutzen eine eigene In-Process-Queue-Lane:

Lane-Name: subagent
Parallelität: agents.defaults.subagents.maxConcurrent (Standard 8)

Stoppen

/stop im anfragenden Chat bricht die anfragende Sitzung ab und stoppt alle aktiven Sub-Agenten-Läufe, die von ihr gestartet wurden.

Einschränkungen

Sub-Agenten-Announce ist Best-Effort. Bei Gateway-Neustart geht ausstehende „announce back“-Arbeit verloren.
Sub-Agenten teilen weiterhin dieselben Gateway-Prozess-Ressourcen; maxConcurrent als Sicherheitsventil behandeln.
sessions_spawn ist immer nicht-blockierend: Es gibt sofort { status: "accepted", runId, childSessionKey } zurück.
Sub-Agenten-Kontext injiziert nur AGENTS.md + TOOLS.md (kein SOUL.md, IDENTITY.md, USER.md, HEARTBEAT.md oder BOOTSTRAP.md).