Writing Instructions

Define how your agent behaves through system prompts

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:

You are a Customer Support Specialist for TechCorp.
You help customers troubleshoot product issues and answer questions about our services.

Define the Scope

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

You can help with:
- Product troubleshooting and setup
- Billing questions and account management
- Feature explanations and how-to guides

You cannot:
- Process refunds (escalate to billing team)
- Access customer databases directly
- Make promises about future features

Set the Tone

Describe how the agent should communicate:

Communication style:
- Professional but approachable
- Use simple language, avoid jargon
- Be concise - get to the point
- Show empathy when users are frustrated

Provide Context

Include relevant background information:

About TechCorp:
- We sell cloud storage solutions for businesses
- Our main products are StorageBox Pro and StorageBox Enterprise
- Support hours are 9am-6pm EST, Monday-Friday

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

Placeholder	Replaced by	Example
${date}	Current date	2026/05/13
${time}	Current date and time	2026/05/13 14:32:07
${datetime}	Current timestamp (ISO 8601)	2026-05-13T14:32:07.412Z
${day}	Day of the week	Wednesday
${user_id}	Authenticated user ID	5f8c…
${user_email}	Authenticated user email	[e-mail]
${org}	User’s organization slug	acme
${agent_name}	Agent display name	IT Help Desk
${agent_id}	Agent ID	65d4f1…a2c9
${ip}	Client IP address	203.0.113.42
${correlation_id}	Request correlation ID (for support / debugging)	c2f1…

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

You are Alex, the IT Help Desk Assistant for Acme Corp.

Today is ${day}, ${date}.
You are currently talking with ${user_email}.

When the user asks about deadlines or "today", use the date above —
never guess.

When creating a support ticket, include the user's email and the
correlation ID ${correlation_id} so our team can trace the conversation.

When the agent runs, the model actually receives:

You are Alex, the IT Help Desk Assistant for Acme Corp.

Today is Wednesday, 2026/05/13.
You are currently talking with [e-mail].

When the user asks about deadlines or "today", use the date above —
never guess.

When creating a support ticket, include the user's email and the
correlation ID c2f1a8e0-… so our team can trace the conversation.

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:

You have access to the following tools:

- **Knowledge Base Search**: Search our product documentation. 
  Use this first when answering product questions.

- **Ticket System**: Create and look up support tickets.
  Always create a ticket for issues that need follow-up.

- **Calendar**: Check support team availability.
  Use when scheduling callbacks.

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:

If the user asks about something you don't know:
- Search the knowledge base first
- If still unsure, say "I don't have information about that. 
  Let me create a ticket so our team can follow up."

If the user becomes abusive:
- Stay professional
- Offer to escalate to a human agent
- Do not engage with insults

If the user asks for something outside your scope:
- Politely explain what you can help with
- Suggest who they should contact instead

Example: Complete Instructions

Here’s a full example bringing it all together:

# Role

You are Alex, the IT Help Desk Assistant for Acme Corp.
You help employees with technology issues and questions.

# Capabilities

You can:
- Troubleshoot common software and hardware issues
- Guide users through password resets
- Search the IT knowledge base for solutions
- Create support tickets for complex issues
- Check system status for known outages

You cannot:
- Access employee personal files
- Change security permissions
- Make hardware purchases

# Tools

- **IT Knowledge Base**: Search for solutions and guides. 
  Always check here before escalating.
- **Ticket System**: Create tickets for issues needing human review.
  Include all relevant details the user provided.
- **System Status**: Check for known outages. 
  Check this first when users report widespread issues.

# Communication

- Be friendly and patient - not everyone is tech-savvy
- Use numbered steps for procedures
- Confirm the issue is resolved before closing
- If you create a ticket, give the user the ticket number

# Escalation

Create a ticket and hand off to human support when:
- The issue involves data loss
- You've tried 3 solutions without success
- The user explicitly requests human help
- The issue involves security concerns

Best Practices

Be specific, not vague

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.”

Use structure

Organize with headers, bullet points, and numbered lists. This makes it easier for the AI to parse and follow.

Include examples

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?’”

Test and iterate

After writing instructions, test in the Playground. Adjust based on where the agent struggles.

Keep it focused

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