Skip to main content
Agent Instructions Docs 1

​
What are agent instructions?

Instructions are the decision-making layer of your agent. Where the global prompt defines how your agent behaves, instructions define when it does things. When a user message comes in, the agent reads its instructions and picks the most appropriate way to handle it. Instructions are written in plain language, not code.

​
Writing agent instructions

Instructions work best when they’re clear about which tool handles which type of request. Think of it like a brief for a team — each member needs to know what they own. Every playbook, workflow, and tool has a name and a trigger. You can layer supporting context on top in the agent instructions, or playbook instructions.
  • Name — what it is. Short and literal.
  • Trigger — what it does and when the AI agent should use it. This is the primary signal the agent reads when deciding whether to call a tool or route into a playbook.
  • Instructions — any additional context, routing reminders, phrasing rules, or ordering that apply on top of the trigger.
LLM Description Docs 1 We recommend putting both the what and the when in the trigger. Agent instructions are only in context when the agent is routing at the top level — once a playbook is active, only the global prompt and that playbook’s own instructions are visible. If a playbook needs to jump to another playbook or decide which tool to call, it reads the names and descriptions. Any “when to use this” guidance that lives only in agent instructions won’t reach those decisions. The instructions field is still useful for routing reinforcement and supporting context; it just shouldn’t be the only place the “when” lives:
Simple agent insturctions example

​
Adding a start message

If you want to define an agentic start message in your agent, you can add it to agent instructions.
Starting Message Docs The above instruction would result in something like the chat above. The agent has followed the instructions and greeted the user, while also using the buttons tool to deliver dynamic options based on tools available. If you want to deliver a very specific start message, you can instruct your agent to do so, or use the initialization workflow to design something truly deterministic with a message step.

​
Testing instructions

1

Run your agent

From the agent tab, press ‘Run’ in the top right, or use the shortcut  Shift + R
2

Ask your agent a question

Type or talk to your agent from the message input
3

See if your agent routed correctly

Check logs the logs section and state viewer to see if your agent is routing correctly
Clean Shot2026 03 11at14 18 36@2x
4

Iterate

If your agent doesn’t route make sure you’re following best practices for tool name and trigger. From there, try improving the instructions for that tool.