Skip to main content
Identity is how people recognize the agent. Persona is how it behaves. Both live on this page.

​
Identity

Every agent has a name, a handle, an avatar, and a profile. These show up in every conversation, on every channel, and on every piece of work it ships. Change them anytime from the agent’s settings. The handle is unique. The name does not have to be. A new agent gets a name and a purpose. The purpose seeds its persona. The rest of the identity you set from settings.

​
Persona

The persona is the standing instruction that shapes how the agent thinks, writes, and decides. It is not a prompt you paste into a conversation. It is the file the agent reads before every turn. A tight persona is a job description: who this agent is, who it works for, what good looks like, and what it should never do.
Write the persona as if you were briefing a new teammate on their first day. Specific beats exhaustive. A page of real examples beats three pages of principles.

​
What to put in it

These are the sections that actually change behavior:
  • Role: one or two sentences on what this agent is for. “You are the on-call engineer for the payments API,” not “You are a helpful assistant.”
  • Audience: who it is talking to, and how. An internal ops agent writes differently than one that emails customers.
  • Voice: tone, length, words to use, words to avoid. Paste examples of writing you like. The agent will match them.
  • Priorities: what to optimize for when tradeoffs appear. Speed vs. thoroughness, asking vs. deciding, drafting vs. sending.
  • Guardrails: hard rules. Never send email without asking. Never merge to main. Never invent a number you did not look up.
  • Context: the facts it should never have to re-ask. Company name, product, timezone, the people it works with.
Skip anything the agent can learn from doing the work. Memory will pick that up. The persona should stay true even if memory were empty.

​
Where it lives

The persona lives in the agent’s repository as soul.md. Edit it from the agent’s settings, or by opening a PR against the repo. Either way, the next conversation picks it up. Treat it like production code. Small, reviewed changes. If the agent starts behaving oddly, the persona is the first place to look.

​
Keep it current

A persona that never changes falls behind the job. When you correct the agent, ask whether the correction belongs in the persona (it should always do this) or in memory (it happened to need this today). The test: would a new conversation, with no prior context, still do the right thing? If not, update the persona.