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 uses skills. When a message comes in, the agent reads its instructions and picks the most appropriate skill to handle it. Instructions are written in plain language, not code.
LayerWhat it controlsWhen it applies
Global promptPersonality, tone, guardrailsEvery turn, always
InstructionsRouting, skill selectionWhen deciding what to do next
PlaybookGoal-specific behaviorWhen a specific skill is active

​
Writing agent instructions

Instructions work best when they’re clear about which skill handles which type of request. Think of it like a brief for a team — each member (skill) needs to know what they own.

​
Naming skills & writing LLM descriptions

Each playbook and workflow (skills) have three things the agent uses when routing: a name, an LLM description, and its routing logic in the agent instructions. They serve different purposes.
  1. Name — what the skill is. Keep it short and literal.
  2. LLM description — what it does. One sentence, outcome-focused.
  3. Instructions — when to use it. This is what goes in the instructions field.
GoodBad
NameOrder StatusHandle order related things
LLM descriptionLooks up the status of an existing order by order ID or emailHelps customers with orders
InstructionsRoute to the Order Status playbook when the user asks
about their existing orders.		N/A
LLM Description Docs While testing, you might realize that if you put both the what and when in the LLM description it will work. But as your agent grows, you’ll notice model confusion. We recommend following the mental model: skill name & LLM description for what, agent instructions for when. Keeping them separate makes it easier to update routing logic without touching skill descriptions, and gives the model cleaner, more focused signal for each decision.
Simple agent insturctions example
# Skills
Route to the Order Status playbook if the customer is asking
about an existing order, delivery, or tracking information.

Route to the Returns workflow if the customer wants to return,
exchange, or get a refund on a product.

Route to the Product Info playbook if the customer is asking
about product details, availability, or compatibility.

If the customer's request doesn't fit any skill, let them
know what you can help with and ask them to rephrase, or use the knowledge
base to provide accurate information.

​
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
Greet the user and offer assitance, use buttons to show the user
quick options of what they can do.

# Skills
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 skills 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 youre following best practices for Skill name and LLM description. From there, try improving the instructions for that skill.