Quickstart

Start with one persona and climb from there: talk to them, put personas together in a network, give them a world, and set it in motion. Every step works in Studio and through the API.

ℹ

What you'll do

Describe a persona, talk to them, gather a few into a network, build a world and bring one into it. Every persona response is generated through real-time inference, never cached or pre-computed.

1. Sign in

Create a free account with Google, GitHub, or a sign-in link sent to your email. There is no separate registration step and no card.

On your first visit Studio offers a guided tour, from one persona to a world. On a wider screen you can take it again at any time from the tour button.

💡

Demo access

If password-gated access is enabled, you'll be prompted for a site password before reaching the sign-in page.

2. Describe one persona

In Studio, open New persona and describe one in a sentence. They arrive with traits, a backstory, memories and a voice. A persona needs no world: it lives on its own until you give it one.

Or through the API

Go to Settings → API Keys and click Create API Key. Give it a name and copy the key. You'll only see it once. Then install an SDK.

Python

pip install ensoul

TypeScript

npm install @ensoul-ai/sdk

⚠

Python requires 3.11 or newer

The Python SDK requires Python 3.11+. On Python 3.9 or 3.10, pip install ensoul fails with no compatible version. Check your version with python --version and upgrade if needed.

Make your first call

Create a persona with no world, send it one message as one of your end users, and end the conversation. user_id is your own id for the person talking.

# pip install ensoul
from ensoul import Ensoul

client = Ensoul(api_key="YOUR_API_KEY")

# A persona needs no world. This one stands alone.
persona = client.personas.create(name="Ada")

# user_id is your own id for the person talking.
# Each end user gets their own conversations with the persona.
reply = client.chat.send(
    persona.id,
    "Hi! Who are you?",
    user_id="YOUR_END_USER_ID",
)
print(reply.response)

# End the conversation when the person is done.
client.chat.end_conversation(
    persona.id,
    reply.conversation_id,
    user_id="YOUR_END_USER_ID",
)

💡

Environment variables

Set ENSOUL_API_KEY and ENSOUL_BASE_URL to skip passing them in code. The base URL defaults to https://api.ensoul-ai.com.

3. Talk to them

Open the persona and choose the Talk tab, or go to Talk and pick them. Ask about their preferences, their past, or how they'd handle a situation, and notice how the answer follows from who they are.

The Embed tab gives the persona a share page and the snippet for putting them in your own product.

POST /v1/personas/{persona_id}/chat: one of your end users talking to one persona
POST /v1/personas/{persona_id}/conversations/{conversation_id}/end: end that conversation

💡

Memory in action

As you talk, the persona builds memories from the conversation. Follow-up questions will reference earlier context.

4. Put personas in a network

A network is a named set of personas who know each other. In Studio, open Networks, create one, and use Add personas. The network page draws everyone and how they are connected, and its Talk button opens one conversation with the whole set.

POST /v1/networks: create a network
POST /v1/networks/{network_id}/members: add personas to it
GET /v1/networks/{network_id}/graph: the personas and the ties between them

5. Give them a world

A world has rules, tiers and archetypes, and a population. Open Worlds and click New World. The wizard can suggest the rules, tiers and archetypes from a description, or you can set everything by hand.

On the world's Personas page, Bring a persona in moves one you already made into the world, and they keep the life they already had. Generate personas grows a population from the world's archetypes and tiers. In Talk, choosing a world as the target lets you ask a world: one question to many of its personas, with the answers gathered together.

POST /v1/personas/{persona_id}/place-in-world: bring a persona into a world
POST /v1/personas/{persona_id}/remove-from-world: take them out again, with their memories kept
GET /v1/personas/{persona_id}/worlds: every world a persona has lived in
POST /v1/domains/{domain_id}/personas/batch/stream: generate a population
POST /v1/aggregate/stream: ask a world

The API calls a world a domain, so world routes and fields keep that name.

6. Set it in motion

A simulation lets the personas in a world or a network talk to each other over time, and you watch what they do. Start one from Simulations, or from a network's Simulate button. Simulations are a paid capability.

POST /v1/simulations: create a simulation, with its personas from a world (domain_id) or a network (network_id)
POST /v1/simulations/{simulation_id}/start: start it

What's Next?

You've climbed the whole ladder. Here's where to go from here:

Use Cases

See how Ensoul can be applied:

Observability : measure and track persona personality over time
Gaming : characters with consistent, evolving personalities
Corporate Training : realistic role-playing scenarios
Healthcare : patient simulations for medical education