Skip to content

Orchestrator and Workers

The worker system provides structured delegation for complex tasks. The Orchestrator coordinates multi-step conversation turns, while the Background Task Runner handles long-running web research independently of the main generation loop.

Orchestrator

Orchestrator (core/worker/orchestrator.py) is the primary conversational coordinator — a single orchestrator with helper worker delegation. It replaces the former multi-agent loop in which all active agents responded in turn.

Flow per Conversation Turn

  1. Intent detection — The orchestrator analyzes incoming messages for patterns:
  2. _PLANNER_KEYWORDS → spawn PLANNER worker for complex task planning
  3. _SUMMARIZER_THRESHOLD (500 chars) → SUMMARIZER for long context compression

  4. memory_mode active → RETRIEVER for vector memory lookup

  5. Helper worker spawn — Workers dispatched via WorkerPool.delegate() with typed configurations

  6. Primary agent generation — Main agent generates response enriched with worker results

  7. Return result — OrchestratorResult (frozen dataclass) containing:

  8. response_text — final generated response
  9. worker_results — outputs from each helper worker
  10. correlation_id — unique trace identifier
  11. duration_ms — total turn duration
  12. primary_agent_name — which agent handled the turn
  13. worker_count — number of helper workers spawned
  14. first_token_ms — time to first generated token

Key Classes

  • Orchestrator — orchestrate() for full turn execution, delegate() for single-worker delegation
  • OrchestratorResult — Frozen result with traces and timing data
  • OrchestratorProtocol — Defined in service_protocols.py for dependency injection

Worker System

WorkerPool (core/worker/worker_system.py) manages non-speaking internal workers that communicate through typed events:

Worker Type Purpose
PLANNER Breaks complex requests into step-by-step plans
RETRIEVER Queries vector memory for relevant context
SUMMARIZER Compresses long conversation history
INDEXER Organizes and indexes knowledge bases
TOOL_PREPARER Pre-validates tool availability
REASONER Independent reasoning pass for complex logic

The worker pool provides bounded concurrency, per-type limits, token budgets, timeouts, cancellation support, and trace event publishing.

Background Task Runner

BackgroundTaskRunner (core/worker/background_task_runner.py) executes long-running operations independently of the main generation loop. Primary use case: deep web research.

Web Research Protocol

A three-phase protocol for full-page deep research:

RESEARCH → SYNTHESIZE → DEEPER RESEARCH
  1. RESEARCH — web_search(task) runs betterwright exec --no-daemon: a headless-browser agent (running the worker's model) reads full pages and returns a complete answer with a Sources: list
  2. SYNTHESIZE — Agent generates a comprehensive response grounded in the research findings
  3. DEEPER RESEARCH — When the answer is incomplete, a follow-up web_search on a different angle runs before synthesizing again

Quality Guards

Guards prevent wasteful or redundant research:

Guard Purpose
Exact-duplicate guard Won't re-run the identical task within a task
Near-duplicate task detection Rejects tasks with ≥0.50 Jaccard word overlap against already-executed tasks, reminding the agent of existing findings
Multi-topic awareness Tracks distinct topics so the agent finishes the current topic before starting the next

Task Queue

TaskQueue (core/worker/task_queue.py) is a bounded async queue with:

  • Priority ordering (semaphore + size limit)
  • Retry with exponential back-off
  • Per-task timeouts and cancellation
  • Result futures for async completion
  • EventBus integration for status updates
  • Bounded history retention

Telemetry

Metric Description
queue.depth Current queue depth (gauge)
queue.task_ms Task execution duration

Worker spawn/complete events publish via EventBus with correlation IDs for end-to-end tracing.

See Also