Skip to main content

Assistant Best Practices

This guide compiles proven patterns, strategies, and lessons learned from building successful agents. Follow these practices to create agents that perform reliably, cost-effectively, and delight users.

Design Principles

Start Simple, Add Complexity

The Progressive Enhancement Approach

Phase 1: Core Functionality
  • Single, clear purpose
  • 1-2 essential tools
  • Basic instructions
  • Simple happy path
Phase 2: Refinement
  • Test with real users
  • Add edge case handling
  • Refine instructions based on feedback
  • Optimize tool usage
Phase 3: Enhancement
  • Add advanced features
  • More tools as needed
  • Sophisticated error handling
  • Performance optimization
Why this works:
  • Faster initial deployment
  • Easier debugging
  • Clear performance baseline
  • Incremental improvement
Example:

Single Responsibility Principle

Each agent should have one clear purpose.
Benefits:
  • ✅ Clear purpose
  • ✅ Easier to optimize
  • ✅ Simpler instructions
  • ✅ Better performance
  • ✅ Easier to debug
When to split agents:
  • Agent instructions exceed 2,000 words
  • Agent has 10+ tools
  • Performance is inconsistent
  • Different user groups with different needs
  • Clear logical separation of concerns

Instruction Writing

Be Obsessively Specific

Vague instructions produce inconsistent results. Specificity drives performance.
Vague: “Help customers”Specific:
When agents know what success looks like, they optimize for it.
Vague: “Be concise” ✅ Specific: “Keep responses under 3 paragraphs (150 words)”Vague: “Process small refunds” ✅ Specific: “Process refunds up to $500 automatically”Vague: “Qualify good leads” ✅ Specific: “Qualify leads with score > 70 (based on: company size 50-5000, industry match, budget $10K+, timeline < 6 months)”Numbers eliminate ambiguity.
Vague: “Be empathetic with frustrated customers”Specific with example:
Examples teach better than descriptions.
Don’t assume agents will “figure it out.” Explicitly handle edge cases.
Cover the top 5-10 edge cases explicitly.

Tool Management

Tool Selection Strategy

The 80/20 Rule for Tools

Start with the 20% of tools that solve 80% of needs:Phase 1 (Essential):
  • Primary data source (knowledge base, CRM, database)
  • Most common action tool (create ticket, process refund)
Phase 2 (Enhancement):
  • Secondary data sources
  • Additional action tools
Phase 3 (Optimization):
  • Advanced features
  • Nice-to-have integrations
Don’t add tools “just in case.” Each tool adds cost and complexity.

Tool Usage Patterns

For knowledge-based agents, always search first.
Why: Ensures accuracy, provides citations, keeps information current.
For action tools (refunds, deletions, updates), verify first.
Why: Prevents errors, fraud, and accidental actions.
For sales agents, gather data before making decisions.
Why: Better qualification accuracy, informed conversations, higher conversion rates.
When agents hit their limits, escalate gracefully.
Why: Builds trust, prevents errors, ensures customer gets best possible help.

Performance Optimization

Token Efficiency

Don’t use more context than needed.Audit your usage:
  1. Check actual token usage in logs
  2. Are you consistently near the limit? → Increase
  3. Are you using < 50% of limit? → Decrease
Optimize context:
  • Enable Smart Context (reduces tokens automatically)
  • Limit message history to what’s actually needed
  • Trim verbose tool descriptions
  • Use concise instructions
Typical needs:
  • Simple Q&A: 16K tokens
  • Standard agents: 50K tokens
  • Complex agents: 100K tokens
  • Document processing: 128K+ tokens
Tool descriptions count toward token limits.Verbose:
(61 words, ~80 tokens)Concise:
(20 words, ~27 tokens)Saved: 53 tokens per tool × 5 tools = 265 tokens saved
Set appropriate reasoning step limits.Profile your agents:
  • Simple tasks: 3-5 steps needed
  • Standard tasks: 5-10 steps needed
  • Complex tasks: 10-15 steps needed
If agents rarely use all steps, lower the limit. If agents frequently hit the limit without completing tasks, raise it.Each unnecessary step costs tokens:
  • Average step: 200-500 tokens
  • 5 unused steps: 1,000-2,500 tokens wasted
For frequently asked questions, consider caching.Implement caching for:
  • “What are your hours?” (asked 100x/day)
  • “What’s your return policy?” (asked 50x/day)
  • Common product questions
Approach:
  1. Identify top 20 repeated questions
  2. Pre-generate high-quality responses
  3. Store in fast-access cache
  4. Return cached response when matched
  5. Fall back to agent for unique queries
Benefits:
  • Instant responses (< 100ms)
  • Zero token cost for cached hits
  • Consistent quality
  • Reduced API load

Cost Management

Match model capability to task complexity.Decision matrix:Example optimization:
  • Task: Simple lead qualification (company size, industry match)
  • Start with: Claude Haiku 4.5 (default, included in plan)
  • Upgrade only if: Task complexity requires deeper reasoning
  • Performance: Haiku 4.5 handles most qualification tasks extremely well
Track costs and set up alerts.Key metrics to monitor:
  • Cost per agent run
  • Cost per day/week/month
  • Token usage per agent
  • Most expensive agents
  • Unusual spikes
Set alerts for:
  • Daily spend exceeds $X
  • Agent cost exceeds expected baseline
  • Token usage spikes unexpectedly
  • Error rates increase (retries cost money)
Review monthly:
  • Which agents cost the most?
  • Can any be optimized?
  • Are costs justified by value?
Failed operations that retry cost double.Reduce retries by:
  • Better input validation
  • Clearer instructions
  • Output schemas (catch errors before production)
  • Better error handling
  • Testing edge cases
Example:
  • Agent without output schema: 20% retry rate
  • Same agent with output schema: 5% retry rate
  • Cost reduction: 15% × (cost per run)

Quality Assurance

Testing Checklist

Before deploying to production, test:
1

Happy Path Scenarios

  • 10 typical, straightforward interactions
  • Verify agent responds correctly
  • Check tool usage is appropriate
  • Confirm output format
2

Edge Cases

  • 5-10 unusual but possible scenarios
  • Past-policy refund requests
  • Missing data
  • Tool failures
  • Ambiguous requests
3

Error Conditions

  • Invalid inputs
  • Tool timeouts
  • Authentication failures
  • Rate limit errors
  • Malformed data
4

Adversarial Cases

  • Attempts to break role
  • Extremely long inputs
  • Nonsense queries
  • Rapid-fire questions
  • Contradictory requests
5

Performance

  • Response time acceptable?
  • Token usage reasonable?
  • Cost per interaction acceptable?
  • No memory leaks or hangs?
6

User Experience

  • Tone is appropriate?
  • Responses are helpful?
  • Escalation works smoothly?
  • Overall experience positive?

Monitoring in Production

Define and monitor success metrics:Customer Service Agent:
  • % inquiries resolved without escalation
  • Average response time
  • Customer satisfaction score
  • Tool usage accuracy
  • Cost per resolution
Lead Qualification Agent:
  • % leads qualified automatically
  • Qualification accuracy (validated by sales)
  • Meeting booking rate
  • Time saved per lead
  • Cost per qualified lead
Set targets and track trends:
  • Week over week improvement?
  • Seasonal variations?
  • Degradation after changes?
Manually review sample conversations:Sample strategy:
  • 10 random conversations
  • 5 escalated conversations
  • 5 low-satisfaction conversations
  • 5 high-satisfaction conversations
Look for:
  • Instruction following
  • Tool usage appropriateness
  • Tone and communication quality
  • Edge cases not yet handled
  • Opportunities for improvement
When making changes, A/B test:Example:
  • Version A: Current instructions
  • Version B: Updated instructions
  • Split traffic: 50/50
  • Run for: 1-2 weeks
  • Measure: Key metrics
  • Winner: Better performance on metrics
What to test:
  • Instruction changes
  • Tool addition/removal
  • Model changes
  • Prompt optimization
  • Response format

Security Best Practices

Never expose sensitive information inappropriately:
Guard against attempts to override instructions:
Implement appropriate safeguards:For read-only tools:
  • Basic authentication sufficient
  • Minimal risk
For action tools (refunds, deletions, updates):
  • Require strong authentication
  • Implement monetary/scope limits
  • Add human approval for high-value actions
  • Log all actions
  • Set up alerts for unusual activity
Example:
Maintain comprehensive audit logs:Log for every interaction:
  • Timestamp
  • User identifier (hashed/anonymized if needed)
  • Agent used
  • Input prompt
  • Agent response
  • Tools called (with parameters)
  • Errors encountered
  • Token usage
  • Cost
Use logs for:
  • Security audits
  • Debugging issues
  • Performance analysis
  • Compliance reporting
  • Fraud detection

Common Pitfalls to Avoid

Mistake: Building complex, feature-rich agents before testing basic functionality.Fix: Start simple. Validate core functionality. Add complexity incrementally.Example:
  • ❌ Build agent with 15 tools and 5,000-word instructions on day 1
  • ✅ Build agent with 2 tools and 500-word instructions. Test. Iterate.
Mistake: Optimizing based on assumptions rather than actual usage.Fix: Monitor real conversations. Talk to users. Iterate based on reality.Example:
  • ❌ “I think users want X” → Build X
  • ✅ Review 50 conversations → Users actually need Y → Build Y
Mistake: Assuming tools always work. No error handling.Fix: Explicitly instruct agents how to handle tool failures.Example:
Mistake: “The agent should be helpful” with no concrete metrics.Fix: Define measurable success criteria before deployment.Example:
  • ❌ “Agent should help customers”
  • ✅ “Agent should: 1) Resolve 75% of inquiries without escalation, 2) Response time < 30 seconds, 3) CSAT > 4.5/5”
Mistake: Overwriting instructions with no history.Fix: Version control your instructions. Track changes. Can roll back.Approach:
  • Keep instructions in version control (Git)
  • Document changes in commits
  • Tag major versions
  • Can A/B test versions
  • Can roll back if new version performs worse
Mistake: Spending hours optimizing token usage before validating the agent works.Fix: First make it work. Then make it good. Then make it fast/cheap.Sequence:
  1. Make it work: Basic functionality, correct behavior
  2. Make it good: Refine quality, handle edge cases
  3. Make it efficient: Optimize tokens, cost, speed

Deployment Strategies

Phased Rollout

1

Internal Testing (Week 1)

  • Deploy to internal team only
  • Test with real scenarios
  • Gather feedback from colleagues
  • Fix critical issues
2

Beta Users (Week 2-3)

  • Deploy to 5-10% of users
  • Monitor closely
  • Rapid iteration based on feedback
  • Validate success metrics
3

Gradual Rollout (Week 4-6)

  • Increase to 25%, then 50%, then 75%
  • Watch for degradation or issues
  • Compare metrics to control group
  • Adjust as needed
4

Full Deployment (Week 7+)

  • Roll out to 100% of users
  • Continue monitoring
  • Iterate based on data
  • Celebrate success! 🎉

Rollback Strategy

Always have a rollback plan:

Rollback Procedures

Triggers for rollback:
  • Success metrics drop > 20%
  • Error rate increases significantly
  • Customer complaints spike
  • Critical bug discovered
  • Security issue identified
How to rollback:
  1. Switch traffic back to previous version
  2. Investigate root cause
  3. Fix issues in staging
  4. Re-test thoroughly
  5. Re-deploy when ready
Keep previous versions active for 1-2 weeks to enable quick rollback if needed.

Continuous Improvement

Weekly Optimization Routine

1

Monday: Review Metrics

  • Check success metrics vs. targets
  • Identify trends (improving or degrading?)
  • Flag anomalies
2

Tuesday: Review Conversations

  • Sample 10-20 conversations
  • Look for improvement opportunities
  • Note edge cases not handled well
3

Wednesday: Identify Improvements

  • Based on metrics and conversations
  • Prioritize by impact and effort
  • Select 1-2 improvements to implement
4

Thursday: Implement & Test

  • Update instructions
  • Test changes thoroughly
  • Prepare A/B test if significant change
5

Friday: Deploy & Monitor

  • Deploy improvements
  • Watch metrics closely
  • Gather early feedback

Monthly Deep Dive

Once per month, conduct a thorough review:
  • Review all metrics for the month
  • Compare to previous months
  • Identify trends
  • Calculate ROI
  • Total spend for the month
  • Cost per interaction
  • Most expensive agents
  • Optimization opportunities
  • ROI calculation
  • CSAT trends
  • Qualitative feedback themes
  • Feature requests
  • Pain points
  • Success stories
  • Error rates
  • Tool reliability
  • Response times
  • Token usage
  • Areas for technical improvement
  • What’s working well?
  • What needs improvement?
  • New use cases to explore?
  • Tools to add or remove?
  • Next quarter priorities

Success Stories & Patterns

What Great Agents Have in Common

Analyzing top-performing agents reveals common patterns:

Crystal Clear Purpose

They know exactly what they do and don’t do. No ambiguity.

Specific Instructions

Every guideline is concrete and actionable. No vague advice.

Rich Examples

Multiple examples of ideal responses for various scenarios.

Edge Case Coverage

Top 10-15 edge cases explicitly handled with example responses.

Right-Sized Tooling

Just enough tools to do the job. No more, no less.

Clear Escalation Path

Agents know when and how to escalate. No guessing.

Continuous Iteration

Updated weekly based on real performance data.

Measurable Success

Clear metrics that show impact and value.

Quick Reference Checklist

Use this checklist when building or optimizing agents:

Design

  • Agent has single, clear purpose
  • Instructions are specific and actionable
  • 2-3 complete example scenarios included
  • Top 5-10 edge cases handled explicitly
  • Success metrics defined clearly

Tools

  • Only essential tools connected
  • Each tool has clear usage guidelines
  • Tool authentication tested and working
  • Escalation path defined for tool failures

Configuration

  • Appropriate model selected for task complexity
  • Token limits right-sized to actual usage
  • Smart Context enabled
  • Prompt Optimization enabled
  • Reasonable reasoning step limit (10-15)

Testing

  • 10+ happy path scenarios tested
  • 5+ edge cases tested
  • Error conditions tested
  • Performance acceptable (speed and cost)
  • User experience validated

Deployment

  • Phased rollout plan in place
  • Rollback strategy defined
  • Monitoring dashboards set up
  • Alert thresholds configured

Maintenance

  • Weekly review scheduled
  • Monthly deep dive planned
  • Feedback collection process in place
  • Continuous improvement mindset

Next Steps

Create Your First Agent

Step-by-step tutorial

Prompt Engineering

Master instruction writing

Configuration Guides

Detailed configuration documentation

Tools & Connectors

Connect your systems