# Writing the brief The brief is the agent's job description. Seven prompt types, composed in a fixed order, published into the system prompt. Source: https://docs.omazy.ai/how-to/agent/brief/ import Figure from '../../../../components/Figure.astro' The brief is where you say who the agent is and what it may do. You write it in the console under **Agent, Prompts**. It is not one box of text. It is a set of small prompts, each with a type, which the platform composes into a single system prompt when you publish. That structure is doing real work, and understanding it is most of understanding the brief. Two things to hold on to before anything else: 1. **Edit the brief, never the system prompt.** Publishing overwrites the prompt with the composed brief, so a hand edit survives until the next publish and then vanishes without a trace. 2. **Nothing is live until you publish.** You can leave a half-written brief overnight and no customer will meet it. ## The seven prompt types Every prompt has a type. The type decides where it lands in the composed brief and what good looks like inside it. | Type | Answers | Shape | Length | |---|---|---|---| | **Identity** | Who the agent is | Second person, present tense. "You are..." | 3 to 6 sentences | | **Role** | The job, and where the job ends | Objective, what success is, what is *not* its job | 2 to 5 sentences | | **Instruction** | How to act, step by step | Numbered imperatives it can actually follow | Max 10 steps | | **Context** | Facts it must always hold | Terse lists. Prices, tiers, policies, names | Scannable, not prose | | **Memory** | Durable things learned | One fact per line, each independently removable | One line each | | **Sample** | What a good answer looks like | Worked visitor and agent pairs | 3 to 12 pairs | | **Rule** | Hard constraints | Flat must and must-never list | Short imperatives | A few of these are easy to confuse, so here is the short version of each. **Identity is the slowest-changing thing you will write.** Character, voice, standing posture. No procedure, no rules, no facts about the business. Write it to last. **Role is mostly about edges.** The valuable half is the sentence naming what is *not* its job. Scope boundaries matter more than warmth here. **Instruction is a procedure**, and procedures are ordered. "Ask one question, wait, respond to what you heard" is an instruction. If yours needs more than ten steps, it is two prompts. **Context is facts with no procedure attached.** Keep it terse and scannable. Paragraphs cost tokens on every single turn and read no better to a model than a list does. **Sample is the one people skip and should not.** Worked examples of a good answer, written as the visitor's line and then the ideal reply, at the exact length you actually want. The replies have to *demonstrate* the shape, not describe it. Include at least one example of your worst failure mode being corrected, because that is the one the model learns most from. **Rule is for things you can check.** Here is the test that settles almost every argument about where something belongs: > If a line cannot be judged true or false about a given reply, it is an > Instruction, not a Rule. "Never quote a price that is not in the catalog" is a rule. You can look at any reply and say yes or no. "Be helpful and friendly" is not a rule, it is a mood, and moods belong in Identity. ## The order is fixed, and that is deliberate Prompts are always composed in this order, regardless of the order you created them in: ``` # IDENTITY # ROLE # INSTRUCTION # CONTEXT # MEMORY # SAMPLE ANSWERS # RULES ``` You cannot drag them into a different order, and that is a feature rather than a missing one. Rules land last so they outrank the persona above them. Samples sit immediately before rules, so the model reads the target shape right before the constraints that police it. If you could reorder these, the most common thing that would happen is somebody dragging a friendly Identity below the Rules and quietly weakening every constraint in the brief, with nothing on screen to show it.
YOU AUTHOR IN ANY ORDER Rule Identity Context Sample composes to ALWAYS COMPOSES IN THIS ORDER 1 Identity who it is 2 Role the job, and where it ends 3 Instruction steps 4 Context facts 5 Memory what it learned 6 Sample worked answers 7 Rules these override everything above
The composed result is visible in the editor as **Composed brief**, so the order is never a mystery. You are just not allowed to break it. ## Writing one **New prompt**, pick a type, and either write markdown yourself or describe what you want and let it draft. The editor gives you three helpers: | Control | What it does | |---|---| | **Draft with AI** | You describe what the prompt should do; it writes the content | | **Revise** | You describe the change; it applies it to the content below | | **Title** | Left blank, it gets named for you | Drafting is genuinely useful here because each type carries its own authoring guidance behind the scenes. Ask for an Instruction and you get numbered steps. Ask for a Rule and you get short checkable imperatives, not a paragraph explaining why the rule exists. Review what comes back. Drafting saves you the blank page, not the thinking. ## Turning prompts off Every prompt has an enable toggle. Disabled prompts are skipped when composing, which makes the toggle the right tool for two jobs: - Testing whether a prompt is actually earning its tokens. Disable it, publish to a test agent, see if answers get worse. - Seasonal content. A holiday-hours Context prompt can sit disabled for eleven months instead of being deleted and rewritten every year. If nothing is enabled, the composed brief is empty and the editor says so. ## Versions and publishing **Composed and publish** writes the composed brief into the agent's system prompt and stores a numbered version at the same time. Every publish is a version, automatically, with no ceremony from you. That means: - **Currently live** always shows what the agent is running right now. - The editor flags when your working copy differs from what is live, so you never have to guess whether you published that change. - Earlier versions can be restored. Restoring is itself a normal edit, so it is auditable like everything else. Publish is deliberate rather than automatic. Some agents will warn you before publishing when checks have not passed, and you can proceed anyway; the warning is there so the decision is conscious, not so it is blocked. ## Test the brief, not the prose A brief reads beautifully and still behaves badly. The only check that counts is running your real questions through **Testing** and reading what comes out. Change one thing at a time. If you rewrite Identity, Role and Rules together and the agent gets worse, you have learned only that it got worse. ## What goes somewhere else The brief is instructions. Some things look like they belong here and do not: | That belongs in | Not the brief, because | |---|---| | [Knowledge](/how-to/agent/knowledge/) | Facts that change. Opening hours in a brief are wrong in six months, confidently, in the agent's voice | | Saved responses | Answers that must be word for word. The brief influences wording; it does not guarantee it | | [Suggestion pills](/how-to/agent/suggestions/) | Tappable answers to a question the agent just asked | | Catalog | Products with prices and media | There is one exception worth knowing. A **Context** prompt does hold facts, and that is correct when the fact is small, stable, and needed on every single turn. Your currency, your delivery radius, the two tiers you sell. Everything larger or more volatile belongs in knowledge, where it can be updated without republishing the agent and where an answer can cite where it came from. ## Size is a running cost Everything enabled in the brief goes to the model on **every turn**, for every customer, forever. A Context prompt with three paragraphs of history you never needed is not a one-off cost, it is rent. The editor shows the running total as **Context cost**. What that number means, and the two very different ways to bring it down, is [Context and compression](/how-to/agent/context/).