Skip to main content
The persona is the agent’s system prompt: the text the model reads before every conversation that says who the agent is, what it does, and how it speaks. It is the persona field on LuaAgent, one of the two required fields, and it is the single biggest lever on how the agent behaves, because skills add tools but the persona decides how and when they are used.

​
How the persona reaches the model

On every turn Lua assembles the prompt from the persona, the context of each active skill, and any knowledge the agent’s features retrieve. The persona comes first and applies everywhere: every channel, every skill, every tool call. persona takes a string or an object with base, voice, and text. The object form renders base always, then appends voice on a voice call or text on a text channel. A missing key renders nothing, so { base, voice } on a text channel is base alone; there is no fallback from one channel’s key to the other’s. An object with none of the three keys throws when the agent is constructed.
src/index.ts
Keep the string form until a channel needs different core rules. The platform already adapts formatting to the channel; the object form is for rules that only make sense on one side, such as reading details back on a call or using formatting components in text.

​
Writing a persona that holds up

A useful persona answers four questions in order: who the agent is, what it helps with (and what it refuses), how it speaks, and what it should know. Plain sentences and short lists work better than adjectives; the model follows rules it can act on and ignores praise.
Do
Don't
The second example fails because it gives the model nothing to decide with: no scope, no refusals, no facts. Three patterns cause most persona problems: rules that contradict each other (“be brief” and “explain everything”), a list of the only questions the agent may answer (end users never ask in the listed words), and facts that drift out of date (hours, prices, policies). Put changing facts in knowledge and keep the persona to rules.

​
Persona versions

The persona lives in your code, and lua persona sandbox edits that same persona value in src/index.ts. lua push agent (and lua push all) uploads it as a new numbered persona version and writes it onto the agent record the runtime reads: a pushed persona is served from the agent’s next message, and unlike a skill it doesn’t wait for a deploy or a promote. lua persona production view prints the live persona; lua persona production versions lists every version. To serve an earlier version, run lua deploy persona --set-version <n> --force (the same operation as lua persona production deploy --persona-version <n>): it switches the served persona to that version at once and is the persona’s rollback. An agent version records which persona version was current when it was created, but lua version promote does not change the served persona; it only marks the persona version it recorded as the published one in the list. After the quickstart your agent runs a promoted agent version; to change its persona, edit the code and push, then run lua version create and lua version promote so the agent version matches what is live. In the sandbox, lua chat sends the persona from your local code with each conversation, so iterating on wording needs no push.

​
From the admin dashboard

The agent’s Persona tab in the admin dashboard edits the same persona. Save as draft stores a draft version the agent doesn’t serve; Publish changes creates a published version that the agent serves from the next message; Activate version in the version history re-serves an earlier one. Admin dashboard and CLI versions form one numbered list, so lua persona production versions shows both. An admin dashboard edit is not in your source: the next lua push agent or lua push all creates a new version from src/index.ts and the agent serves that instead, so the admin dashboard wording stops being served (it stays in the history and can be activated again). Run lua sync --check before you push; it reports the difference, and lua sync --pull writes the server’s persona into src/index.ts instead.

​
Persona and skill context

Both are prompt text, but they have different scope. The persona is agent-wide and always present; a skill’s context is present only while that skill is active and should hold the rules for that skill’s tools (“ask for the order number before calling get_order_status”). Put a rule in the persona when it applies to every conversation, and in a skill’s context when it applies to that skill’s tools. Duplicating a rule in both doesn’t strengthen it.

​
When to change it

  • The agent answers out of scope, over-promises, or adopts the wrong tone: change the persona.
  • The agent picks the wrong tool or calls it too early: change that skill’s context or the tool’s description.
  • The agent gets a fact wrong: fix it in knowledge, not in the persona.
  • Voice calls need shorter turns than text: add a voice key rather than rewriting base.

​
Limits

  • Persona versions are integers assigned by the server on each lua push agent; you cannot choose the number.
  • The object form must set at least one of base, voice, text; a text channel never sees voice and a voice call never sees text.
  • lua persona sandbox edits the literal in src/index.ts; a persona built from an expression cannot be edited by the command.

​
Next steps

Build an agent

Write a persona and see it change the agent’s answers.

Releasing

Push, create a version, promote, and roll back.

lua persona

Every action and flag.

LuaAgent reference

The persona field and its type.