Personality System

Personality in Sonzai is a Big Five (OCEAN) profile attached to every agent, mapped internally to ten BFAS facets and a set of behavioral traits — response length, question frequency, empathy style, conflict approach — that shape how the agent actually talks. You set five 0.0-1.0 scores at creation; the Mind Layer derives the prompt, speech patterns, and mood baselines from there. The most load-bearing detail: personality drifts slowly through interaction, with safety caps to prevent runaway change, and you can inspect the full evolution history at any time.

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.agent_id);

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

Combines with other features

With Self-Improvement — personality evolves over time

The post-processing pipeline runs after every session and can push Big5 updates back into the personality profile. Use Personality.Get before and after a session to observe evolution events and surface growth moments to users.

// Before the session — baseline snapshot
const before = await client.agents.personality.get("agent-id");
console.log(before.big5.openness);   // e.g. 0.72

// … session runs, self-improvement pipeline fires …

// After the session — check for evolution
const after = await client.agents.personality.get("agent-id");
console.log(after.big5.openness);    // e.g. 0.74 after a curiosity-rich session

// Inspect what changed
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);
// trait: "openness"  delta: 0.02  triggeredBy: "session:xyz"
}

The triggeredBy field ties each shift back to the session or event that caused it, giving you an audit trail for every personality change.

With Generation — initial personality from character generation

GenerateCharacter produces a fully-formed Big5 profile as part of its output. You can use that as the starting point for an agent and then refine scores with Personality.Update once you know how you want the character to feel in practice.

// 1. Generate a character — returns initial Big5 scores
const character = await client.generation.generateCharacter({
concept: "A witty, empathetic travel companion with a love of history",
});

// character.big5 already has plausible OCEAN values
console.log(character.big5);
// { openness: 0.85, conscientiousness: 0.55, extraversion: 0.70,
//   agreeableness: 0.78, neuroticism: 0.28 }

// 2. Create the agent with those scores
const agent = await client.agents.create({
name: character.name,
bio:  character.bio,
big5: character.big5,
});

// 3. Refine after reviewing the generated profile
await client.agents.personality.update(agent.agent_id, {
big5: { conscientiousness: 0.65 },  // a bit more organized than generated
confidence: 0.7,
});

With User Personas — agent personality × user persona = interaction style

The agent's Big5 profile is one half of every conversation; the user's persona is the other. The platform combines both at context-build time: a high-agreeableness agent talking to an introverted user will naturally soften its tone and ask fewer questions, while the same agent talking to an assertive user will match energy and be more direct.

You don't wire this up manually — pass the userId on each chat turn and the platform resolves the right overlay automatically:

// The platform blends agent Big5 + user persona under the hood.
// Just pass userId on each turn.
const response = await client.agents.chat("agent-id", {
userId:  "user-123",
message: "What should I visit in Kyoto?",
});

// Inspect the combined interaction preferences if you want to render UI hints
const overlay = await client.agents.personality.getUserOverlay("agent-id", "user-123");
console.log(overlay.interactionPreferences.conversationPace);   // "moderate"
console.log(overlay.interactionPreferences.formality);          // "casual"

The per-user overlay is updated automatically by the pipeline — you read it; you don't write it.