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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alhena.gitbook.io/docs/ai-configuration/agents/custom-agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.