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.
LayerWhat it controlsWhen it applies
Global promptPersonality, tone, guardrailsEvery agentic turn, always
InstructionsRouting, tool selectionWhen deciding what to do next
PlaybookGoal-specific behaviorWhen a specific playbook is active

​
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 an LLM description. You can layer supporting context on top in the agent instructions, or playbook instructions.
  • Name — what it is. Short and literal.
  • LLM description — 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 description.
GoodBad
NameOrder StatusHandle order related things
LLM descriptionLooks up the status of an existing order by order ID or email. Use when the customer asks about an existing order, a delivery, or tracking info.Helps customers with orders
InstructionsRoute to Order Status for any order-related question. If the customer then wants to return or exchange the item, hand off to the Returns workflow.N/A
LLM Description Docs 1 We recommend putting both the what and the when in the LLM description. 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
# Routing
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 tool, 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.

# Tools
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 LLM description. From there, try improving the instructions for that tool.