Prompt Engineering for Agents
Writing effective agent instructions is both an art and a science. Good instructions result in agents that consistently perform well, handle edge cases gracefully, and delight users. This guide teaches you how to write instructions that work.The Fundamentals
What Makes Good Instructions?
Good agent instructions are:Specific
Clear, detailed, and unambiguous. Vague instructions produce inconsistent results.
Actionable
Tell the agent what to DO, not just what to BE. Focus on behaviors and actions.
Complete
Cover the main cases, edge cases, and failure modes your agent will encounter.
Examples-Rich
Show the agent how to handle specific scenarios with concrete examples.
Bad vs. Good Instructions
- Bad Example
- Good Example
- Too vague (“help with questions”)
- No specific guidelines
- No tool usage instructions
- No examples
- No edge case handling
Instruction Structure
Recommended Template
Section Breakdown
1. Role & Identity
1. Role & Identity
Define who the agent is and what they do.Good:Bad:Include:
- Company name and what you do
- Agent’s specific role
- Primary function
- Key context
2. Primary Responsibilities
2. Primary Responsibilities
List specific tasks the agent handles.Good:Bad:Be specific: Each item should be actionable and measurable.
3. Communication Style
3. Communication Style
Define how the agent should communicate.Good:Bad:Include:
- Tone and personality
- Length guidelines
- Formatting preferences
- Example opening and closing
4. Tool Usage Guidelines
4. Tool Usage Guidelines
Explain when and how to use each tool.Good:Bad:For each tool:
- When to use it
- Required inputs
- Specific rules
- Example usage
5. Business Rules & Policies
5. Business Rules & Policies
Define hard constraints and policies.Good:Bad:Include:
- Qualification criteria
- Disqualification rules
- Escalation triggers
- Things agent should never do
6. Edge Case Handling
6. Edge Case Handling
Show how to handle unusual situations.Good:Bad:Include:
- 3-5 common edge cases
- Exact response language
- What to do, step by step
- When to escalate
7. Complete Examples
7. Complete Examples
Provide full conversation examples.Good:Why this works:
- Shows complete flow
- Demonstrates tool usage
- Models good conversation
- Handles objections
- Clear next steps
- Qualified lead (success case)
- Unqualified lead (rejection case)
- Edge case (unusual scenario)
Advanced Techniques
Chain of Thought Prompting
Encourage step-by-step reasoning by asking agents to think through problems.Few-Shot Examples
Provide multiple examples of desired behavior.Constraint Specification
Clearly define what agents should and shouldn’t do.Persona Consistency
Define personality traits with examples.Common Patterns
Customer Service Agent
Lead Qualification Agent
Content Generation Agent
Testing & Iteration
Test Scenarios
Always test instructions with:Happy Path
Happy Path
Standard, straightforward cases.
Edge Cases
Edge Cases
Unusual but possible scenarios.
Adversarial Cases
Adversarial Cases
Attempts to break or confuse the agent.
Error Conditions
Error Conditions
When tools fail or data is missing.
Iteration Process
1
Deploy Initial Instructions
Start with your best attempt at complete instructions
2
Test Thoroughly
Run through 10-20 test scenarios covering happy path and edge cases
3
Identify Gaps
Note where agent behavior doesn’t match expectations:
- Wrong tool usage
- Incorrect responses
- Missing edge case handling
- Tone issues
4
Update Instructions
Add specific guidance for identified gaps:
- More explicit tool usage rules
- Additional examples
- Edge case handling
- Clarified policies
5
Re-test
Verify improvements work and didn’t break existing behavior
6
Monitor Production
Watch real conversations for new edge cases
7
Continuous Improvement
Update instructions based on real-world performance
Common Mistakes
Being Too Vague
Being Too Vague
❌ Bad: “Be helpful”
✅ Good: “When customers ask questions, search the knowledge
base first, then provide a clear 2-3 sentence answer with a link
to the full article”Fix: Add specific actions and examples
Assuming Context
Assuming Context
❌ Bad: “Use the refund tool appropriately”
✅ Good: “Use the refund tool only when: 1) Customer explicitly
requests refund, 2) Order is < 30 days old, 3) Amount is < $500”Fix: State all assumptions explicitly
No Examples
No Examples
❌ Bad: “Handle customer complaints professionally”
✅ Good: “Example: Customer says ‘This product is terrible!’
Response: ‘I’m sorry you’re having a bad experience. I want to
help make this right. Can you tell me specifically what issue
you’re encountering?’”Fix: Show don’t tell - provide concrete examples
Ignoring Edge Cases
Ignoring Edge Cases
❌ Bad: Only describing happy path scenarios
✅ Good: “If order is past 30-day policy: ‘I understand you’d
like a refund. Our policy is 30 days, and your order is 35 days
old. While I can’t process this automatically, let me escalate to
our billing team to review your specific situation.’”Fix: Explicitly handle edge cases and exceptions
Contradictory Instructions
Contradictory Instructions
❌ Bad: “Be concise” + “Provide detailed explanations”
✅ Good: “Be concise: 2-3 paragraphs for most responses.
Provide detailed explanations only when: 1) Customer asks for
more detail, 2) Technical setup instructions, 3) Complex policies”Fix: Clarify when each instruction applies
No Tool Guidance
No Tool Guidance
❌ Bad: “You have access to these tools: [list]”
✅ Good: “Order Lookup: Use whenever customer mentions order
number. Call it BEFORE answering order status questions. Example:
Customer says ‘Order #12345’ → Look it up first, then respond”Fix: Explain when and how to use each tool with examples