Coordinator

Der coordinator ist die Persona, mit der der Benutzer tatsächlich spricht. Jede Chat-Session (Web-UI, Slack, Telegram, Feishu) gehört einer coordinator-Instanz. Er ist kein Worker — er ist die langlebige ReAct-Loop, die das Gespräch antreibt, entscheidet, wann direkt zu antworten ist, und entscheidet, wann via AgentTool zu einem Specialist zu dispatchen ist.

Identität

Feld	Wert
Persona-Name	default
Spawnbar als Worker	Nein — der Agent-Katalog schließt default aus
Session-Modell	Eine langlebige chat_sessions-Zeile pro (user, Chat-Thread)
Tool-Tasche	Breit: query_*, AgentTool, SendMessage, TaskStop, Redirect-Stubs
Persona-Body	Wird im Manager-Image ausgeliefert; Per-Org-Override via gemountete Datei

Wenn Sie das flottenweite Verhalten des coordinators ändern wollen, mounten Sie eine benutzerdefinierte default.md über die eingebaute (siehe Benutzerdefinierte Agenten). Die AgentRegistry.Replace-Naht ist das, was die User-Agent-Edit-UI antreibt; eine Override-Datei verwendet denselben Code-Pfad beim Start.

Was er direkt tun kann

Die Tool-Tasche des coordinators enthält alle Read-Only-Query-Tools, die im Manager-Scope funktionieren:

• query_promql, query_logql, query_traceql — Telemetrie. Auf dem coordinator gestubbt (Weiterleitung zum incident-investigator) für bekannte Halluzinations-Fälle — siehe unten.
• query_knowledge — RAG über Vault + Uploads.
• query_incidents, get_incident_detail, query_alert_rules, query_devices — Alarm- / Inventar.
• query_change_events — kürzliche Config- / Regel- / Device-Mutationen.
• expand_topology, find_topology_node — Dienstgraph.
• get_active_incidents — aktuell offene Alarme.
• BC-Handler-Tools — alles, was ein Org-/User-Admin aus der UI tun würde.

Er trägt absichtlich keine Host-Shell- oder Per-Host-Inspektionstools. Diese liegen auf den Specialists.

Das Steuer-Tool-Trio

Drei spezielle Tools liegen ausschließlich auf dem coordinator. Sie steuern die Multi-Agent-Orchestrierung; sie fragen nichts ab.

AgentTool

Einen Worker dispatchen. Synchron. Das vollständige Schema, das Dedupe-Verhalten und die „nicht für Trivia delegieren"-Leitlinie sind auf der Agents-Übersicht dokumentiert. Die Form:

{
  "description": "Find which process is OOM-ing on node-01",
  "subagent_type": "specialist-compute",
  "prompt": "On device_id=7 we saw mem_used_pct=98 at 14:02. Find the top RSS processes and check dmesg for oom-killer hits. The user originally asked: 'who's eating memory on node-01?'"
}

Der System-Reminder injiziert den Persona-Katalog, sodass das LLM die gültigen subagent_type-Werte kennt. Der Reminder ist pro-Turn — selbst nach Aufmerksamkeits-Drift in langen Sessions vergisst das LLM nie, welche Specialists existieren.

SendMessage

Sendet eine Zwischennachricht an den Benutzer, ohne den Turn zu beenden. Wird verwendet, wenn der coordinator sagen will „Ich dispatch zu specialist-network — geben Sie mir eine Minute", bevor sich der Dispatch festsetzt. Workers tragen dieses Tool nicht — nur der coordinator spricht mit dem Benutzer.

Die IM-Bridge verwendet dies, um die Platzhalter-Nachricht im Chat zu aktualisieren (chat.update auf Slack, editMessageText auf Telegram, PUT /messages auf Feishu). Die Web-UI verwendet es, um Zwischen-Text in das Transkript zu streamen, bevor die finale Antwort kommt.

TaskStop

Bricht einen laufenden Worker höflich ab. Der coordinator emittiert TaskStop, wenn z. B. der Benutzer mitten im Dispatch das Thema wechselt und die Antwort des laufenden Workers nicht mehr relevant ist.

Intern ruft es Runtime.StopWorker auf, was das context.CancelFunc des Workers feuert. Der Worker beobachtet ctx.Done() bei seinem nächsten Tool-Aufruf und setzt Status = killed.

Wann dispatchen vs. direkt antworten

Das Persona-Prompt des coordinators kodiert die Regel:

AgentTool 不是默认选项。能用本地工具 1-2 步答出来的，自己答。复杂深挖 （需要 5+ 步 / 跨主机 / 跨信号面）才派。

Auf Deutsch: nur dispatchen, wenn die Aufgabe

• tiefe Iteration benötigt (5+ Tool-Aufrufe fokussierter Inspektion),
• hostseitige Tools benötigt (host_bash, host_probe_*, host_du_summary), oder
• von einer domänenspezifischen Tool-Tasche profitiert, die der coordinator nicht trägt.

Bei „what's the load on node-01?" antwortet der coordinator direkt mit einem get_host_load (nun — mit einem Redirect-Stub-vermittelten AgentTool(specialist-compute); das Prinzip ist dasselbe). Bei „why is the order service throwing 502s and what should I do about it?" dispatcht der coordinator zu incident-investigator.

Redirect-Stubs (Anti-Halluzination)

Die Tasche des coordinators trägt RedirectStub-Einträge für Tool-Namen, die das LLM bekanntermaßen halluziniert (host_bash, host_du_summary, host_restart_service, get_host_load, correlate_incident, …). Wenn das LLM einen gestubbten Namen wählt, gibt der Stub zurück:

{
  "status": "redirect",
  "hint": "This tool is not available in coordinator scope. Re-invoke via AgentTool to dispatch to specialist-disk.",
  "reason": "目录占用分析",
  "suggested_call": "AgentTool(description=\"…\", subagent_type=\"specialist-disk\", prompt=\"<self-contained task>\", background=true)",
  "why_stub_exists": "Coordinator's job is dispatch + triage. Deep-dive tools live on specialist workers; calling them inline is the wrong pattern."
}

Ohne diese Stubs würde einos Graph-Runtime mit [NodeRunError] tool X not found in toolsNode indexes abbrechen und den Turn verschwenden. Mit ihnen lernt das LLM aus dem Ergebnis und versucht es bei der nächsten Iteration mit dem korrekten AgentTool-Aufruf erneut. Die Stub-Liste liegt in CoordinatorRedirectStubs; sie ist reine Daten — über die Zeit erweitern, wenn neue Halluzinationen auftauchen.

Nicht die gesamte Specialist-Tasche überschatten

Jeder Stub belegt einen Slot in der LLM-präsentierten Schema-Liste. Stubben Sie zu viele Tools, und das Prompt-Budget bläht sich auf; das LLM könnte beginnen, Stubs als gültige Optionen zu behandeln. Nur Tools, die in Evals halluziniert wurden, bekommen einen Stub.

Was der Benutzer sieht

Pro Turn kann der coordinator:

1. Tokens direkt streamen — die Antwort ist kurz und in sich geschlossen.
2. Read-Only-Query-Tools inline aufrufen — query_incidents, expand_topology, query_knowledge.
3. Einen Worker via AgentTool dispatchen — die SPA rendert ein „Agent-Tile" mit dem Persona-Namen + der 1-Zeilen-Beschreibung, während der Worker läuft. Das endgültige Worker-Ergebnis landet als Kind des Tiles.
4. Eine Zwischennachricht via SendMessage senden — meist bevor sich ein langsamer Dispatch festsetzt („Looking into it; spawning specialist-network").
5. Einen Worker via TaskStop stoppen — selten, meist nur wenn der Benutzer mitten im Dispatch umleitet.

Der Benutzer sieht das Roh-Transkript des Workers nie. Der coordinator synthetisiert das Result des Workers in seine eigene Antwort.

Session und Audit

• Coordinator-Session liegt in chat_sessions mit agent_id = "default" und parent_session_id = NULL.
• Worker-Sessions bekommen ein parent_session_id, das auf die Zeile des coordinators zeigt. Die Audit-UI traversiert diesen Baum, um Parent → Child-Läufe zu rendern.
• Jeder Tool-Aufruf bekommt eine audit_logs-Zeile mit der Sicht des LLM auf die Args und das gekürzte Ergebnis (siehe Self-Observability).

Den Coordinator anpassen

Sie können die Persona-Datei des coordinators überschreiben. Dinge, die Sie typischerweise ändern wollen:

• Die Dispatch-Anleitung (Ihr Team hat eine andere „wann zu delegieren"-Policy).
• Die Ausgabesprache / den Ton (verwenden Sie default_locale auf dem Kanal; oder pinnen Sie über den Persona-Body).
• Die Liste der Read-Only-Inline-Tools, die der coordinator vor dem Dispatchen verwenden soll.

Dinge, die Sie nicht ändern sollten:

• Den Agent-Katalog-Block — er ist maschinengeneriert. Bearbeiten hat keine Wirkung; der nächste Reload regeneriert ihn.
• Die Redirect-Stub-Semantik — sie sind Code, nicht Persona.
• Den default-name — die Runtime sucht den coordinator per Name.

Siehe Benutzerdefinierte Agenten für die Hot-Reload-Story.