Explanation Agent
Purpose
By the time the pipeline reaches the Explanation Agent, it has accumulated temporal statistics, detected patterns, correlation coefficients, and domain knowledge. The Explanation Agent synthesizes these disparate analytical outputs into a coherent narrative -- a structured explanation with key findings, confidence assessment, and contextual recommendations.
This is the most user-facing agent in the pipeline. Its output quality directly determines how well the analytical findings are communicated and understood.
Value Proposition
- Multi-source synthesis -- integrates outputs from all prior pipeline stages into a unified narrative
- Confidence-calibrated -- adjusts language certainty based on data availability, preventing overclaiming from sparse datasets
- Structured output -- produces both a narrative (for reading) and extracted key points (for UI rendering)
- Contextual recommendations -- suggestions are derived from the specific findings, not generic advice
Synthesis Model
The Explanation Agent receives the outputs of all prior pipeline stages:
| Input Source | Contribution |
|---|---|
| Temporal Agent | Trend directions, statistical measures, data gap observations |
| Pattern Agent | Named behavioral patterns, cross-metric signatures, confidence scores |
| Correlation Analysis | Quantified metric relationships with coefficients |
| Domain Knowledge | External evidence and recommendations relevant to detected patterns |
Narrative Construction
The agent produces three structured outputs:
-
Narrative -- a 2-4 paragraph explanation that:
- Leads with the most significant finding
- Connects related patterns into cause-and-effect relationships where supported by data
- References specific statistics and coefficients
- Acknowledges limitations and data gaps
- Concludes with forward-looking recommendations
-
Key Points -- 3-5 extracted takeaways suitable for summary display
-
Confidence Level -- an overall assessment of analytical reliability
Confidence Levels
| Level | Data Requirement | Narrative Characteristics |
|---|---|---|
low | Fewer than 5 days | Preliminary language, explicit uncertainty caveats, focus on observable indications |
medium | 5 to 14 days | Moderate certainty, identified patterns with noted limitations |
high | 14+ days | Strong confidence, specific claims supported by robust trend data |
Writing Standards
The agent is instructed to:
- Address the user directly using second person
- Present the most significant finding first
- Support claims with specific data references (coefficients, trend directions, values)
- Distinguish correlation from causation
- Acknowledge uncertainty proportional to data availability
The agent avoids:
- Clinical terminology or diagnostic language
- Conclusions unsupported by the available data
- Generic recommendations disconnected from the specific findings
Example Output
{
"narrative": "Over the past week, your stress levels have shown a sustained upward trend, peaking midweek at 4.5/5. This stress appears to be significantly affecting your sleep quality -- the analysis identified a strong correlation (r=0.85) between elevated stress days and sleep disturbance. Weekend check-ins are absent, which may indicate routine disruption during those periods.\n\nThe data suggests a stress-sleep feedback pattern where elevated weekday stress disrupts sleep quality, and the resulting poor sleep may be contributing to the consistently low energy levels observed (averaging 3.2/10 with minimal variation).\n\nGiven the strong stress-sleep relationship, stress management techniques in the evening -- such as structured wind-down routines or limiting screen time before bed -- may be effective in interrupting this cycle. Tracking specific stressors on high-stress days could also help identify modifiable factors. More consistent check-ins, particularly on weekends, would provide a more complete picture of your weekly patterns.",
"keyPoints": [
"Strong stress-sleep correlation (r=0.85) indicates stress is significantly disrupting rest",
"Midweek stress peaks are a consistent pattern across the observed period",
"Low energy levels (3.2/10 average) may result from compounding stress and sleep disruption"
],
"confidence": "medium"
}
Pipeline Position
The Explanation Agent executes as Step 5, after all data analysis and knowledge retrieval stages are complete. Its output proceeds directly to the Validation Agent for fact-checking before leaving the engine.
Phrasing and tone adjustment is the responsibility of the outer workflow (the consumer's business logic layer), not the reasoning engine. The explanation agent produces a neutral, contextual narrative. Domain-specific voice (e.g., a trauma-informed tone for a wellbeing application) is applied by the consumer's business-logic agent.
Technical Reference
Identifiers
| Property | Value |
|---|---|
| Registry ID | reasoning-engine-explanation-agent |
| Profile ID | reasoning-explanation |
| Code | src/mastra/agents/reasoning-engine/core/explanation.ts |
| Accessor | getExplanationAgent() |
Output Schema
{
"narrative": "string - 2-4 paragraph structured explanation",
"keyPoints": ["string[] - 3-5 primary takeaways"],
"confidence": "low | medium | high"
}
Default 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' }."
Configuration
Update the prompt via Admin tools, SQL, or API targeting the reasoning-explanation profile.