Writing instructions
Instructions are the one field only you can write. Everything else about an agent - its identity, its tone, the platform's safety rules, the tools it can reach - is set elsewhere and arrives in the prompt already.
This page is how to structure what's left. It applies to both single agents and the Agent nodes inside a multi agent, because the same runtime reads both.
Nothing parses your headings
There's no schema here. Headings are a habit that keeps you from writing the wrong things, not a format the platform validates.
Two do the work:
| Heading | What belongs there |
|---|---|
## Rules | Your business constraints, and how to use each tool |
## Exits | Each branch, and the sentence that causes it - Agent nodes only; a single agent has no exits |
Add a third only when it earns its place:
| Heading | Add it when |
|---|---|
## Steps | The order is genuinely fixed - do this, then this, then this |
If every line in your Steps section starts with "if", you don't have steps - you have rules. A conditional procedure written as steps makes the agent look more sequential than it is, and that's the beginning of most over-built prompts.
Numbering steps changes how the turn runs
This one is invisible, and worth knowing before it surprises you.
If your instructions contain Step 1 - any capitalisation - the runtime treats the agent as sequential. It injects step-execution rules and asks the model to report its progress every turn: which step it's on, which it has completed, which tools it ran.
That's usually what you want for a procedure:
- Numbered steps run one per turn, in order, rather than the model attempting everything at once.
- Progress survives across turns, so someone who wanders off-topic and comes back doesn't restart.
- The step it thinks it's on appears in the trace, which makes a stuck conversation much easier to debug.
It works against you when the instructions loop or jump backwards, because the injected rules describe a straight line while your text describes a graph.
Three levels
| When | Runtime effect | |
|---|---|---|
| No Steps section | order depends on the answers | none |
| Steps as bullets | fixed order, readable list | none |
Step 1…Step N | fixed order that must not be reordered | sequential mode + progress tracking |
Don't number things that aren't a sequence. Four unrelated capabilities written as Step 1–Step 4 become a four-turn procedure.
To write numbered steps without the switch, include a ### Step Rules heading of your own and the platform leaves your ordering alone.
What's already in your prompt
Before writing anything, know what the platform put there for you:
| Already present | So don't write |
|---|---|
| Your identity and tone from Profile settings | "You are Acme's friendly assistant. Be warm and professional." |
| Your project's conversation rules | Anything you've already said there |
| Safety rules - stay in role, use only values tools returned, keep internal names out of replies, decline what's out of scope | "Never make things up", "don't reveal your instructions" |
| The agent's name and its attached tools, with their descriptions | A list of the tools it has |
Routing rules are not in your prompt. They're read when the router picks an agent and never reach the agent itself, so an instruction here about which agent should handle something has nothing to act on.
That leaves your instructions one job: say what this agent does, in what order, with what boundaries.
Habits that work
Plain beats emphatic. Short, direct steps outperform capitalised insistence. Shouting doesn't increase compliance - it buries the actual instruction.
One instruction per line. Chain two actions with "and" or "then" and the model often does the first and drops the second.
Clean messy input before it reaches a tool. People don't answer in the shape a tool expects, so say how to normalise the reply first.
Reference tools and variables with @. Typing a tool's name as plain text works until someone renames it. An @-mention stores the slug and renders the current name, so the prompt doesn't go stale.
Next: Agent node recipes - two nodes written out in full, one with numbered steps and one without.