Personality System

Create agents with distinct personalities and watch them evolve through interaction.

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.

Openness0.0 - 1.0Curiosity, creativity, openness to experience. High = imaginative, adventurous. Low = practical, conventional.

Conscientiousness0.0 - 1.0Organization, discipline, goal-orientation. High = methodical, reliable. Low = spontaneous, flexible.

Extraversion0.0 - 1.0Social energy, enthusiasm, assertiveness. High = outgoing, energetic. Low = reserved, reflective.

Agreeableness0.0 - 1.0Warmth, cooperation, empathy. High = caring, trusting. Low = direct, skeptical.

Neuroticism0.0 - 1.0Emotional 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.

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

Idempotent — passing the same agentId always upserts. Safe to call on every deploy. See Quickstart for the recommended UUID derivation pattern.

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:

Pace

slowmoderatefast

Derived from: Extraversion level

Formality

casualbalancedformal

Derived from: Conscientiousness level

Humor Style

dryplayfulwarm

Derived from: Openness + Agreeableness

Emotional Expression

reservedmoderateexpressive

Derived from: Neuroticism + Extraversion

Personality Evolution

Personalities evolve naturally through interactions:

Interaction Analysis

Emotional themes and patterns are analyzed after each conversation.

Micro-Shifts

Small adjustments are applied to relevant Big5 dimensions based on conversation content.

Breakthroughs

When cumulative shifts cross a threshold, a 'breakthrough' event fires — a significant personality change the agent becomes aware of.

Profile Regeneration

Personality prompt, speech patterns, and behavioral instructions are regenerated to reflect the evolved personality.

Per-User Personality Overlays

Adjust personality behavior for specific users without affecting the base agent profile.

// Apply a per-user overlay (e.g. from assessment results)
await client.agents.personality.setUserOverlay("agent-id", "user-123", {
  big5: {
    extraversion: 0.55,  // agent speaks more reservedly with this user
  },
  confidence: 0.6,
});

← MCP Integration Memory & Context→