Coordinator

The Coordinator component is an advanced orchestration node that coordinates multiple specialized sub-agents. It analyzes task complexity, plans execution, routes to appropriate sub-agents, and synthesizes their results into a unified response.

Scenarios

Use the Coordinator when a single query requires:

Data from multiple sources or agents (e.g., semantic search + SQL metrics)
Multi-step analysis where results of one step inform the next
Parallel execution of independent sub-tasks

How It Works

When a query reaches the Coordinator component, it runs through five phases:

Phase 1 — Complexity Analysis

The agent evaluates the query against available sub-agent capabilities and classifies it into one of three levels:

Level	Behavior
LOW	Single sub-agent is sufficient — simple, well-scoped query
MEDIUM	Two sub-agents in sequence (e.g. find assets via API, then fetch metrics via DB)
HIGH	Multiple sub-agents in parallel — complex, multi-dimensional queries

Phase 2 — Sub-Agent Selection

Routes the query to the appropriate sub-agents using the configured strategy (capability_based, load_balanced, or priority_based). Sub-agent descriptions are critical here — clear, accurate descriptions directly influence routing accuracy.

Phase 3 — Execution Planning

Builds a structured multi-phase plan with assigned agents, phase dependencies, and success criteria.

Phase 4 — Coordinated Execution

Executes each phase, passing context-aware queries to sub-agents. The Coordinator component copies the full conversation history to every sub-agent so that follow-up questions and ambiguous inputs resolve correctly.

Phase 5 — Result Synthesis

Aggregates outputs from all sub-agents, extracts key insights, and produces a final unified response. For queries returning structured data from multiple sources, results are merged and de-duplicated before being returned to the user.

Coordination Patterns

Pattern	Description	Use Case
Sequential	Phases execute one after another; each can use prior outputs	Retrieval → Processing → Reporting
Parallel	Multiple agents run simultaneously	Market research + Competitive analysis + Financial data
Pipeline	Results stream between agents in real-time	Live ingestion → Processing → Visualization
Conditional	Branching logic based on intermediate results	IF error THEN retry ELSE continue

Configuration

Parameter	Type	Default	Description
`Model`	string	—	Language model for orchestration decisions
`System Prompt`	string	—	Pre-configured orchestration instructions — do not modify
`Connected Sub-Agents`	array	`[]`	Sub-agents this component can coordinate
`Agent Selection Strategy`	string	`capability_based`	How sub-agents are selected: `capability_based`, `load_balanced`, or `priority_based`
`Coordination Strategy`	string	`sequential`	`sequential`, `parallel`, `pipeline`, or `conditional`
`Parallel Execution`	boolean	`true`	Allow sub-agents to run in parallel when phases are independent
`Failure Handling`	string	`retry_once`	`fail_fast`, `retry_once`, `retry_with_fallback`, or `continue_partial`
`Enable Reflection`	boolean	`true`	Reflect on results for quality improvement
`Max Execution Time`	number	`1800`	Maximum execution time in seconds
`Sub-Agent Timeout`	number	`300`	Timeout per sub-agent in seconds
`Temperature`	number	`0.1`	Controls randomness in orchestration decisions
`Thinking Budget`	number	`10000`	Maximum tokens for thinking steps

Error Handling

Strategy	Behavior
`fail_fast`	Stop on first error — use when partial results are unacceptable
`retry_once`	Retry failed sub-agent once with exponential backoff
`retry_with_fallback`	Retry, then route to an alternative sub-agent
`continue_partial`	Continue despite failures and synthesize successful results only

Usage

Add the Coordinator component to your canvas.
Connect your specialized sub-agents as downstream components.
Set the coordination strategy appropriate for your workflow (sequential for dependent tasks, parallel for independent ones).
Connect the Coordinator output to an Interact component to return results to the user.

Best Practices

Keep sub-agents focused — each sub-agent should have a single, clear purpose
Write accurate sub-agent descriptions — the Coordinator uses them to route queries correctly
Avoid deep nesting — coordinate sub-agents from a Coordinator, not from other Coordinators
Use parallel execution when phases have no dependencies to improve response time
Set appropriate timeouts — balance responsiveness with task complexity

Troubleshooting

Sub-agents not receiving conversation history

Symptom: Follow-up questions fail; sub-agents lack context.
Solution: Verify history is being copied to the external canvas before sub-agent execution.

LLM token limit exceeded

Symptom: Query reformulation fails with a token limit error.
Solution: Reduce the context size passed to the reformulation step or adjust the truncation token limit.

Sub-agent timeout

Symptom: TimeoutError during sub-agent execution.
Solution: Increase sub_agent_timeout in the Coordinator configuration, or optimize the sub-agent’s performance.

Incorrect routing

Symptom: Queries are sent to the wrong sub-agent.
Solution: Review and improve sub-agent descriptions — they are the primary signal used for routing decisions.