Agent Best Practices

Design, deploy, and maintain high-quality AI agents

Design, deploy, and maintain high-quality AI agents. This guide covers architectural patterns, common pitfalls, and proven strategies for success.

Design Principles

Single Responsibility

Each agent should have one clear purpose:

Good	Bad
Billing Support Agent	General Support Agent
Technical Troubleshooting Agent	”Does Everything” Agent
Onboarding Guide Agent	Customer Service Agent

A focused agent produces better responses, is easier to test and improve, has clearer escalation paths, and gives you more actionable analytics.

Clear Boundaries

Define what your agent can and cannot do:

## Agent: Product Support

CAN DO:
✓ Answer product feature questions
✓ Guide through common workflows
✓ Troubleshoot known issues
✓ Create support tickets

CANNOT DO:
✗ Access customer account data
✗ Process refunds or payments
✗ Provide legal advice
✗ Debug custom integrations

Graceful Degradation

Plan for what happens when the agent can’t help:

---

Multi-Agent Architecture

When to Use Multiple Agents

Consider multiple agents when:

• Different domains require different expertise
• Response styles should vary significantly
• Escalation paths differ between topics
• Permission requirements vary

Agent Routing Pattern

Use a main agent that delegates to specialists:

Implementation

Configure agent-as-tool for routing:

1. Create specialist agents
2. Create main agent with agent invocation tools
3. Add routing instructions to main agent’s prompt:

## Routing Rules

Analyze each user message and route appropriately:

- **Billing questions** (invoices, payments, subscriptions)
  → Use the Billing Agent tool

- **Technical issues** (bugs, errors, how-to)
  → Use the Technical Agent tool

- **Sales inquiries** (pricing, features, demos)
  → Use the Sales Agent tool

- **General questions** (company info, basic FAQs)
  → Handle directly

---

Knowledge Configuration

Source Selection

Choose knowledge sources strategically:

Agent Type	Recommended Sources
Product Support	Product docs, FAQs, troubleshooting guides
Sales	Feature pages, pricing, case studies
Technical	API docs, developer guides, code examples
HR/Internal	Policies, procedures, handbooks

Source Prioritization

When agents have multiple sources, configure priority:

1. High priority: Core documentation, FAQs
2. Medium priority: Detailed guides, tutorials
3. Low priority: Blog posts, announcements

Regular Updates

Establish a knowledge maintenance schedule:

Frequency	Action
Daily	Sync external connectors
Weekly	Review quality scores
Monthly	Audit outdated content
Quarterly	Full knowledge base review

---

Tool Configuration

Essential Tools

Most agents benefit from these tools:

Tool	Purpose	When to Enable
Ticketing	Human escalation	Always
Parameterized Search	Advanced retrieval	Complex knowledge bases
HTTP Request	External data	Integration needs
Agent Invocation	Delegation	Multi-agent setups

Tool Prompt Optimization

Write clear tool descriptions:

Weak:

Create a ticket for the user.

Strong:

Create a support ticket when:
- User explicitly requests human assistance
- Issue requires account-level access
- Problem cannot be resolved after troubleshooting

Before creating a ticket:
1. Summarize the issue
2. List troubleshooting steps already tried
3. Ask if user wants to proceed with ticket creation

Tool Limits

Set appropriate limits to prevent abuse:

• HTTP Request: Rate limit external API calls
• Agent Invocation: Limit delegation depth
• Ticketing: Require minimum context before creation

---

Permission Strategy

User Segmentation

Match agents to user segments:

User Segment	Agent
Anonymous Users	Public FAQ Agent
Free Users	Basic Support Agent
Paid Users	Premium Support Agent
Enterprise	Dedicated Account Agent

Permission Inheritance

Structure permissions hierarchically:

Default Permissions

Configure sensible defaults:

• Anonymous: Access to public-facing agents only
• Authenticated: Access to appropriate tier agents
• Admin: Access to all agents for testing

---

Testing Strategy

Test Coverage

Cover these scenarios:

Scenario	Purpose
Happy path	Verify core functionality
Edge cases	Handle unusual inputs
Escalation	Verify handoff to humans
Tool usage	Confirm correct tool invocation
Off-topic	Maintain focus on scope
Adversarial	Resist manipulation

Simulation Testing Workflow

1. Define test dataset
2. Create test cases with expected outcomes
3. Run simulation
4. Review results
5. Identify failures
6. Update prompt or knowledge
7. Re-run simulation
8. Repeat until satisfactory

Regression Testing

Before any production change:

1. Run full test suite
2. Compare scores to baseline
3. Investigate any regressions
4. Only deploy if quality maintained

---

Quality Monitoring

Key Metrics

Metric	Description	Target
CX Score	Overall quality	>80
Resolution Rate	Resolved without human	>70%
First Response Accuracy	Correct first try	>85%
Escalation Rate	Sent to humans	less than 20%

Thread Evaluator Usage

Enable Thread Evaluator for continuous monitoring:

1. Configure evaluation criteria
2. Set dimension weights
3. Review daily summaries
4. Act on flagged conversations

Feedback Loop

---

Common Pitfalls

Pitfall	What goes wrong	Fix
Over-engineering	Agent tries to handle too many scenarios	Start simple, add complexity only when needed
Vague instructions	Prompt lacks specific guidance	Use concrete examples and explicit rules
Missing escalation	No clear path to human help	Always include escalation criteria and tools
Stale knowledge	Documentation becomes outdated	Automated sync + regular audits
Ignoring analytics	Deploying without monitoring	Enable Thread Evaluator, review weekly

---

Deployment Checklist

Pre-Launch

• Prompt template finalized and reviewed
• Knowledge sources connected and synced
• Tools configured and tested
• Permissions set correctly
• Simulation tests passing
• Escalation path verified

Launch

• Enable for limited user group first
• Monitor initial conversations
• Check for unexpected issues
• Gather early feedback

Post-Launch

• Enable Thread Evaluator
• Set up alerting for low scores
• Schedule regular reviews
• Document learnings

---

Performance Tips

Response Quality

• Use specific examples in prompts
• Include format guidelines
• Define tone explicitly
• Test with real user questions

Response Speed

• Choose appropriate LLM model
• Use fast model for simple tasks
• Optimize knowledge source size
• Enable reranker for precision

Cost Efficiency

• Match model to complexity
• Limit token usage where possible
• Use caching for common queries
• Monitor usage patterns

---

Related

• Agents — Agent configuration reference
• Prompt Engineering — Prompt writing techniques
• Simulation Testing — Test your agents
• Thread Evaluator — Monitor conversation quality
• Router Agent — Automatic message routing to specialist agents