> For the complete documentation index, see [llms.txt](https://docs.artific.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.artific.nl/en/for-administrators/assistants/sub-agents.md).

# Sub-agents

How to let one assistant hand a question to another. Configured in the **Sub-agents** section of an assistant's settings.

## What sub-agents are for

A single assistant that tries to cover everything ends up with a long, contradictory set of instructions and mediocre answers in every area. The alternative is a small team: one assistant that users talk to, which quietly passes questions to specialists.

The assistant users talk to is the **supervisor**. The specialists are its **sub-agents**. From the user's point of view there is one conversation. They never have to know which assistant they are being helped by.

An example. An internal helpdesk assistant is the supervisor. It has three sub-agents:

| Sub-agent            | Handles                               |
| -------------------- | ------------------------------------- |
| HR assistant         | Leave, salary, staff policy           |
| IT assistant         | Accounts, hardware, software requests |
| Facilities assistant | Buildings, desks, access passes       |

The supervisor decides where each question goes.

## Adding a sub-agent

1. Open the supervising assistant's **Settings**.
2. Scroll to **Sub-agents** and choose **Choose sub-agent**.
3. Pick an assistant from the list.
4. Fill in **When to use this sub-agent**. This is required.
5. Optionally set a **Progress message**.
6. **Save**.

### When to use this sub-agent

The supervisor reads this description to decide whether to hand over. It is the only thing it has to go on, so be concrete and behavioural:

* Good: *"when the user asks about billing, invoices, payment terms or refunds"*
* Poor: *"finance stuff"*

List the actual words a user would use. Overlapping descriptions cause questions to go to the wrong specialist, so make the boundaries clear.

### Progress message

An optional line shown in the chat while the supervisor consults this sub-agent, such as *"Checking with the finance team…"*. It can be set per language. Leave it empty and the platform shows a default message naming the sub-agent.

## Rules and limits

* The picker hides any assistant that would create a loop, so an assistant cannot end up delegating to itself through a chain.
* Any sub-agent with an empty description blocks saving. You are told which rows are incomplete.
* If a sub-agent is restricted to certain user groups, users outside those groups will not have their question handed over. The supervisor answers instead. The row shows a **Restricted access** badge.
* The supervisor's model must support tools. If it does not, the settings screen warns you.

## Designing a good set

* **Keep the supervisor thin.** Its job is routing and general conversation, not answering everything.
* **Give each sub-agent one clear area** with its own instructions and its own knowledge.
* **Make descriptions mutually exclusive.** If two descriptions could both match a question, the routing becomes unpredictable.
* **Test with real questions.** Use the **Preview** tab and ask the awkward, in-between questions your users will actually ask.
* **Restrict what should be restricted.** A sub-agent inherits nothing from the supervisor's access rules; set its own group restrictions deliberately.