Skip to main content
Instructions are the foundation of your agent’s behavior. They tell the AI who it is, what it should do, and how it should interact with users.

​
The Instructions Editor

Open any agent and go to the Instructions section. You’ll see:
  • A text editor for your system prompt
  • Model selector to change the AI model
  • Save button (changes are saved as drafts until published)

​
Writing Effective Instructions

​
Start with Identity

Tell the agent who it is:

​
Define the Scope

Be clear about what the agent should and shouldn’t do:

​
Set the Tone

Describe how the agent should communicate:

​
Provide Context

Include relevant background information:

​
Dynamic Variables

You can insert runtime values into your instructions using ${variable} placeholders. They are replaced automatically every time the agent runs, so the model always sees the current date, the user it is talking to, and the agent it is impersonating.

​
Available variables

​
Why use them

Without dynamic variables, the model has no built-in sense of “now” or “who”. It will guess the date (often wrong by months), greet the user generically, or refuse time-sensitive tasks. Inserting variables gives the agent fresh context on every message — the platform fills them in before the prompt is sent to the model.

​
Example

When the agent runs, the model actually receives:
Use ${date} and ${day} whenever your agent reasons about time — scheduling, “is this still valid?”, expiration checks, follow-ups. Without it, models invent a date from their training data.
Unknown placeholders are left untouched. If you write ${foo} and there is no foo variable, it stays as ${foo} in the prompt rather than becoming an empty string — so a typo is visible instead of silently breaking your instructions.

​
Working with Tools

When your agent has tools attached, mention them in the instructions:
After adding a tool in the Capabilities section, go back to Instructions and add guidance on when and how to use it.

​
Handling Edge Cases

Anticipate situations and provide guidance:

​
Example: Complete Instructions

Here’s a full example bringing it all together:

​
Best Practices

Instead of “be helpful”, specify what helpful means: “Answer questions directly, provide step-by-step instructions when explaining processes, and confirm the user’s issue is resolved before ending the conversation.”
Organize with headers, bullet points, and numbered lists. This makes it easier for the AI to parse and follow.
Show the agent what good responses look like: “When greeting users, say something like: ‘Hi! I’m Alex from IT Help Desk. What can I help you with today?’”
After writing instructions, test in the Playground. Adjust based on where the agent struggles.
Long, sprawling instructions can confuse the model. Focus on what matters most for your use case.

​
Changing Models

Different models have different strengths. To change:
  1. Click the model selector below the instructions editor
  2. Choose from available models
  3. Save your changes
Model changes take effect immediately in the Playground. For published agents, you’ll need to publish again.

​
When the current model is flagged

The model selector surfaces a banner when the agent’s currently-configured model is no longer fully usable:
  • 🔴 Error: the model has been deleted, disabled, or removed from the organization’s allowed list — the agent will stop working until you pick another one.
  • 🟡 Warning: the model has only been hidden at platform level — the agent still works, but you’re encouraged to switch to a supported model.
See Model Lifecycle: Hidden vs Disabled for the underlying semantics.

​
Next Steps

Add capabilities

Give your agent tools and knowledge to work with

Test in Playground

Try out your instructions and see how the agent responds