Orchestrator

The orchestrator implements a manager-worker pattern. It uses an LLM to decompose complex tasks into subtasks, then dispatches them to parallel subagent workers. Results are synthesized into a final response.

Details


ID	`nexus.agent.orchestrator`
Dependencies	`nexus.agent.subagent`

Configuration

Key	Type	Default	Description
`max_workers`	int	`5`	Maximum concurrent subagent workers
`max_subtasks`	int	`8`	Maximum number of subtasks to decompose into
`worker_max_iterations`	int	`10`	Max iterations per worker subagent
`orchestrator_model_role`	string	`reasoning`	Model for task decomposition
`worker_model_role`	string	`balanced`	Model for worker execution
`synthesis_model_role`	string	`balanced`	Model for result synthesis
`fail_fast`	bool	`false`	Stop all workers if one fails
`system_prompt`	string	(none)	System prompt for the orchestrator
`system_prompt_file`	string	(none)	Path to system prompt file

Events

Subscribes To

Event	Priority	Purpose
`io.input`	50	Receives user tasks
`tool.result`	50	Tool results during decomposition
`llm.response` / `llm.stream.*`	50	LLM responses
`skill.loaded`	50	Skill content
`tool.register`	50	Tool discovery
`subagent.started`	50	Worker started notification
`subagent.iteration`	50	Worker progress
`subagent.complete`	50	Worker finished
`cancel.active` / `cancel.resume`	5	Cancellation
`memory.compacted`	50	History compaction

Emits

Event	When
`llm.request`	Decomposition and synthesis LLM calls
`before:tool.invoke` / `tool.invoke`	Tool invocation
`before:tool.result`	Before tool result propagation (vetoable)
`thinking.step`	Decomposition and synthesis reasoning
`io.status`	Phase transitions
`agent.turn.start` / `agent.turn.end`	Turn boundaries

Phases

stateDiagram-v2
    direction LR
    [*] --> idle
    idle --> decomposing: agent.turn.start
    decomposing --> dispatching: subtasks ready
    dispatching --> executing: workers spawned
    executing --> executing: subtask completed
    executing --> synthesizing: all subtasks done
    synthesizing --> idle: agent.turn.end
    idle --> [*]

    note right of decomposing
        orchestrator LLM
        breaks task into
        subtasks
    end note
    note right of executing
        parallel workers
        respect max_workers
    end note

Decomposing — The orchestrator LLM breaks the task into subtasks with descriptions and optional dependencies
Dispatching — Subtasks are queued and sent to subagent workers (respecting max_workers concurrency)
Executing — Workers run in parallel; the orchestrator tracks progress and collects results
Synthesizing — All results are gathered and the synthesis LLM produces a unified response

Subtask Dependencies

The orchestrator can recognize dependencies between subtasks. Dependent subtasks wait until their prerequisites complete before dispatching.

Failure Handling

fail_fast: false (default) — Other workers continue even if one fails. Failed results are included in synthesis.
fail_fast: true — All remaining workers are cancelled when any worker fails.

Session Context in Prompts

Both the per-worker system prompt (dispatching) and the synthesis system prompt get a <session_context> section: the current session’s general-namespace (non-_-prefixed) tags, rendered fresh for each build and omitted entirely when none are set. See Prompt Registry → Agent-Level Semantic Tags and Session Tags for what populates it and why the reserved namespace never reaches either prompt.

Example Configuration

plugins:
  active:
    - nexus.io.tui
    - nexus.llm.anthropic
    - nexus.agent.orchestrator
    - nexus.agent.subagent
    - nexus.agent.react
    - nexus.tool.shell
    - nexus.tool.file
    - nexus.memory.capped
    - nexus.control.cancel

  nexus.agent.orchestrator:
    max_workers: 3
    max_subtasks: 6
    orchestrator_model_role: reasoning
    worker_model_role: balanced
    synthesis_model_role: balanced
    fail_fast: false

  nexus.agent.subagent:
    max_iterations: 10

When to Use

The orchestrator is ideal for:

Complex tasks that naturally decompose into independent subtasks
Research across multiple topics that can be explored in parallel
Code analysis across multiple files or modules simultaneously
Any task where parallel execution significantly reduces total time

Keyboard shortcuts

Nexus Documentation