Mit Sub-Agenten arbeiten

Einzelne Agenten stoßen an Grenzen. Sie können nur eine Sache zur Zeit tun. Sie werden in komplexen Aufgaben überlastet. Ihre Kontextfenster füllen sich mit irrelevanten Informationen. Wenn du echte Power brauchst, brauchst du mehrere Agenten, die zusammenarbeiten.

Subagenten sind OpenClaws Lösung. Sie sind Hintergrund-Agenten-Runs, die von einem Parent-Agenten gespawnt werden und in isolierten Sessions mit eigenen Workspaces operieren. Stell sie dir als spezialisierte Worker vor, die dein Hauptagent (der Orchestrator) einstellen, Aufgaben zuweisen und Ergebnisse sammeln kann. Dieser Guide zeigt dir, wie du sie effektiv nutzt.

Was sind Subagenten?

Subagenten sind ephemere Agenten-Instanzen, die bei Bedarf mit dem sessions_spawn-Tool erstellt werden. Im Gegensatz zu deinem Hauptagenten, der persistiert und laufende Konversationen handhabt, existieren Subagenten für spezifische Aufgaben und räumen sich automatisch auf, wenn sie fertig sind.

Kern-Eigenschaften

• Isolation: Jeder Subagent hat seinen eigenen Workspace, State-Directory und Tool-Zugriff. Was in einem Subagenten passiert, bleibt dort, es sei denn, es wird explizit geteilt
• Vererbung: Subagenten können Model-Einstellungen, Thinking-Präferenzen und Kontext vom Parent-Agenten erben oder sie nach Bedarf überschreiben
• Non-blocking: Das Spawnen eines Subagenten gibt sofort eine runId zurück. Der Parent-Agent fährt mit anderer Arbeit fort, während der Subagent seine Aufgabe verarbeitet
• Auto-Archivierung: Subagenten archivieren sich automatisch nach einem Timeout (Standard 60 Minuten), bewahren Ergebnisse und geben Ressourcen frei
• Verschachtelungsfähigkeit: Subagenten können ihre eigenen Subagenten spawnen, bis zu einer Tiefe von zwei Ebenen

Wann Subagenten nutzen

Subagenten glänzen in spezifischen Szenarien:

• Parallele Verarbeitung: Führe mehrere unabhängige Aufgaben gleichzeitig statt sequentiell aus
• Spezialisierung: Weise verschiedene Agenten-Typen verschiedenen Aufgaben zu (Rechercheur, Autor, Coder, Reviewer)
• Verteilung kognitiver Last: Zerlege komplexe Probleme in kleinere Teile, die in Kontextfenster passen
• Sandboxing: Isoliere riskante Operationen (wie das Ausführen nicht vertrauenswürdigen Codes) von deinem Hauptagenten
• Kostenoptimierung: Nutze billigere Modelle für einfache Subtasks, während du teure Modelle für komplexes Reasoning reservierst

Deinen ersten Subagenten erstellen

Das sessions_spawn-Tool erstellt Subagenten. Hier ist das Basis-Muster:

// Spawn einen Subagenten mit spezifischer Aufgabe
const runId = await sessions_spawn({
  task: "Recherchiere die neuesten OpenClaw-Updates und fasse die Key-Features zusammen",
  model: "claude-sonnet-4-6",  // Optional: Parent-Model überschreiben
  thinking: "low",              // Optional: Thinking-Level
  timeout: 300                  // Optional: Timeout in Sekunden
});

Dies spawnt einen isolierten Agenten, der die Aufgabe unabhängig ausführt. Der Parent-Agent erhält sofort eine runId und kann mit anderer Arbeit fortfahren.

Basis-Beispiel: Einfache Delegation

Hier ist ein komplettes Beispiel für die Delegation einer Recherche-Aufgabe an einen Subagenten:

// Orchestrator-Agent
async function handleUserRequest(userQuery) {
  // Spawne einen Rechercheur-Subagenten
  const researchRunId = await sessions_spawn({
    task: `Recherchiere dieses Thema gründlich: ${userQuery}`,
    model: "claude-sonnet-4-6",
    thinking: "medium"
  });
  
  // Fahre mit anderer Arbeit fort (oder warte auf Ergebnisse)
  await doOtherWork();
  
  // Sammle Ergebnisse, wenn bereit
  const results = await sessions_history({
    sessionKey: researchRunId,
    limit: 50
  });
  
  // Nutze die Recherche, um Antwort zu generieren
  return generateResponse(results);
}

Subagenten-Kommunikationsmuster

Subagenten müssen Ergebnisse an ihren Parent zurückkommunizieren. OpenClaw bietet dafür mehrere Mechanismen.

Muster 1: Direkter Session-Verlauf

Der einfachste Ansatz: Lese den Nachrichten-Verlauf des Subagenten, wenn er fertig ist.

// Warte auf Subagenten-Abschluss und lese Ergebnisse
const history = await sessions_history({
  sessionKey: subagentRunId,
  includeTools: true,
  limit: 100
});

// Extrahiere das Endergebnis aus dem Verlauf
const finalResult = history.messages[history.messages.length - 1].content;

Dieses Muster funktioniert gut für einfache Aufgaben mit klaren Outputs. Der Parent-Agent pollt oder wartet, bis der Subagent fertig ist, und extrahiert dann Ergebnisse aus seinem Session-Verlauf.

Muster 2: Gemeinsame Workspace-Dateien

Für komplexe Workflows können Subagenten Ergebnisse in gemeinsame Dateien schreiben:

// Subagent schreibt Ergebnisse in eine Datei
await fs.writeFile('/workspace/results/research.json', JSON.stringify({
  topic: userQuery,
  findings: researchResults,
  sources: sourceList,
  confidence: confidenceScore
}));

// Parent-Agent liest die Datei später
const results = JSON.parse(
  await fs.readFile('/workspace/results/research.json', 'utf8')
);

Dieses Muster glänzt, wenn mehrere Subagenten zu gemeinsamen Outputs beitragen oder wenn Ergebnisse über die Lebenszeit des Subagenten hinaus persistieren müssen.

Muster 3: Nachrichten-Passing

Für Echtzeit-Koordination nutze sessions_send für direkten Agent-zu-Agenten-Nachrichtenaustausch:

// Sende eine Nachricht an die Session eines anderen Agenten
await sessions_send({
  sessionKey: targetAgentRunId,
  message: "Recherche abgeschlossen. Starte Phase 2.",
  timeoutSeconds: 30
});

Hinweis: Direktes Messaging muss explizit in der Konfiguration aktiviert werden. Für die meisten Workflows wird das Routing über den Orchestrator für einfacheres Auditing und Debugging bevorzugt.

Multi-Subagenten-Orchestrierung

Die echte Power entsteht, wenn du mehrere Subagenten zusammen orchestrierst. Hier sind bewährte Muster.

Muster 1: Parallele Map

Spawne mehrere Subagenten gleichzeitig, um unabhängige Aufgaben zu verarbeiten:

// Verarbeite 10 Artikel parallel
const articles = await fetchArticleList();
const runIds = await Promise.all(
  articles.map(article => 
    sessions_spawn({
      task: `Fasse diesen Artikel zusammen: ${article.url}`,
      model: "claude-haiku-4-6"  // Billiges Model für einfache Aufgabe
    })
  )
);

// Warte auf alle Abschlüsse und sammle Ergebnisse
const summaries = await Promise.all(
  runIds.map(id => sessions_history({ sessionKey: id, limit: 20 }))
);

Dieses Muster reduziert die Gesamtverarbeitungszeit von der Summe individueller Aufgaben auf die Dauer des langsamsten Tasks.

Muster 2: Sequentielle Pipeline

Kette Subagenten, bei der der Output jedes Schritts in den nächsten fließt:

// Recherche -> Schreiben -> Editieren Pipeline
const researchRunId = await sessions_spawn({
  task: "Recherche: Vorteile von Multi-Agenten-Systemen",
  model: "claude-sonnet-4-6"
});

const research = await waitForCompletion(researchRunId);

const writingRunId = await sessions_spawn({
  task: `Schreibe Artikel basierend auf dieser Recherche: ${research}`,
  model: "claude-opus-4-6"
});

const draft = await waitForCompletion(writingRunId);

const editingRunId = await sessions_spawn({
  task: `Editiere diesen Artikel für Klarheit: ${draft}`,
  model: "claude-sonnet-4-6"
});

Dieses Muster sorgt für Qualität in jeder Phase, bevor es weitergeht. Nutze es, wenn Schritte klare Abhängigkeiten und Qualitäts-Gates haben.

Muster 3: Hub and Spoke

Ein zentraler Orchestrator delegiert an spezialisierte Subagenten basierend auf Aufgabentyp:

// Orchestrator analysiert Anfrage und routed entsprechend
async function routeTask(userRequest) {
  const intent = await classifyIntent(userRequest);
  
  switch(intent) {
    case 'code':
      return sessions_spawn({ 
        task: userRequest, 
        model: "claude-opus-4-6",
        context: "Du bist ein Experten-Programmierer."
      });
    case 'research':
      return sessions_spawn({ 
        task: userRequest, 
        model: "claude-sonnet-4-6",
        context: "Du bist ein gründlicher Rechercheur."
      });
    case 'creative':
      return sessions_spawn({ 
        task: userRequest, 
        model: "gpt-4",
        context: "Du bist ein kreativer Autor."
      });
  }
}

Dieses Muster matcht Aufgabentypen mit optimalen Agenten-Konfigurationen. Es ist das häufigste Produktions-Muster für Multi-Agenten-Systeme.

Verschachtelte Subagenten

Für komplexe Workflows können Subagenten ihre eigenen Subagenten spawnen. Dies ermöglicht hierarchische Aufgabendekomposition.

Beispiel: Hierarchische Recherche

Ein Meta-Rechercheur-Subagent kann an spezialisierte Rechercheur-Sub-Subagenten delegieren:

// Level 1: Meta-Rechercheur (Subagent des Orchestrators)
async function metaResearch(topic) {
  // Zerlege Thema in Sub-Themen
  const subTopics = await analyzeTopic(topic);
  
  // Spawne Spezialisten-Rechercheure (Level 2 Subagenten)
  const researchRuns = await Promise.all(
    subTopics.map(st => 
      sessions_spawn({
        task: `Deep-Recherche zu: ${st}`,
        model: "claude-sonnet-4-6",
        timeout: 600
      })
    )
  );
  
  // Synthetisiere Ergebnisse
  const findings = await Promise.all(
    researchRuns.map(r => sessions_history({ sessionKey: r }))
  );
  
  return synthesizeReport(findings);
}

Dieses Muster skaliert zu beliebiger Komplexität, während jeder Agent seinen Kontext fokussiert und handhabbar hält.

Fehlerbehandlung und Recovery

Subagenten können fehlschlagen. Deine Orchestrierung muss dies elegant handhaben.

Muster: Retry mit Fallback

async function resilientSpawn(task, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const runId = await sessions_spawn({
      task: task,
      model: i === 0 ? "claude-sonnet-4-6" : "claude-opus-4-6"
      // Eskaliere Model bei Retry
    });
    
    try {
      const result = await waitWithTimeout(runId, 300);
      if (result.success) return result;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      // Logge und versuche erneut
    }
  }
}

Dieses Muster versucht fehlgeschlagene Subagenten mit stärkeren Models erneut, maximiert Erfolgsraten und minimiert Kosten.

Kostenoptimierungsstrategien

Subagenten ermöglichen ausgefeiltes Kostenmanagement.

Strategie 1: Gestufte Model-Auswahl

Nutze billigere Modelle für einfache Subtasks:

• Haiku/GPT-3.5: Zusammenfassung, Formatierung, einfache Extraktion
• Sonnet/GPT-4: Recherche, Analyse, moderate Komplexität
• Opus/GPT-4 Turbo: Komplexes Reasoning, Coding, finale Qualitätsprüfung

Strategie 2: Parallelisierungs-Einsparungen

Parallele Subagenten reduzieren die Echtzeit-Verarbeitungszeit, was in zeitbasierten Umgebungen die Gesamtkosten senken kann. Sie verhindern auch Kontextfenster-Überlauf, der teure Neustarts von Konversationen erfordern würde.

Strategie 3: Frühe Terminierung

Überwache Subagenten-Fortschritt und breche früh ab, wenn Qualitätsschwellen nicht erreicht werden:

// Prüfe Zwischenergebnisse und brich bei Bedarf ab
const intermediate = await sessions_history({ 
  sessionKey: runId, 
  limit: 10 
});

if (detectLowQuality(intermediate)) {
  await process_kill({ sessionId: runId });
  return fallbackApproach();
}

Best Practices

Lektionen aus Produktions-Multi-Agenten-Systemen:

Halte Subagenten fokussiert

Gib jedem Subagenten eine einzelne, klar definierte Aufgabe. Vage Anweisungen produzieren vage Ergebnisse. Spezifische Aufgaben produzieren spezifische Outputs.

Begrenze Parallelität

Setze maxConcurrentRuns, um APIs oder deine eigene Infrastruktur nicht zu überlasten. Starte mit 3-5 parallelen Subagenten und erhöhe basierend auf Performance.

Versioniere deine Workflows

Speichere Workflow-Definitionen in Versionskontrolle. Subagenten-Orchestrierung ist Code. Behandle sie mit der gleichen Rigorosität wie jede andere Codebase.

Überwache und logge

Logge alle Subagenten-Spawns, Abschlüsse und Fehler. Verfolge, welche Subagenten die besten Ergebnisse produzieren. Diese Daten leiten zukünftige Optimierungen.

Teste isoliert

Teste Subagenten-Aufgaben unabhängig, bevor du sie in komplexe Workflows integrierst. Ein defekter Subagent zerstört die gesamte Pipeline.

Häufige Fallstricke

Vermeide diese Fehler:

Over-Subagenting

Nicht jede Aufgabe braucht einen Subagenten. Einfache Operationen, die leicht in den Kontext deines Hauptagenten passen, sind ohne Spawn schneller und billiger. Nutze Subagenten für Parallelisierung, Spezialisierung oder Sandboxing.

Kontextverlust

Subagenten erben nicht automatisch den gesamten Parent-Kontext. Übergib essentiellen Kontext explizit in der Aufgabenbeschreibung oder gemeinsamen Dateien.

Vorzeitige Optimierung

Optimiere Subagenten-Modelle oder Parallelisierung nicht, bevor du Basis-Metriken hast. Messe zuerst, dann optimiere.

Timeouts ignorieren

Setze immer vernünftige Timeouts. Ein hängender Subagent verschwendet Ressourcen und blockiert deinen Workflow. Standardmäßig 5-10 Minuten für die meisten Aufgaben.

Nächste Schritte

Starte einfach. Erstelle einen Subagenten für eine einzelne Aufgabe. Gewöhne dich an Spawnen, Überwachen und Ergebnisse sammeln. Steigere dann schrittweise die Komplexität.

Wenn du bereit bist, erkunde unseren Multi-Agenten-Systeme-Guide für Orchestrierungsmuster, Kommunikationsstrategien und Produktions-Deployment-Ratschläge. Kombiniere Subagenten mit Skills, Model-Routing und Speicherverwaltung für wirklich leistungsstarke KI-Systeme.