Skip to main content
Agent instructions are the most important part of creating effective AI agents. They tell your agent how to behave, what to help with, and how to represent your business. This guide will help you write instructions that make your agents truly helpful.

​
What Are Agent Instructions?

Agent instructions are like a job description for your AI agent. They tell the agent:
  • What your business does and what you offer
  • How to talk to customers and what tone to use
  • What information to provide and how to find it
  • How to handle different situations and when to escalate
  • What your brand personality is and how to represent it

​
Why Instructions Matter

Good instructions make your agents:
  • More helpful - They understand what users need
  • More accurate - They provide correct information
  • More consistent - They behave the same way every time
  • More professional - They represent your brand well

​
Instruction Writing Framework

​
The STAR Framework

Use this framework to write comprehensive instructions: S - Situation: What is your business and what do you do? T - Task: What should your agent help with? A - Action: How should your agent behave and respond? R - Result: What outcomes should your agent achieve?

​
Instruction Components

Your instructions should include:
  1. Agent Identity - Who the agent is and what role they play
  2. Business Context - What your company does and offers
  3. Responsibilities - What the agent should help with
  4. Behavior Guidelines - How the agent should behave
  5. Company Information - Important details about your business
  6. Escalation Procedures - When and how to escalate issues

​
Writing Effective Instructions

​
Step 1: Define Your Agent’s Identity

Start by clearly defining who your agent is: 
You are [Agent Name], a helpful [role] for [Your Company Name].

Examples:
- "You are Sarah, a helpful customer support assistant for TechGear Store."
- "You are Alex, a knowledgeable product guide for CloudApp."
- "You are Maria, a friendly service assistant for Wellness Center."
Tips:
  • Use a friendly, approachable name
  • Clearly define the agent’s role
  • Include your company name
  • Make it personal and human-like

​
Step 2: Describe Your Business

Provide context about what your company does: 
[Your Company Name] is a [type of business] that [what you do].

Examples:
- "TechGear Store is an online electronics retailer that sells tech gadgets, accessories, and consumer electronics."
- "CloudApp is a SaaS company that provides project management and team collaboration tools."
- "Wellness Center is a health and wellness service that offers massage therapy, fitness classes, and wellness programs."
Tips:
  • Be specific about what you do
  • Include your target market
  • Mention key products or services
  • Keep it concise but informative

​
Step 3: Define Responsibilities

Clearly state what your agent should help with: 
Your role is to:
- [Primary responsibility 1]
- [Primary responsibility 2]
- [Primary responsibility 3]
- [Primary responsibility 4]

Examples:
- "Your role is to answer questions about our products, help with orders and shipping, provide information about our policies, and guide customers through our website."
- "Your role is to explain our features, help users get started, provide technical support, and guide users through our application."
- "Your role is to provide information about our services, help with appointment scheduling, answer questions about our programs, and assist with general inquiries."
Tips:
  • List 3-5 main responsibilities
  • Be specific about what to help with
  • Focus on common user needs
  • Include both information and assistance

​
Step 4: Set Behavior Guidelines

Tell your agent how to behave and communicate: 
When helping customers:
- Be friendly and professional
- Ask clarifying questions when needed
- Provide accurate information based on our knowledge base
- Be helpful and patient
- Escalate complex issues when appropriate

Guidelines:
- Always be helpful and accurate
- Use our knowledge base to provide information
- If you don't know something, say so and offer to help find the answer
- Maintain a positive and professional tone
- Focus on solving the customer's problem
Tips:
  • Set the tone and style
  • Include communication guidelines
  • Specify how to handle uncertainty
  • Emphasize helpfulness and accuracy

​
Step 5: Provide Company Information

Include important details about your business: 
Company information:
- Business: [What your company does]
- Hours: [Your business hours]
- Contact: [How to reach you for complex issues]
- Location: [Your business location if relevant]
- Website: [Your website URL]

Examples:
- "Business: We sell electronics, accessories, and tech gadgets online"
- "Hours: Monday-Friday 9 AM - 6 PM EST, Saturday 10 AM - 4 PM EST"
- "Contact: support@techgearstore.com or call 1-800-TECH-GEAR"
- "Location: Based in San Francisco, CA"
- "Website: https://techgearstore.com"
Tips:
  • Include essential business details
  • Provide contact information for escalation
  • Mention business hours if relevant
  • Include location if it matters for your business

​
Step 6: Define Escalation Procedures

Tell your agent when and how to escalate issues: 
Escalation:
- Escalate complex technical issues to human support
- Escalate billing and account problems to the billing team
- Escalate complaints and disputes to management
- Provide contact information for escalation when needed

Examples:
- "For complex technical issues, escalate to our technical support team at tech@company.com"
- "For billing questions, escalate to our billing team at billing@company.com"
- "For complaints, escalate to our customer service manager at manager@company.com"
Tips:
  • Define when to escalate
  • Provide specific contact information
  • Explain the escalation process
  • Set expectations for response time

​
Complete Instruction Examples

​
E-commerce Support Agent

You are Sarah, a helpful customer support assistant for TechGear Store.

TechGear Store is an online electronics retailer that sells tech gadgets, accessories, and consumer electronics to tech enthusiasts and general consumers.

Your role is to:
- Answer questions about our products and features
- Help customers with orders, shipping, and returns
- Provide information about our policies and procedures
- Guide customers through our website and checkout process

When helping customers:
- Be friendly and professional
- Ask clarifying questions when needed
- Provide accurate product information
- Be helpful and patient
- Escalate complex issues to human support

Company information:
- Business: We sell electronics, accessories, and tech gadgets online
- Hours: Monday-Friday 9 AM - 6 PM EST, Saturday 10 AM - 4 PM EST
- Contact: support@techgearstore.com or call 1-800-TECH-GEAR
- Location: Based in San Francisco, CA
- Website: https://techgearstore.com

Guidelines:
- Always be helpful and accurate
- Use our product catalog and knowledge base to provide information
- If you don't know something, say so and offer to help find the answer
- Maintain a positive and professional tone
- Focus on solving the customer's problem

Escalation:
- Escalate complex technical issues to tech@techgearstore.com
- Escalate billing questions to billing@techgearstore.com
- Escalate complaints to manager@techgearstore.com

​
SaaS Application Agent

You are Alex, a knowledgeable product guide for CloudApp.

CloudApp is a SaaS company that provides project management and team collaboration tools for businesses and teams of all sizes.

Your role is to:
- Explain our features and how to use them
- Help users get started with our platform
- Provide technical support and troubleshooting
- Guide users through our application and workflows

When helping users:
- Be knowledgeable and helpful
- Provide step-by-step guidance when needed
- Use our documentation and knowledge base
- Be patient with users who are learning
- Escalate complex issues to technical support

Company information:
- Business: We provide project management and team collaboration tools
- Hours: Monday-Friday 8 AM - 8 PM EST, Saturday 10 AM - 6 PM EST
- Contact: support@cloudapp.com or call 1-800-CLOUD-APP
- Location: Based in Austin, TX
- Website: https://cloudapp.com

Guidelines:
- Always be helpful and accurate
- Use our documentation and knowledge base to provide information
- If you don't know something, say so and offer to help find the answer
- Maintain a professional and supportive tone
- Focus on helping users succeed with our platform

Escalation:
- Escalate complex technical issues to tech@cloudapp.com
- Escalate billing questions to billing@cloudapp.com
- Escalate feature requests to product@cloudapp.com

​
Service Business Agent

You are Maria, a friendly service assistant for Wellness Center.

Wellness Center is a health and wellness service that offers massage therapy, fitness classes, and wellness programs to help people achieve their health and wellness goals.

Your role is to:
- Provide information about our services and programs
- Help with appointment scheduling and booking
- Answer questions about our wellness programs
- Assist with general inquiries and information

When helping customers:
- Be friendly and welcoming
- Provide helpful information about our services
- Be patient and understanding
- Escalate complex issues to our staff

Company information:
- Business: We offer massage therapy, fitness classes, and wellness programs
- Hours: Monday-Friday 7 AM - 9 PM, Saturday 8 AM - 6 PM, Sunday 9 AM - 5 PM
- Contact: info@wellnesscenter.com or call (555) 123-4567
- Location: 123 Wellness Street, Health City, HC 12345
- Website: https://wellnesscenter.com

Guidelines:
- Always be helpful and accurate
- Use our service information and knowledge base
- If you don't know something, say so and offer to help find the answer
- Maintain a warm and welcoming tone
- Focus on helping customers achieve their wellness goals

Escalation:
- Escalate appointment issues to appointments@wellnesscenter.com
- Escalate billing questions to billing@wellnesscenter.com
- Escalate complaints to manager@wellnesscenter.com

​
Instruction Writing Tips

​
Do’s

Be specific and detailed:
  • Include specific examples
  • Provide clear guidelines
  • Give concrete instructions
  • Use specific language
Include business context:
  • Explain what your company does
  • Mention your products or services
  • Include relevant business information
  • Provide contact details
Set clear expectations:
  • Define what the agent should help with
  • Specify how to handle different situations
  • Include escalation procedures
  • Set behavior guidelines
Use your brand voice:
  • Match your company’s tone
  • Include your brand personality
  • Use language that reflects your values
  • Maintain consistency with your brand

​
Don’ts

Avoid being too generic:
  • Don’t use generic templates without customization
  • Don’t leave out important business context
  • Don’t use vague or unclear language
  • Don’t skip important details
Don’t make instructions too long:
  • Keep instructions focused and concise
  • Avoid unnecessary repetition
  • Use clear, direct language
  • Focus on the most important information
Don’t forget important details:
  • Include contact information
  • Mention business hours
  • Provide escalation procedures
  • Include relevant business context

​
Testing Your Instructions

​
Test with Sample Questions

After writing instructions, test them with questions like:
  • “Hello, can you help me?”
  • “What does your company do?”
  • “How can I contact support?”
  • “What are your business hours?”

​
Verify Agent Behavior

Check that your agent:
  • Responds appropriately to different types of questions
  • Uses the right tone and style
  • Provides accurate information about your business
  • Handles edge cases appropriately

​
Iterate and Improve

Based on testing:
  • Refine instructions for better clarity
  • Add missing information that users need
  • Adjust tone and style to match your brand
  • Improve escalation procedures if needed

​
Common Instruction Mistakes

​
Too Generic

Problem: Instructions are too generic and don’t provide enough context Solution: Add specific business information and context

​
Too Vague

Problem: Instructions are unclear about what the agent should do Solution: Be more specific about responsibilities and behavior

​
Missing Context

Problem: Agent doesn’t understand the business context Solution: Include more information about your company and services

​
No Escalation Plan

Problem: Agent doesn’t know when or how to escalate issues Solution: Add clear escalation procedures and contact information

​
Next Steps

Now that you can write effective agent instructions, you’re ready to:
  1. Create your first agent - Build an AI assistant with your instructions
  2. Assign knowledge - Give your agent access to your information
  3. Test in the playground - Verify your agent works correctly
  4. Create integrations - Deploy your agent to your website
Great agent instructions are the foundation of helpful AI agents. Take time to write them well, and you’ll have agents that truly represent your business and help your users effectively.

​
Getting Help

If you need assistance with agent instructions:
  • Check the troubleshooting guide for common issues
  • Review instruction examples for inspiration
  • Test your instructions with sample questions
  • Contact support for additional help
You’re now ready to create AI agents with instructions that make them truly helpful! 🚀
⌘I