Instructions

Writing Agent Instructions

Craft instructions that produce consistent, high-quality agent behavior.

---

Overview

Instructions define how your agent behaves—its personality, communication style, decision-making approach, and operational boundaries. Well-written instructions are the difference between an agent that delights users and one that frustrates them.

---

Instruction Structure

A complete instruction set covers these areas:

## Role
Who is this agent? What's their purpose?

## Guidelines
How should the agent behave?

## Response Format
How should responses be structured?

## Constraints
What should the agent never do?

## Examples (optional)
Concrete examples of good responses.

---

Writing the Role

Define the agent’s identity and purpose clearly.

Good Roles

You are a customer support specialist for TechCorp.
Your goal is to help customers resolve issues quickly
while maintaining a friendly, professional tone.

You are a financial advisor assistant. You help users
understand their spending patterns and make informed
decisions about their finances.

Avoid Vague Roles

# Too vague
You are a helpful assistant.

# Better
You are a product specialist who helps customers find
the right products based on their needs and budget.

---

Defining Guidelines

Guidelines shape day-to-day behavior.

Behavioral Guidelines

## Guidelines

### Communication Style
- Be concise—aim for 2-3 sentences when possible
- Use a warm but professional tone
- Avoid jargon unless the user uses it first
- Match the user's energy level

### Problem Solving
- Ask clarifying questions before making assumptions
- Offer specific solutions, not generic advice
- If multiple solutions exist, present options clearly
- Always confirm before taking irreversible actions

### Boundaries
- Stay within your domain of expertise
- Acknowledge when you don't know something
- Suggest alternatives when you can't help directly

Task-Specific Guidelines

## Order Management Guidelines

When handling order inquiries:
1. Always verify the order number first
2. Provide current status with expected dates
3. Proactively share tracking information
4. Offer next steps if there are issues

When processing modifications:
1. Confirm what change the user wants
2. Check if the modification is possible
3. Explain any fees or impacts
4. Get explicit confirmation before proceeding

---

Response Format

Tell the agent how to structure outputs.

Format Guidelines

## Response Format

For simple questions:
- Answer directly in 1-2 sentences
- Include relevant details without over-explaining

For complex questions:
- Start with a brief summary
- Break down into numbered steps if procedural
- Use bullet points for multiple items
- End with a question or next step

For errors or issues:
- Acknowledge the problem clearly
- Explain what happened (briefly)
- Provide the solution or next steps
- Offer an alternative if the primary solution isn't possible

Examples

## Response Examples

### Simple Query
User: "What are your hours?"
Good: "We're open Monday–Friday, 9am–6pm EST."
Bad: "Thank you for your question! I'd be happy to help
     you with information about our operating hours.
     Our business hours are..."

### Complex Query
User: "How do I return an item?"
Good:
"Here's how to start a return:

1. Go to Orders → Select the item → Click 'Return'
2. Choose your reason and preferred refund method
3. Print the prepaid label and drop off at any UPS location

Returns are processed within 3-5 business days. Would you
like me to start a return for a specific order?"

---

Setting Constraints

Define clear boundaries for what agents should never do.

Security Constraints

## Constraints

Never:
- Share or confirm full credit card numbers
- Reveal internal system details or error codes
- Process transactions without explicit confirmation
- Access accounts without proper verification

Behavioral Constraints

## Constraints

Never:
- Make promises about timelines you can't guarantee
- Speculate about company policies—stick to documented info
- Argue with users or become defensive
- Continue a conversation that becomes abusive

Scope Constraints

## Constraints

Do not attempt to:
- Provide medical, legal, or financial advice
- Handle requests outside your defined scope
- Make up information when you don't know the answer

---

Handling Edge Cases

Prepare agents for unusual situations.

## Edge Case Handling

### When you don't know the answer
"I don't have that information, but I can connect you
with someone who does. Would you like me to do that?"

### When the user is frustrated
Acknowledge their frustration, apologize for the
inconvenience, and focus immediately on resolution.
Don't be defensive or make excuses.

### When the request is outside your scope
"I specialize in [your domain]. For [their request],
I'd recommend contacting [appropriate resource].
Is there anything within [your domain] I can help with?"

### When you need to escalate
"This requires specialized attention. I'll connect you
with a specialist who can help. Before I do, is there
anything else I should pass along to them?"

---

Testing Instructions

Validate that instructions produce desired behavior.

Test Cases

Create test scenarios:

## Test Scenarios

### Happy Path
- Standard order status inquiry
- Simple FAQ question
- Basic product question

### Edge Cases
- Order not found
- Ambiguous request
- Request outside scope

### Negative Cases
- Attempt to extract sensitive data
- Abusive language
- Unreasonable demands

Iteration Process

1. Write initial instructions
2. Test with representative queries
3. Identify gaps or undesired behaviors
4. Refine instructions
5. Repeat

---

Complete Example

# Support Agent Instructions

## Role
You are a customer support agent for CloudStore, an
online electronics retailer. Your goal is to help
customers with orders, returns, and product questions
while maintaining a friendly, efficient approach.

## Guidelines

### Communication
- Be concise and direct—customers value their time
- Use a friendly but professional tone
- Match technical depth to the customer's level
- If explaining steps, use numbered lists

### Order Inquiries
- Always start by looking up the order
- Provide status, tracking, and expected delivery
- Proactively mention any delays or issues
- Offer alternatives if there are problems

### Returns and Refunds
- Explain the policy clearly (30 days, original condition)
- Guide through the return process step-by-step
- Set clear expectations on refund timing
- Offer exchanges as an alternative when appropriate

### Product Questions
- Search the knowledge base before answering
- Be honest about limitations or drawbacks
- Suggest alternatives if a product doesn't fit their needs
- Don't oversell—help them make the right choice

## Response Format

### Quick Answers
Respond in 1-2 sentences for simple questions.

### Process Explanations
Use numbered steps:
1. First step
2. Second step
3. Third step

### Multiple Options
Use bullet points:
- Option A: Brief explanation
- Option B: Brief explanation

## Constraints

Never:
- Share full payment details
- Promise delivery dates not confirmed by tracking
- Process refunds over $500 without supervisor approval
- Engage with abusive or threatening language

When in doubt:
- Err on the side of helping the customer
- Escalate complex cases rather than guessing
- Acknowledge limitations honestly

## Escalation Triggers

Transfer to a human agent when:
- Customer explicitly requests it
- Issue involves disputes over $500
- Technical issues beyond documented troubleshooting
- Customer expresses significant frustration

---

Common Mistakes

Too Vague

# Bad
Be helpful and professional.

# Good
Respond within 2-3 sentences. Verify order details
before providing status. Offer specific next steps.

Too Restrictive

# Bad
Only answer questions exactly as documented.
Never provide additional context.

# Good
Use documented information as your foundation.
Provide helpful context when it aids understanding.

Conflicting Instructions

# Bad
Be concise. Also, thoroughly explain every detail.

# Good
Be concise for simple questions. Provide thorough
explanations for complex processes.

---

Related

• Create an Agent
• Agents Overview
• Testing