User Personas

User Personas are templates your tenant defines for the kinds of users the agent will meet. When a persona is attached to a user — during priming or via conversation metadata — the agent reads it alongside its own personality and adjusts tone, vocabulary, and pace accordingly. A "skeptical beginner" gets gentler explanations and more confirmations; a "power user" gets concise, direct answers without hand-holding.

What you can build with it

• Experience tiers — beginner / intermediate / expert personas with progressively faster pace and denser vocabulary
• Customer segments — trial / paying / enterprise personas with calibrated support formality and escalation thresholds
• Game character archetypes — personas for NPCs or dynamic character switching mid-conversation
• Onboarding flows — a first-time-user persona that gradually fades as the user completes milestones
• Testing + evaluation — define canonical personas for each scenario so you can run repeatable agent evals against a known user type

Quickstart

Create a persona, then fetch the full list.

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

const client = new Sonzai({ apiKey: process.env.SONZAI_API_KEY! });

// Create a persona
const persona = await client.userPersonas.create({
name: "Skeptical Beginner",
description: "First-time user who questions recommendations and needs reassurance.",
style: "Use plain language. Confirm before any irreversible action. Offer brief rationale for each suggestion.",
});

console.log(persona.persona_id);

// List all tenant personas
const { personas } = await client.userPersonas.list();
personas.forEach(p => console.log(p.name, p.is_default));

Core concepts

• Tenant-scoped — personas belong to your tenant, not to a specific agent or user. Every agent in your tenant can reference the same persona library.
• Template, not assignment — creating a persona does not apply it to anyone. You attach it during priming or pass it as metadata when starting a conversation.
• Default persona — one persona per tenant can be marked is_default. The agent falls back to it when no persona is explicitly attached to a user.
• Style field — an optional free-form directive layered on top of the agent's base personality prompt. Write it as a concise instruction set: tone, vocabulary level, confirmation habits, pacing.

Full API

UserPersona fields

Combines with other features

With Priming — attach a persona during user setup

Pass a persona reference when priming a new user so the agent adapts from the very first turn, before any conversation history exists.

const job = await client.agents.priming.primeUser("agent_abc", "user_123", {
display_name: "Jordan Lee",
metadata: {
  persona_id: persona.persona_id,   // attach persona at priming time
  timezone: "America/New_York",
},
content: [
  { type: "text", body: "Jordan is a first-time user migrating from a competitor product." },
],
source: "onboarding",
});

With Personality — agent personality × user persona = interaction style

These two concepts are complementary and operate at different levels:

• Personality is the agent's traits — Big Five scores, speech patterns, emotional range. It is fixed per agent (and evolves slowly through interactions).
• User Persona is the user's type — a template describing what kind of person the agent is talking to. It shapes how the agent expresses its personality in this specific conversation.

Think of it as a matrix: a high-agreeableness agent talking to a "power user" persona stays warm but drops the hand-holding; talking to a "skeptical beginner" persona it adds more reassurance and simpler vocabulary — without the underlying personality changing.

With Evaluation — test against canonical personas

Define a persona for each user archetype you care about, then run eval scenarios scoped to that persona. This gives you repeatable, deterministic test conditions.

// Define an eval scenario for the "Skeptical Beginner" persona
const result = await client.agents.evaluate("agent-id", {
templateId: "onboarding-rubric",
messages: [
  { role: "user",      content: "I'm not sure I trust this — what happens to my data?" },
  { role: "assistant", content: "That's a fair question. Your data stays on our servers..." },
],
// Pass persona context so scoring reflects expected beginner-friendly tone
metadata: { persona_id: persona.persona_id },
});

console.log(result.score, result.feedback);

Tutorials

• Tutorial: Custom States — see how metadata fields like persona_id travel through the conversation lifecycle alongside custom state.

Next steps

• Personality
• Priming
• Evaluation