Phrasing

Overview

The Phrasing agent is an optional helper for outer workflows and application-specific presentation layers. It rephrases existing user-facing text for a friendlier, more conversational tone without changing facts or structure.

Agent file: src/mastra/agents/reasoning-engine/core/phrasing.ts

warning

The committed reasoningEngineWorkflow does not include a phrasing step. It ends at validation-agent, where optional output formatting can run. Consumers that need tone adjustment should call getPhrasingAgent() or applyPhrasing() from an outer workflow or application layer.

When It Runs

Only when a consumer explicitly invokes the helper. The core workflow schema accepts passthrough fields, but enablePhrasing is not consumed by the committed workflow definition.

What It Does

1. Takes the formattedOutput JSON
2. Sends to phrasing agent for tone adjustment
3. Returns the same JSON shape with text fields rephrased

Input

{
  formattedOutput: {
    summary: string,
    insights: string[],
    recommendations: string[]
  }
}

Output

Same structure as input, with rephrased text:

{
  formattedOutput: {
    summary: string,        // Friendlier tone
    insights: string[],     // More conversational
    recommendations: string[]
  }
}

Example Transformation

Before (Clinical Tone):

{
  "summary": "Analysis indicates elevated stress levels correlating with decreased sleep quality. Recommend implementing stress reduction protocols.",
  "insights": [
    "Stress levels exceed baseline by 64%",
    "Sleep duration inversely correlated with stress (r=-0.65)"
  ],
  "recommendations": [
    "Implement consistent sleep schedule",
    "Consider stress management techniques"
  ]
}

After (Friendly Tone):

{
  "summary": "Your stress has been a bit higher than usual lately, and it looks like it might be affecting your sleep. Here are some things that could help!",
  "insights": [
    "Your stress has been notably higher than your usual baseline",
    "When stress goes up, your sleep tends to suffer"
  ],
  "recommendations": [
    "Try going to bed and waking up at the same time each day",
    "Simple relaxation techniques might make a big difference"
  ]
}

Agent Implementation

const result = await applyPhrasing(formattedOutput);
if (result.success) {
  return result.data;
}
return formattedOutput;

Error Handling

Outer workflows should treat phrasing as non-blocking:

try {
  // Attempt rephrasing
} catch (err) {
  // Keep original formattedOutput unchanged
  return formattedOutput;
}

If phrasing fails for any reason:

• Original formattedOutput is preserved
• No error is added to workflow
• Workflow continues successfully

Use Cases

Use Case	Phrasing Enabled
API response to other systems	No
User-facing dashboard	Yes
Clinical reports	No
Mobile app notifications	Yes
Data export	No