Orchestrator Agents
Current Workflow Usage
The committed reasoningEngineWorkflow uses the Step Orchestrator Agent during preflight when enableStepOrchestration is enabled. The older Orchestrator Agent remains registered for planning and tool-orchestration use cases, but it is not the agent called by preflight.step.ts for current workflow step selection.
Purpose
The Step Orchestrator Agent evaluates the user's analytical objective against the available data dimensions and produces an execution plan -- an ordered list of pipeline steps to invoke. This selective execution eliminates unnecessary computation: a straightforward statistical query does not require pattern detection, correlation analysis, or domain knowledge retrieval.
Value Proposition
- Reduced latency -- 30-50% faster responses for targeted queries by bypassing irrelevant stages
- Lower API cost -- fewer agent invocations translates directly to fewer LLM tokens consumed
- Preserved quality -- the explanation and validation steps always execute, maintaining output integrity regardless of which analytical steps are selected
Decision Logic
The step orchestrator receives these inputs:
- The user's objective -- the analytical question to answer
- A dataset summary -- available data dimensions, time range, and metric count
It returns an execution plan specifying which steps to invoke and in what order.
Representative Decisions
| Objective | Steps Selected | Steps Skipped | Rationale |
|---|---|---|---|
| "What was my average stress?" | temporal, explanation, validation | pattern, correlation, domain | Statistical query requires only temporal analysis |
| "Does stress affect my sleep?" | temporal, correlation, explanation, validation | pattern, domain | Relationship question requires correlation computation |
| "How have I been doing?" | All 6 steps | None | Broad exploratory question benefits from comprehensive analysis |
| "What should I do to feel better?" | temporal, pattern, domain, explanation, validation | correlation | Recommendation request requires domain knowledge and pattern context |
Pipeline Position
The Step Orchestrator executes during the preflight step and its output determines the remainder of the pipeline. A supplied stepPlan takes priority over AI orchestration; UI step toggles are also converted to a deterministic plan before the AI fallback runs.
Technical Reference
Identifiers
| Property | Value |
|---|---|
| Current Step Orchestrator Registry ID | reasoning-engine-step-orchestrator-agent |
| Current Step Orchestrator Profile ID | reasoning-step-orchestrator |
| Current Step Orchestrator Code | src/mastra/agents/reasoning-engine/core/step-orchestrator.ts |
| Current Step Orchestrator Accessor | getStepOrchestratorAgent() |
| Legacy Orchestrator Registry ID | reasoning-engine-orchestrator-agent |
| Legacy Orchestrator Profile ID | reasoning-orchestrator |
| Legacy Orchestrator Code | src/mastra/agents/reasoning-engine/core/orchestrator.ts |
Input/Output Schemas
Input:
{
"objective": "Understand stress patterns this week",
"datasetSummary": "7 days of stress, sleep, and mood check-ins"
}
Output:
{
"steps": ["temporal", "pattern", "correlation", "explanation", "validation"],
"reasoning": "Included temporal/pattern/correlation for multi-metric time-series analysis; skipped domain because no recommendation or external context was requested."
}
Default Prompt
The Step Orchestrator prompt requires raw JSON with steps and reasoning. Allowed step names are temporal, pattern, correlation, domain, explanation, and validation; explanation and validation are always required.
Configuration
Update the current workflow prompt via Admin tools, SQL, or API targeting the reasoning-step-orchestrator profile. Use reasoning-orchestrator only for the legacy/planning agent.