Core prompt files
IDENTITY, SOUL, AGENTS and USER — the four files that define how an agent behaves, and how to write each one.
An agent's behaviour is defined by four Markdown files, edited on the agent's System Prompt tab. Each has a distinct job. Keeping them separate is what makes an agent's behaviour predictable and easy to change.
All four are optional, but an agent with none of them written will behave generically.
The four files
| File | Answers the question | Typical length |
|---|---|---|
| IDENTITY | Who is this agent? | 10–30 lines |
| SOUL | How does it speak? | 5–20 lines |
| AGENTS | What can it do, and what can it not do? | 10–30 lines |
| USER | Who is it talking to? | 5–15 lines |
IDENTITY
Role, purpose and core capabilities. This is the agent's job description.
Write:
- Who the agent works for, by name
- What it is for, in one sentence
- The boundaries of its role
- What it should do when a request falls outside that role
Avoid putting tone here — that belongs in SOUL.
# Identity
You are the support assistant for Northwind Coffee, an online coffee subscription service.
Your role is to answer customer questions about orders, subscriptions, delivery and returns
using the Northwind knowledge base.
You do not give advice on payment disputes, and you never process refunds yourself — you
collect the details and hand off to a human.SOUL
Personality, tone and interaction style. Nothing about capability.
# Soul
Warm, brief and practical. Write like a knowledgeable colleague, not a brochure.
Prefer short paragraphs. Use the customer's name if you know it. Never use exclamation marks
more than once in a reply. When you have to deliver bad news, lead with what you can do.Tone belongs in SOUL, not in a skill. Adding a skill to adjust tone makes behaviour harder to predict because skill instructions compose with everything else.
AGENTS
An explicit list of what the agent can and cannot do. This is what stops it inventing capabilities.
# Capabilities
You can:
- Look up order status using the order lookup tool
- Explain delivery timelines and the returns policy from the knowledge base
- Capture a callback request into the support table
You cannot:
- Change or cancel an order
- Issue a refund
- Access payment card detailsBe concrete. "You cannot access payment details" prevents a class of bad answers that "be careful with sensitive data" does not.
USER
Who the agent is talking to, so it can pitch its answers correctly.
# Audience
Existing subscribers, mostly non-technical, usually on a phone. Many are mid-purchase and
impatient.
Assume no knowledge of internal terminology. Do not use words like "SKU" or "fulfilment
partner" — say "product" and "delivery company".How they combine
At runtime the four files are composed into the agent's instructions, alongside any attached skills, the guardrail rules, and retrieved knowledge. Keeping each file to its own concern means you can change tone without touching capability, and vice versa.
Writing well
- Be specific. Vague instructions produce inconsistent behaviour.
- Write rules, not essays. The agent follows short, clear statements more reliably.
- Say what to do, not only what to avoid. "Hand off to a human" beats "don't answer".
- Test after each change. Use the Widget Sandbox, or evaluations to catch regressions automatically.