> For the complete documentation index, see [llms.txt](https://doc.aissist.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.aissist.io/tutorial/add-sub-agents.md).

# Add Sub Agents

Create an Aissist sub-agent for one scenario - its detection trigger, scenario, instructions, linked assets and actions, options and controls - by describing it or by hand.

*Last updated: October 25, 2026*

A sub-agent handles one scenario, such as order tracking, returns or billing. It is detected from the conversation, adds its own instructions, uses its own assets and actions, and can hand over or stop. This page shows how to create one and set each part.

For what sub-agents are and why they matter, see [Sub Agents](https://doc.aissist.io/capabilities/sub-agents.md).

### Create a sub-agent by describing it

{% stepper %}
{% step %}

### Open Create a sub-agent

Go to **Workspace → Sub Agents** and click **Add Sub Agent**.
{% endstep %}

{% step %}

### Say what it is for

Under **What is it for?**, describe in your own words what customers come to you wanting in this situation, and how you want it handled. For example:

> Items that arrive damaged - take the order number and photos, explain the replacement window, hand over if they want a refund instead.

Click **Confirm**. Aissist reads your existing sub-agents and searches your knowledge, then writes the sub-agent. This takes up to a minute, and you can watch each step.
{% endstep %}

{% step %}

### Review the draft

The draft shows the sub-agent's name, scenario and instruction, the **Assets it can read** and the **Actions it can call**. **Changed to make it valid** lists anything adjusted, such as a name already taken. **Worth knowing** lists what you should check before creating it.

Choose whether to **Switch it on when created**, then click **Create sub-agent**. Nothing is created before that.
{% endstep %}
{% endstepper %}

Already know exactly what you want? Click **Write it myself instead** for the form.

### Set up a sub-agent

Open a sub-agent from the list to edit it. It has five tabs: **Settings**, **Assets**, **Actions**, **Options** and **Control**.

#### Settings

* **Name**: a short tag name, such as `order_tracking`. It also becomes a tag in your help desk when the sub-agent is activated.
* **Detection Trigger**:
  * **Inbound**: triggered by the customer's message. Use it for intents such as returns or order status.
  * **Outbound**: triggered by the agent's reply. Use it for outcomes such as a transfer to a person.
* **Scenario Description**: the situation that activates it, in plain words. For example: `user wants to make a return`, `user asks where their order is`, `user wants to cancel an order`.
* **Instruction**: how to handle the scenario. It applies only once the sub-agent is activated. For example: ask for the order number, check the return reason, share the return policy, tell the customer a person will review the request.
* **Triggered by Multimedia?**: turn on only when the scenario is recognized from a customer's image. It can add processing time.

#### Assets

Link the knowledge this scenario needs. Click **Link Asset** to pick an existing asset, or **Add Asset** to create one for this sub-agent. For example, link a return policy page to `order_return`.

Linking keeps each scenario focused: unrelated content stays out of its replies. See [Add Assets](https://doc.aissist.io/tutorial/add-assets.md).

#### Actions

Click **Link Action** to give the sub-agent the actions it needs, such as a Shopify `getOrder` for `order_tracking`.

* **Entry Actions** run when an inbound sub-agent is activated.
* **Exit Actions** run when an outbound sub-agent is activated, or when an inbound one ends.

Outbound sub-agents can only have exit actions. See [Add Actions](https://doc.aissist.io/tutorial/add-actions.md).

#### Options

All optional:

* **Acknowledgement**: a message sent the first time the sub-agent is activated, such as a notice or a confirmation that the request was received.
* **Summary**: instructions for a summary written the first time the sub-agent is activated. The summary is sent to your help desk as a note. For example, an eSIM sales sub-agent could collect:

```json
{
  "destination": "where the customer is travelling",
  "number_of_days": "how many days they will travel",
  "number_of_esim": "how many eSIMs they want"
}
```

* **Context**: extra information available to the sub-agent once it is detected.
* **Task**: what must be done before handing over. The agent will not hand over until the tasks are done.

#### Control

These are rarely needed. Use them with care:

* **No Response for Current Interaction**: the agent does not reply to this message. Useful for spam, no-reply emails and out-of-office messages.
* **No Response After Current Interaction**: the agent replies this time, then stops replying in this conversation. Combine it with handover rules in your gateway to send the conversation to the right team.
* **Close**: closes the ticket or conversation in your help desk and ends all interactions.

### Related settings

* **Respond Only to Tagged**: the agent replies only when at least one sub-agent recognizes the message. Set it on the **Sub Agents** list or in **Workspace → Setting**. Recommended only for email.
* **Handover rules in your gateway**: choose a sub-agent and the team that should receive its conversations, so billing, returns or technical cases each reach the right team. See [Deploy](https://doc.aissist.io/tutorial/deploy.md) and [Escalation and Handover](https://doc.aissist.io/capabilities/escalation-and-handover.md).
* **Tags in your help desk**: each activated sub-agent becomes a tag on the ticket or conversation, which your help desk can use for its own workflows, automation and reports.
* **Copy**: copy a sub-agent to another workspace from its page.

### Test it

Open [Try](https://doc.aissist.io/tutorial/try.md) and send a message that should activate the sub-agent. The reply shows **Sub-agents** with the ones activated and why. Send one that should not, too, to check it stays quiet.

### Do it with Ask Engine

**Add Sub Agent** is Ask Engine. It reads what your workspace already has, so the new sub-agent does not duplicate one you have, uses a valid name, and links only assets and actions that exist. You review it before it is created.

> Refund requests - check the order and the refund policy, create a refund ticket in the help desk, and say when to expect the money.

> Pre-sales questions about which plan fits, and what the differences are.

In **Ask**, you can also find out which sub-agents need work:

> Which sub-agents escalate most, and what is missing that would let the AI finish the job?

See [Ask Engine](https://doc.aissist.io/capabilities/ask.md).

### Best practice

* Start with a few high-value sub-agents, one per major workflow. Add more as real conversations show the need.
* Give each sub-agent one clear scenario, written the way customers put it.
* Keep scenario instructions in the sub-agent, not in the workspace instruction.
* Link only the assets and actions the scenario needs.
* Leave the **Control** settings off unless you mean them.

### Related

* [Sub Agents](https://doc.aissist.io/capabilities/sub-agents.md)
* [Instructions and Information](https://doc.aissist.io/capabilities/instructions-and-information.md)
* [Try](https://doc.aissist.io/tutorial/try.md)
