Writing good instructions
System instructions are the single biggest lever on how an agent behaves. A clear prompt produces a focused, predictable agent; a vague one produces a confident but unreliable one. Instructions are written in the Profile tab of the Agent Builder.
Structure that works
Write instructions in this order. Each part answers a question the model would otherwise guess at.
| Section | What to write |
|---|---|
| Role | Who the agent is and the one job it owns. |
| Do | The specific tasks it should perform and how. |
| Don’t | What it must refuse or stay away from. |
| Clarify | When to ask a question instead of guessing. |
| Escalate | When to hand off to a person and how. |
| Format | The shape of the answer when consistency matters. |
Principles
- Be specific about the role. “You are a support agent for Acme’s billing product” beats “You are a helpful assistant.”
- Show, don’t just tell. Include one or two short examples of a good answer. Examples constrain behavior better than adjectives.
- Set explicit boundaries. State what to refuse and what to escalate. Silence here is where agents go off-script.
- Define tone once, concretely. “Concise, friendly, no emoji” is enforceable; “be professional” is not.
- Reference knowledge and tools by intent. Say when to search the knowledge base or use a tool, not just that it exists.
Keep it lean
Longer is not better. Overstuffed instructions dilute the important rules and raise cost on every turn.
- Put reusable behavior into a skill instead of repeating it across agents.
- Cut rules the model already follows by default.
- Remove contradictory guidance — conflicting rules produce inconsistent answers.
Use Enhance with AI as a draft, not a final
The Profile tab’s Enhance with AI can draft or improve a prompt from a short description. Treat its output as a starting point: read it, cut what doesn’t apply, and add the specifics only you know.
Test against real prompts
After writing instructions, test from the builder preview with prompts that read like real user requests — including edge cases and escalation scenarios. When a response is wrong, change the instructions, save, and retest before touching another setting. See Debugging behavior.