Reasoning Engine Agents

Agent Architecture

The Reasoning Engine delegates analytical responsibilities across a team of specialized agents, each scoped to a single analytical discipline. This decomposition follows the principle that focused models with domain-specific prompts produce higher-quality output than general-purpose models tasked with the full analytical spectrum.

The specialization enables two architectural advantages:

Precision through focus -- each agent's system prompt is tuned exclusively for its analytical domain, yielding more accurate and consistent results than a monolithic approach.
Independent configurability -- prompt tuning, model selection, and temperature adjustments for one agent (e.g., improving narrative quality in the explanation agent) have zero impact on the statistical accuracy of upstream agents.

Collaboration Model

The agents execute in a defined sequence, where each stage builds upon the accumulated output of prior stages. The pipeline is organized into four functional phases:

Execution Flow

The Step Orchestrator evaluates the user's objective and the available data dimensions to determine which pipeline steps are relevant, producing an execution plan that may skip unnecessary stages when enableStepOrchestration is enabled.
The Temporal Agent performs statistical computation across all time-series inputs: means, extremes, trend direction, and volatility measures. Its output provides the quantitative foundation for all downstream analysis.
The Pattern Agent combines algorithmic detection with semantic analysis to identify behavioral signatures -- recurring cycles, cross-metric correlations, and warning indicators that statistical summaries alone do not surface.
The Normalizer and Analysis agents handle correlation as a two-stage process. The normalizer cleans and aligns heterogeneous datasets into comparable numeric arrays; after mathematical computation of Pearson coefficients, the analysis agent interprets the relationships in context.
The Query Generator synthesizes the accumulated findings into targeted web search queries. The committed domain retrieval tool then calls Perplexity when configured and assembles knowledge items, with a local fallback when external retrieval is unavailable. The Content Analyzer remains a registered helper, but it is not invoked by the current domain-retrieval workflow step.
The Explanation Agent synthesizes all prior outputs -- temporal statistics, detected patterns, correlation interpretations, and domain knowledge -- into a structured narrative with key findings and confidence assessment.
The Validation Agent performs systematic fact-checking, verifying every claim in the narrative against the underlying data. Inconsistencies, unsupported claims, and missing caveats are flagged before the output leaves the engine.

Agent Profiles

Functional Summary

Agent	Responsibility	Value Proposition
Orchestrator	Legacy/planning agent available in the artifact loader	Supports planning/tool orchestration use cases outside the committed core workflow
Step Orchestrator	Determines which analysis steps to execute based on objective and data shape	Reduces execution time and API cost by eliminating unnecessary stages
Temporal	Computes time-series statistics and identifies trend directions	Provides the quantitative foundation all downstream agents depend on
Pattern	Detects behavioral signatures across metrics	Surfaces recurring cycles and warning indicators beyond statistical summaries
Normalizer	Cleans and aligns heterogeneous datasets for correlation	Ensures mathematical validity of cross-metric comparisons
Correlation Analysis	Interprets computed correlation coefficients	Translates statistical relationships into actionable observations
Domain Retrieval	Provides domain-knowledge synthesis when used directly	Available as a registered agent for retrieval-style consumers
Query Generator	Synthesizes analysis context into targeted search queries	Retrieves domain knowledge specific to the user's detected patterns
Content Analyzer	Registered helper for extracting insights from retrieved web content	Available to consumers, but not invoked by the committed workflow step
Explanation	Produces the user-facing analytical narrative	Synthesizes all findings into a coherent, contextual explanation
Validation	Fact-checks every claim against source data	Prevents hallucinated or inconsistent claims from reaching the user
Phrasing Helper	Rephrases existing user-facing text without changing meaning	Available to outer workflows; not a committed core workflow step

Technical Identifiers

Agent	Registry ID	Profile ID	Code
Orchestrator	`reasoning-engine-orchestrator-agent`	`reasoning-orchestrator`	`core/orchestrator.ts`
Step Orchestrator	`reasoning-engine-step-orchestrator-agent`	`reasoning-step-orchestrator`	`core/step-orchestrator.ts`
Temporal	`reasoning-engine-temporal-summary-agent`	`reasoning-temporal-summary`	`core/temporal.ts`
Pattern	`reasoning-engine-pattern-recognition-agent`	`reasoning-pattern-recognition`	`core/pattern.ts`
Normalizer	`reasoning-engine-correlation-normalizer-agent`	`correlation-tool-normalizer`	`correlation/normalizer.ts`
Correlation Analysis	`reasoning-engine-correlation-analysis-agent`	`correlation-tool-analysis`	`correlation/analysis.ts`
Domain Retrieval	`reasoning-engine-domain-retrieval-agent`	`reasoning-domain-retrieval`	`core/domain.ts`
Query Generator	`reasoning-engine-query-generator-agent`	`reasoning-query-generator`	`core/query-generator.ts`
Content Analyzer	`reasoning-engine-content-analyzer-agent`	`reasoning-content-analyzer`	`core/content-analyzer.ts`
Explanation	`reasoning-engine-explanation-agent`	`reasoning-explanation`	`core/explanation.ts`
Validation	`reasoning-engine-validation-agent`	`reasoning-validation`	`core/validation.ts`
Phrasing Helper	`reasoning-engine-phrasing-agent`	`reasoning-phrasing`	`core/phrasing.ts`

All agents reside under src/mastra/agents/reasoning-engine/ and share the REASONING-ENGINE- scope prefix through the common factory in correlation/common.ts.

Detailed Agent Documentation

Orchestrator

Execution planning and step selection

Temporal

Time-series analysis and trend detection

Pattern

Behavioral and semantic pattern recognition

Correlation

Normalizer + Analysis agent pair

Query Generator

Domain-specific search query synthesis

Content Analyzer

Contextual insight extraction from web content

Explanation

Narrative synthesis and confidence assessment

Validation

Claim verification and consistency checking

Design Principles

Dual-Mode Processing

Every analysis step supports two complementary processing modes:

Algorithmic processing executes first -- deterministic computation producing reproducible, verifiable results (statistical measures, correlation coefficients, trend detection).
Agent enhancement layers on top -- AI-powered interpretation that adds semantic understanding the algorithms cannot provide.

This architecture guarantees a baseline result even when an agent is unavailable or returns an error. The agents improve output quality, but the pipeline does not depend on them for structural integrity.

Fail-Safe Pipeline

When any agent fails or returns invalid output:

The pipeline continues with degraded results rather than terminating
The failed step is logged, and downstream agents operate on the available data
The validation agent flags the gap so output consumers are aware of reduced coverage

Database-Backed Configuration

Every agent's system prompt is stored in the Core.AgentProfiles table:

No redeployment required to modify agent behavior -- update the prompt via Admin tools or SQL
Version history is maintained -- every prompt change creates a new version with the previous version preserved for audit
Profile hash invalidation -- the agent cache rebuilds automatically when a prompt changes

// Runtime prompt loading
const profile = await agentProfilesService.getCurrent('reasoning-explanation');
if (profile) {
  systemPrompt = profile.systemPrompt ?? DEFAULT_PROMPT;
  llmConfig = { ...defaultConfig, ...profile.llmOverrides };
}

Per-Agent Model Selection

Each agent can target a different LLM deployment, enabling cost and quality optimization per analytical stage:

Agent Role	Recommended Model	Rationale
Temporal, Correlation, Step Orchestrator	GPT-4o-mini	Statistical and classification tasks; lower latency and cost
Pattern, Domain, Validation	GPT-4o	Benefits from stronger reasoning and knowledge
Explanation	GPT-4o	Narrative quality is user-facing; justifies the additional cost

Next Steps

Orchestration Pipeline

Workflow coordination and state management

Engine Overview

Full architecture, adapters, and configuration

Agent Prompt Overrides

Database-driven prompt configuration system

Database Schema

Persistence tables for tasks, steps, and payloads

Agent Architecture​

Collaboration Model​

Execution Flow​

Agent Profiles​

Functional Summary​

Technical Identifiers​

Detailed Agent Documentation​

Design Principles​

Dual-Mode Processing​

Fail-Safe Pipeline​

Database-Backed Configuration​

Per-Agent Model Selection​

Next Steps​