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

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.

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