> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```markdown theme={null}
## 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:

```mermaid theme={null}
flowchart TD
    A[User Question] --> B{Can agent help?}
    B -->|Yes| C[Help]
    B -->|No| D[Acknowledge limitation<br>+ escalate]
```

***

## 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:

```mermaid theme={null}
flowchart TD
    A[User Message] --> B[Main Agent<br>Router]
    B --> C[Billing Agent]
    B --> D[Tech Agent]
    B --> E[Sales Agent]
```

### 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:

```markdown theme={null}
## 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:

```mermaid theme={null}
flowchart TD
    subgraph Organization
        A[basic_access] --> A1[faq_agent]
        B[paid_access] --> B1[faq_agent]
        B --> B2[support_agent]
        C[enterprise_access] --> C1[faq_agent]
        C --> C2[support_agent]
        C --> C3[account_agent]
    end
```

### 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

```mermaid theme={null}
flowchart TD
    A[Evaluation Results] --> B[Identify Issues]
    B --> C[Prompt Update]
    B --> D[Knowledge Gap]
    C --> E[Retest & Deploy]
    D --> E
```

***

## 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/agents) — Agent configuration reference
* [Prompt Engineering](./prompt-engineering) — Prompt writing techniques
* [Simulation Testing](../features/simulation-testing) — Test your agents
* [Thread Evaluator](../features/thread-evaluator) — Monitor conversation quality
* [Router Agent](../agent/router) — Automatic message routing to specialist agents