> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/ai-configuration/agents/custom-agents.md).

# Custom Agents

Custom agents let you extend Alhena AI with specialized behaviors tailored to your business. Create custom agents when you need functionality beyond what built-in agents provide.

## When to Create a Custom Agent

Consider creating a custom agent when you need to:

* **Handle specialized queries** - Create an agent for a specific domain like warranty claims, technical troubleshooting, or appointment scheduling
* **Integrate with custom APIs** - Connect to your internal systems or third-party services not covered by built-in integrations
* **Implement complex workflows** - Define multi-step processes that require specific tools and logic
* **Separate concerns** - Isolate specific functionality with its own set of guidelines

## Creating a Custom Agent

Navigate to **AI Settings > Agents** and click **Create Agent** to add a new custom agent.

### Name

Choose a descriptive name that clearly identifies the agent's purpose. This name appears in the Agents list and helps you identify the agent when assigning guidelines.

**Examples:**

* "Warranty Claims Agent"
* "Store Locator Agent"
* "Technical Support Agent"

### Description

Write a clear description of what the agent does and when it should be activated. The planner uses this description to route customer queries to the appropriate agent.

**Good descriptions:**

* "Handles warranty claims and repair requests for products within the warranty period"
* "Helps customers find nearby store locations and check store hours"
* "Provides technical troubleshooting for software installation and configuration issues"

**Tips for effective descriptions:**

* Be specific about the types of queries this agent should handle
* Mention key topics or keywords the agent should respond to
* Describe what makes this agent different from other agents

### Assigning Tools

Tools extend what your agent can do. Select the tools this agent needs to complete its tasks.

Available tool types:

| Tool Type    | Description                                  | Plan |
| ------------ | -------------------------------------------- | ---- |
| API Tools    | Connect to external HTTP APIs                | Pro  |
| MCP Servers  | Model Context Protocol integrations          | Pro  |
| Sheet Search | Search spreadsheets from your knowledge base | All  |

See [Agent Tools](/docs/ai-configuration/agents/tools.md) for details on configuring each tool type.

### Adding Guidelines

After creating your agent, add guidelines to define its behavior. Guidelines tell the agent how to respond in specific situations.

Navigate to **AI Settings > Guidelines** to create guidelines, then assign them to your custom agent in the agent assignment field.

See [Guidelines](/docs/ai-configuration/tuning/guidelines.md) for details on creating effective guidelines.

## Best Practices

### Keep agents focused

Each agent should have a clear, well-defined purpose. If an agent is handling too many different types of queries, consider splitting it into multiple specialized agents.

### Write clear descriptions

The planner relies on agent descriptions to route queries correctly. Vague descriptions lead to incorrect routing. Be specific about what the agent handles.

### Test routing thoroughly

After creating a custom agent, test various customer queries to ensure they route to the correct agent. Use the playground in your dashboard to verify routing behavior.

### Start simple

Begin with a minimal agent configuration and add complexity as needed. It's easier to add guidelines and tools incrementally than to debug an overly complex agent.