Emotions & Mood
Each agent maintains a living mood state that shifts with conversations, application events, and time.
Mood Dimensions
Each agent-user pair has a mood state with four dimensions on a 0-100 scale:
Mood Labels
The overall mood label is derived from the combined dimensions:
What Shifts Mood
1. Chat Interactions
The platform detects emotional themes in conversations and adjusts mood automatically. Common themes:
▶View all emotional themes
joy_bloominghappy, excited, wonderfulHappiness ↑, Energy ↑creative_sparkcreate, imagine, inspireEnergy ↑, Happiness ↑brave_stepscourage, try, challengeEnergy ↑, Calmness ↑growth_journeylearn, grow, improveHappiness ↑, Energy ↑seeking_connectionfriend, together, shareAffection ↑, Happiness ↑feeling_overwhelmedstressed, anxious, worriedCalmness ↓, Energy ↓tender_heartlove, care, missAffection ↑, Happiness ↑facing_fearsscared, afraid, nervousCalmness ↓, Affection ↑2. Application Events
Pass application context and the platform updates mood automatically.
▶Application event mood effects
3. Time-Based Decay
Mood naturally drifts back toward the agent's personality-derived baseline over time. No action needed — this happens automatically.
Get Mood
Read the current mood state for an agent-user pair.
import { Sonzai } from "@sonzai-labs/agents";
const client = new Sonzai({ apiKey: "sk-..." });
const mood = await client.agents.getMood("agent-id", {
userId: "user-123",
});
console.log(mood.label); // "Content"
console.log(mood.happiness); // 72
console.log(mood.energy); // 65
console.log(mood.calmness); // 80
console.log(mood.affection); // 68Mood History
Retrieve the mood history for a user-agent pair over time.
const history = await client.agents.moodHistory("agent-id", {
userId: "user-123",
from: "2026-01-01",
to: "2026-03-31",
});
for (const snapshot of history.snapshots) {
console.log(snapshot.timestamp, snapshot.label, snapshot.happiness);
}Mood Aggregate
Get aggregated mood statistics across all users for an agent.
const agg = await client.agents.moodAggregate("agent-id");
console.log(agg.averageHappiness);
console.log(agg.averageEnergy);
console.log(agg.labelDistribution);How Mood Affects Responses
Mood state is automatically included in the AI context. The agent adjusts tone accordingly: