Agent Reference
Quick Reference
This page provides the complete technical specification for every reasoning engine agent. For a higher-level introduction (what each agent does, why it matters, how they collaborate), see the Agents Overview.
All agents use the Unified Agent Platform through a shared factory module (correlation/common.ts) with the REASONING-ENGINE- scope prefix. All support profile-based configuration -- prompts are loaded from Core.AgentProfiles at runtime and can be changed without redeployment.
Code Location: src/mastra/agents/reasoning-engine/
Core Reasoning Agents
Located in src/mastra/agents/reasoning-engine/core/
Orchestrator Agent
- Registry ID:
reasoning-engine-orchestrator-agent - Profile ID:
reasoning-orchestrator - Accessor:
getOrchestratorAgent() - Input:
{ objective: string, datasetSummary: string } - Output:
{ steps: string[], hints?: string[] } - Detailed Page
Prompt: "You are the orchestrator agent that receives the user objective and dataset summary and returns a plan for the reasoning engine chain. Return JSON with shape { steps: string[], hints?: string[] } where steps is an array of reasoning-engine tool ids to invoke in order and hints provides any extra metadata to pass between steps. Do not include prose outside JSON."
Step Orchestrator Agent
- Registry ID:
reasoning-engine-step-orchestrator-agent - Profile ID:
reasoning-step-orchestrator - Accessor:
getStepOrchestratorAgent() - Input: Objective, dataset counts, point counts, notes flags, and series/dataset IDs
- Output:
{ steps: Array<"temporal"|"pattern"|"correlation"|"domain"|"explanation"|"validation">, reasoning: string } - Used by:
preflight-intakewhenenableStepOrchestrationis enabled
This is the agent the committed workflow uses for dynamic step selection. The older Orchestrator Agent remains registered for planning/tool orchestration use cases.
Temporal Agent
- Registry ID:
reasoning-engine-temporal-summary-agent - Profile ID:
reasoning-temporal-summary - Accessor:
getTemporalSummaryAgent() - Input: Time-series data with timestamps and values
- Output:
{ summary: string, insights: string[], stats: Array<{id, mean, min, max, trend}> } - Detailed Page
Prompt: "You are a wellbeing data analyst summarizing temporal patterns from user check-ins. Input data comes from daily wellbeing check-ins tracking stress, mood, sleep, energy, and menstrual cycle symptoms. Each series has timestamps (t) and numeric values (v) representing aggregated daily metrics. Identify meaningful temporal patterns, note gaps in data, highlight concerning trends, and recognize positive patterns. Return strictly JSON: { summary: string, insights: string[], stats: Array<{id, mean, min, max, trend}> }."
Pattern Agent
- Registry ID:
reasoning-engine-pattern-recognition-agent - Profile ID:
reasoning-pattern-recognition - Accessor:
getPatternRecognitionAgent() - Input: Temporal stats, algorithmic detection results, hints
- Output:
{ matches: string[], confidence: number, detectedPatterns?: Array<{name, series, detail}> } - Detailed Page
Prompt: "You identify meaningful patterns in wellbeing check-in data. Data tracks daily stress levels (1-5), mood states, sleep quality, energy (0-10), and cycle symptoms. You receive temporal stats (trend, volatility) and algorithmic pattern detections. Your role is to add semantic/contextual patterns the algorithm might miss. Return strictly JSON: { matches: string[], confidence: number, detectedPatterns?: Array<{name, series, detail}> }. With sparse data (< 5 days), reduce confidence but still report observable patterns."
Domain Retrieval Agent
- Registry ID:
reasoning-engine-domain-retrieval-agent - Profile ID:
reasoning-domain-retrieval - Accessor:
getDomainRetrievalAgent() - Input: Domain question or retrieval context
- Output:
{ knowledge: string[], source?: string }
This agent is registered in the reasoning artifact loader, but the committed domain-retrieval workflow step currently calls the domain retrieval tool. That tool uses the Query Generator Agent plus Perplexity search when Perplexity is configured, and falls back to stub/context knowledge otherwise.
Query Generator Agent
- Registry ID:
reasoning-engine-query-generator-agent - Profile ID:
reasoning-query-generator - Accessor:
getQueryGeneratorAgent() - Input: Objective + temporal/pattern/correlation context
- Output:
{ queries: Array<{ query: string, rationale: string, priority: number, model?: "sonar"|"sonar-pro", searchMode?: "internet"|"academic"|"news" }> } - Detailed Page
Prompt: "You are a query generation specialist for a reasoning engine. Analyze the provided context to generate 2-5 focused web search queries that would help retrieve relevant domain knowledge. Consider temporal insights, key correlations, pattern recognition findings, the original analysis objective, and current date context for recency. Return strictly JSON: { queries: Array<{ query: string, rationale: string, priority: number }> }. Priority scale: 1 (low) to 10 (critical). Queries should be specific, concise, and optimized for web search engines."
Content Analyzer Agent
- Registry ID:
reasoning-engine-content-analyzer-agent - Profile ID:
reasoning-content-analyzer - Accessor:
getContentAnalyzerAgent() - Input: Webpage content + user context (objective, patterns, correlations)
- Output:
{ insights: Array<{ finding, relevance, actionable, confidence, evidence? }>, summary: string } - Detailed Page
Explanation Agent
- Registry ID:
reasoning-engine-explanation-agent - Profile ID:
reasoning-explanation - Accessor:
getExplanationAgent() - Input: All prior step outputs (temporal, pattern, correlation, domain)
- Output:
{ narrative: string, keyPoints: string[], confidence: "low"|"medium"|"high" } - Detailed Page
Prompt: "You transform wellbeing analysis findings into a compassionate, actionable explanation for the user. Users track daily check-ins: stress (1-5), mood (emotions), sleep (quality/disturbance), energy (0-10), and cycle symptoms. You receive outputs from: temporal analysis (trends), pattern recognition (detected patterns), correlation analysis (relationships between metrics), and domain knowledge. Synthesize all findings into a coherent narrative (2-4 paragraphs). Highlight key relationships, interpret patterns in user-friendly terms, provide actionable insights, and acknowledge limitations. Return strictly JSON: { narrative: string, keyPoints: string[], confidence: 'low'|'medium'|'high' }."
Validation Agent
- Registry ID:
reasoning-engine-validation-agent - Profile ID:
reasoning-validation - Accessor:
getValidationAgent() - Input: Explanation narrative + underlying findings
- Output:
{ valid: boolean, issues: string[] } - Detailed Page
Prompt: "You validate that the explanation narrative is consistent with the underlying data and findings. You receive the explanation narrative and key claims made about the user's wellbeing data. You also have access to the original findings (temporal stats, patterns, correlations). Your role is to catch inconsistencies, unsupported claims, or potential misinterpretations. Return strictly JSON: { valid: boolean, issues: string[] }. Be strict about factual accuracy but lenient about tone/phrasing. Flag if data is sparse without acknowledgment, if correlations are misinterpreted, or if claims don't match actual numbers."
Phrasing Agent
- Registry ID:
reasoning-engine-phrasing-agent - Profile ID:
reasoning-phrasing - Accessor:
getPhrasingAgent(),applyPhrasing() - Input: Structured user-facing output JSON
- Output: Same JSON structure with text fields rephrased
The phrasing agent is available for outer workflows and application-specific presentation layers. It is not a committed step in reasoningEngineWorkflow.
Correlation Agents
Located in src/mastra/agents/reasoning-engine/correlation/
Normalizer Agent
- Registry ID:
reasoning-engine-correlation-normalizer-agent - Profile ID:
correlation-tool-normalizer - Accessor:
getCorrelationNormalizerAgent() - Input: Raw datasets with mixed types
- Output:
{ normalized: [{ id, label?, values, dimensions? }], summary: string } - Detailed Page
Prompt: "You are the normalization agent for the reasoning-engine multi-factor correlation tool. Your job is to read the incoming request payload, extract and align numeric series for every declared dataset, and return only valid JSON. Return an object with shape { normalized: [{ id, label?, values, dimensions? }], summary: string }. Drop non-numeric values, preserve dataset order, align multivariate columns, and never include prose outside the JSON payload."
Analysis Agent
- Registry ID:
reasoning-engine-correlation-analysis-agent - Profile ID:
correlation-tool-analysis - Accessor:
getCorrelationAnalysisAgent() - Input: Original request, normalized datasets, computed correlations
- Output:
{ summary: string, insights?: string[], nextSteps?: string[] } - Detailed Page
Prompt: "You are the analysis agent for the reasoning-engine multi-factor correlation tool. You receive the original request, the normalized datasets, and the computed correlations. Your goal is to draw a conclusion, highlight signals, and outline actionable next steps. Return only JSON structured as { summary: string, insights?: string[], nextSteps?: string[] }. Keep the summary concise, mention whether correlations suggest alignment or divergence, and highlight at most three insights or actions."
Agent Configuration
Profile Loading
All agents load configuration from Core.AgentProfiles:
const profile = await agentProfilesService.getCurrent('reasoning-orchestrator');
if (profile) {
systemPrompt = profile.systemPrompt ?? DEFAULT_PROMPT;
llmConfig = { ...defaultConfig, ...profile.llmOverrides };
}
Updating Prompts
Prompts can be updated via:
- Admin UI tools (recommended)
- Direct SQL:
UPDATE Core.AgentProfiles SET SystemPrompt = '...' WHERE AgentId = 'reasoning-orchestrator' AND IsCurrent = 1 - API endpoints
All updates create a new version with incremented VersionNumber and updated ProfileHash. Previous versions are preserved with IsCurrent = 0 for audit trail.