subagents/

Verschachtelte Agenten, jeder ein eigenes, gewöhnliches BX-Agents-Projekt.

subagents/

subagents/ enthält verschachtelte Agenten, jeder ein eigenes, gewöhnliches BX-Agents-Projekt - ein Agent.bx + instructions.md (und optional eigene tools/, skills/ usw.):

my-agent/
├── Agent.bx              # subAgents: ["researcher"]
├── instructions.md
└── subagents/
    └── researcher/
        ├── Agent.bx
        └── instructions.md

Ein Subagent wird namentlich mit seinem Elternteil verdrahtet, deklariert in der configure() des Elternteils in Agent.bx - der ORDNERNAME unter subagents/, zur Build-Zeit verdrahtet, zu unterscheiden vom eigenen subAgents-Argument von super.init() (das bereits gebaute AiAgent-Instanzen nimmt, keine Namen):

// Agent.bx
class extends="bxModules.bxai.models.runnables.AiAgent" {

	function init() {
		super.init(
			name  : "my-agent",
			model : aiModel( provider: "openai", params: { model: "gpt-5" } )
		)
		return this
	}

	function configure() {
		return {
			subAgents : [ "researcher" ]
		};
	}

}

Zur Build-Zeit umwickelt bx-ais addSubAgent() jede gebaute Subagenten-Instanz automatisch als aufrufbares Tool am Elternteil - es gibt keinen separaten, selbst zu schreibenden Tool-Wrapping-Schritt.

Flacher Namensraum, Geschwisterreferenzen

Jeder Subagent - egal wie tief die eigene Konfiguration eines anderen Subagenten ihn referenziert - liegt direkt unter dem subagents/-Ordner des Root-Projekts. Die eigenen deklarierten subAgents eines Subagenten referenzieren Geschwister-Einträge in genau diesem Root-Level-Ordner, nicht einen unter sich selbst verschachtelten Ordner. Das hält das Discovery-/Validierungsmodell einfach: ein flacher gerichteter Graph über die unmittelbaren Unterordner von subagents/, statt eines Baums, der auf der Platte beliebig tief verschachtelt sein könnte.

Flach auf der Platte, ein Graph in der Konfiguration, von unten nach oben gebaut - die drei Sichten auf dasselbe Projekt:

flowchart LR
    subgraph disk["ON DISK - always flat, one level under the ROOT project"]
        direction TB
        R1["subagents/A/"]
        R2["subagents/B/"]
        R3["subagents/C/"]
    end

    subgraph declared["DECLARED - each Agent.bx's own subAgents list"]
        direction TB
        GA["A"] --> GB["B"] --> GC["C"]
    end

    subgraph built["BUILT - leaf-first, in GeneratedAgentFactory.bx"]
        direction TB
        O1["1. build C"] --> O2["2. build B<br/>with the built C"] --> O3["3. build A<br/>with the built B"]
    end

    disk -.->|"names resolve<br/>against siblings"| declared
    declared -.->|"a parent needs its<br/>children already built"| built

    style disk fill:#eef2f7,stroke:#5a6570
    style declared fill:#e7f1ff,stroke:#004085
    style built fill:#eaf6ec,stroke:#155724

Ein Zyklus im deklarierten Graphen (A -> B -> A) wird bei der Validierung abgelehnt, bevor irgendetwas davon generiert wird; ein Diamant (zwei Elternteile, die sich einen Nachfahren teilen) ist unproblematisch.

Build-Reihenfolge

Subagenten werden blattzuerst (von unten nach oben) gebaut: Deklariert A subAgents: ["B"] und B deklariert subAgents: ["C"], baut die generierte GeneratedAgentFactory.bx zuerst C, dann B (unter Übergabe der gebauten C-Instanz), dann A (unter Übergabe der gebauten B-Instanz) - nie umgekehrt, da der aiAgent()-Aufruf eines Elternteils die bereits gebauten Instanzen seiner Kinder braucht.

Validierung

• Ein Subagentenname in subAgents, der zu keinem echten subagents/{name}/Agent.bx passt, schlägt bei der Validierung mit einem klaren Fehler "references unknown subagent [...]" fehl - das gilt für die subAgents-Liste jedes Knotens, einschließlich des eigenen Agent.bx des Root-Projekts, nicht nur verschachtelter Subagenten.
• Zirkuläre Referenzen (A → B → A) werden zur Validierungszeit abgelehnt, mit dem vollständigen gemeldeten Zyklenpfad (z. B. A -> B -> A), bevor irgendeine Codegenerierung stattfindet.
• Eine "Diamant"-Form - zwei Subagenten, die beide vom selben gemeinsamen Nachfahren abhängen - ist kein Zyklus und baut problemlos; nur echte Zyklen werden abgelehnt.
• Ein fehlendes Agent.bx innerhalb eines entdeckten subagents/*-Ordners wird als eigener Validierungsfehler gemeldet.
• Der eigene DEKLARIERTE name jedes Knotens (Root + jedes Subagenten eigenes Agent.bx) muss über das gesamte Projekt hinweg eindeutig sein - siehe unten.

Retrieving an agent from schedules/Scheduler.bx

Zwei unterschiedliche Namen sind im Spiel, und sie sind nicht austauschbar:

• Der Ordnername unter subagents/ (researcher oben) ist das, worauf subAgents: [ "..." ] referenziert - ein reines Build-Zeit-Verdrahtungsanliegen.
• Der eigene deklarierte name des Subagenten (das name-Feld seines Agent.bx, z. B. "ResearchBot") ist es, mit dem er zur Laufzeit abgerufen wird - jeder Agent im Baum (Root + jeder Subagent) wird in config/WireBox.bx unter diesem Namen registriert, sodass schedules/Scheduler.bx (oder jeder andere WireBox-fähige Code) ihn mit einem einfachen getInstance( "ResearchBot" ) erreicht.

Diese beiden Namen können abweichen, und werden es oft - der Ordnername ist ein Implementierungsdetail, der deklarierte name ist derjenige, der überall sonst zählt (Prompts, WireBox-Retrieval). Weil er jetzt auch ein WireBox-Bindungsschlüssel ist, schlägt build bei der Validierung fehl, falls zwei Agenten im Baum - wie tief auch immer verschachtelt - denselben deklarierten name haben, einschließlich zweier, die beide unset lassen und sich still den Standardwert "BxAi" teilen.