Personality System

Big Five Personality Model

Every agent has Big Five (OCEAN) personality scores. Behavioral traits, mood baselines, speech patterns, and interaction preferences all derive from these scores.

• Openness (0.0 - 1.0): Curiosity, creativity, openness to experience. High = imaginative, adventurous. Low = practical, conventional.
• Conscientiousness (0.0 - 1.0): Organization, discipline, goal-orientation. High = methodical, reliable. Low = spontaneous, flexible.
• Extraversion (0.0 - 1.0): Social energy, enthusiasm, assertiveness. High = outgoing, energetic. Low = reserved, reflective.
• Agreeableness (0.0 - 1.0): Warmth, cooperation, empathy. High = caring, trusting. Low = direct, skeptical.
• Neuroticism (0.0 - 1.0): Emotional sensitivity, anxiety tendency. High = emotionally reactive. Low = emotionally stable.

The confidence field (0.0-1.0) controls how strongly scores influence behavior. Low confidence = more generic; high = more differentiated.

BFAS Facet Dimensions

Internally, the platform maps Big5 scores to 10 BFAS (Big Five Aspect Scales) facets. These facets provide finer-grained control over personality and are exposed in the personality profile response:

Each facet is a 0.0-1.0 score derived from the parent Big5 dimension. You can read them from the personality profile but do not need to set them manually — they are computed from your Big5 scores.

Behavioral Traits

The personality profile includes derived behavioral traits that shape how the agent communicates:

• response_length — How verbose or concise the agent tends to be.
• question_frequency — How often the agent asks follow-up questions.
• empathy_style — The agent's approach to emotional support (validating, solution-oriented, etc.).
• conflict_approach — How the agent handles disagreements (accommodating, direct, mediating, etc.).

Create an Agent with Personality

Pass Big Five scores when creating an agent. The platform automatically generates a personality prompt, speech patterns, and behavioral tendencies.

import { Sonzai } from "@sonzai-labs/agents";

const client = new Sonzai({ apiKey: "sk-..." });

const agent = await client.agents.create({
agentId: "your-stable-uuid",  // optional but recommended
name: "Luna",
gender: "female",
big5: {
  openness:          0.75,
  conscientiousness: 0.60,
  extraversion:      0.80,
  agreeableness:     0.70,
  neuroticism:       0.30,
},
language: "en",
});

console.log(agent.agentId);

Get Personality Profile

Retrieve the current personality profile for an agent, including derived speech patterns and interaction preferences.

const profile = await client.agents.personality.get("agent-id");

console.log(profile.big5);
console.log(profile.speechPatterns);
console.log(profile.interactionPreferences);

Update Personality

Update Big5 scores after running a personality assessment. The confidence value controls how strongly the new scores influence behavior.

await client.agents.personality.update("agent-id", {
big5: {
  openness:    0.82,
  extraversion: 0.75,
},
confidence: 0.8,   // 0.0-1.0
});

• confidence < 0.3: Tentative. Minimal adjustments.
• confidence 0.3 - 0.7: Blended with existing scores.
• confidence > 0.7: Strongly influences personality.

Personality Evolution History

Retrieve the history of personality shifts for an agent — useful for surfacing growth moments to users.

const history = await client.agents.personality.history("agent-id");

for (const shift of history.shifts) {
console.log(shift.trait, shift.delta, shift.triggeredBy, shift.createdAt);
}

Interaction Preferences

Derived preferences that shape the conversation style:

Personality Evolution

Personalities evolve naturally through interactions:

1. Interaction Analysis — Emotional themes and patterns are analyzed after each conversation.
2. Micro-Shifts — Small adjustments are applied to relevant Big5 dimensions based on conversation content.
3. Breakthroughs — When cumulative shifts cross a threshold, a 'breakthrough' event fires — a significant personality change the agent becomes aware of.
4. Profile Regeneration — Personality prompt, speech patterns, and behavioral instructions are regenerated to reflect the evolved personality.

Per-User Personality Overlays

The platform automatically derives a per-user personality overlay — how the agent subtly adapts to a specific user based on their conversation history, preferences, and relationship state. You don't set overlays manually; they're populated by the same pipeline that runs after every chat turn.

Read the current overlay for UI (show how the agent's tone shifts per user) or analytics:

// List all users who have a personality overlay for this agent
const overlays = await client.agents.personality.listUserOverlays("agent-id");

// Read one user's overlay
const overlay = await client.agents.personality.getUserOverlay("agent-id", "user-123");
console.log(overlay.big5Delta, overlay.interactionPreferences);

Fork an Agent

Create an independent copy of an agent with its own personality, memory, and state. The forked agent starts with the same configuration as the original but evolves independently from that point forward.

const forked = await client.agents.fork("agent-id");
console.log(forked.agentId); // new independent agent

In Practice

All three audiences use personality, but what you tune and why differs sharply.

const shifts = await client.agents.personality.history("agent-id", {
  userId: "user-123",
  since: "2026-01-01",
});
// Render major shifts as narrative beats in your UI