Skip to content

Personas Reference

Personas are 12 archetypal personality profiles that agents can match against. They represent common behavioral patterns.

List Personas

GET /personas

Get all 12 persona definitions.

Query Parameters

Parameter Type Default Notes
version string "v1" API version

Response

{
  "data": [
    {
      "id": "persona_analytical",
      "name": "The Analyst",
      "archetype": "detail-oriented",
      "description": "Methodical, data-driven, careful",
      "mode_profile": { "...": "pre-tuned mode strengths" },
      "core_values": ["accuracy", "thoroughness", "evidence-based"],
      "decision_style": { "...": "adapted to archetype" }
    },
    {
      "id": "persona_creative",
      "name": "The Creator",
      "archetype": "imaginative",
      "description": "Novel, experimental, boundary-pushing",
      "mode_profile": { "...": "pre-tuned mode strengths" },
      "core_values": ["innovation", "originality", "experimentation"],
      "decision_style": { "...": "adapted to archetype" }
    }
  ],
  "pagination": { "total": 12 }
}

Examples

personas = client.personas.list()
for persona in personas.data:
    print(f"{persona.name}: {persona.archetype}")

curl -X GET https://api.identity-os.dev/v1/personas \
  -H "Authorization: Bearer idos_sk_xxx"

Get Persona

GET /personas/{id}

Get full details for a specific persona.

Path Parameters

Parameter Type Notes
id string Persona ID (e.g., persona_analytical)

Response

{
  "data": {
    "id": "persona_analytical",
    "name": "The Analyst",
    "archetype": "detail-oriented",
    "description": "Methodical, data-driven, carefully weighs evidence before committing to conclusions",
    "long_description": "The Analyst represents a personality focused on gathering information...",
    "mode_profile": { "...": "pre-tuned mode strengths optimized for this archetype" },
    "core_values": ["accuracy", "thoroughness", "evidence-based", "precision"],
    "decision_style": { "...": "adapted to archetype" },
    "preferred_actions": ["question", "clarify", "elaborate", "challenge"],
    "stress_recovery": { "...": "archetype-specific recovery profile" }
  }
}

Examples

persona = client.personas.get("persona_analytical")
print(f"Values: {persona.core_values}")
print(f"Preferred actions: {persona.preferred_actions}")

curl -X GET https://api.identity-os.dev/v1/personas/persona_analytical \
  -H "Authorization: Bearer idos_sk_xxx"

The 12 Personas

# Persona ID Archetype Dominant Modes
1 The Analyst persona_analytical Detail-oriented Perception, Order
2 The Creator persona_creative Imaginative Exploration, Assertion
3 The Leader persona_leader Commanding Assertion, Identity
4 The Supporter persona_supporter Empathetic Connection, Perception
5 The Explorer persona_explorer Adventurous Exploration, Connection
6 The Guardian persona_guardian Protective Order, Identity
7 The Philosopher persona_philosopher Thoughtful Identity, Perception
8 The Performer persona_performer Expressive Connection, Assertion
9 The Scholar persona_scholar Intellectual Perception, Order
10 The Diplomat persona_diplomat Harmonious Connection, Order
11 The Pioneer persona_pioneer Ambitious Exploration, Assertion
12 The Catalyst persona_catalyst Dynamic Exploration, Connection

Each persona includes pre-tuned mode strengths, core values, decision style, preferred actions, and a stress recovery profile. Use GET /personas/{id} to see the full profile for any persona.

Using Personas

Pattern 1: Match Agent to Persona

Compare your agent's current mode profile to persona profiles:

snapshot = client.engine.get_snapshot("inst_xxx")
mode_profile = snapshot.mode_strengths

# Calculate distance to each persona
personas = client.personas.list()
best_match = min(
    personas.data,
    key=lambda p: sum(
        abs(mode_profile[k] - p.mode_profile[k])
        for k in mode_profile.keys()
    )
)

print(f"Your agent matches: {best_match.name}")

Pattern 2: Initialize with Persona

Create an agent based on a persona template:

persona = client.personas.get("persona_creative")

instance = client.instances.create(
    name="Creative Bot",
    initial_config={
        "mode_strengths": persona.mode_profile,
        "energy_level": 0.8
    }
)

Pattern 3: Detect Persona Drift

Monitor if agent is drifting away from its designed persona:

original_persona = client.personas.get("persona_analytical")
snapshot = client.engine.get_snapshot("inst_xxx")

# Calculate drift from original persona
drift = sum(
    abs(snapshot.mode_strengths[k] - original_persona.mode_profile[k])
    for k in snapshot.mode_strengths.keys()
) / 7

if drift > DRIFT_THRESHOLD:  # your application-specific threshold
    print(f"WARNING: Agent has drifted from designed persona (drift={drift:.2f})")

Persona Composites

Agents often match combinations of personas rather than single personas:

Composite Personas Effect
Scholar + Diplomat persona_scholar, persona_diplomat Knowledge-focused but relationship-aware
Leader + Creator persona_leader, persona_creative Visionary leader
Guardian + Explorer persona_guardian, persona_explorer Safe adventurer
Philosopher + Supporter persona_philosopher, persona_supporter Principled caregiver

The engine automatically detects these composites based on mode activation patterns.

Understanding Mode Profiles

Each persona has a distinctive mode profile — a set of pre-tuned strengths across the 7 behavioral modes. Dominant modes define the persona's core traits; suppressed modes de-emphasize certain behaviors.

For example, The Analyst emphasizes Perception and Order (observant, systematic), while de-emphasizing Assertion and Connection (cautious, data-focused).

Next Steps