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

# Build Multi-Agent Workflows

> Attach existing MoEngage Custom Agents as sub-agents to a coordinator agent, so one session delegates work to specialists and consolidates the output.

A Custom Agent performs one well-defined job. A campaign workflow usually involves more than one: pulling campaign data, analyzing it, drafting a recommendation, and checking the result. Instead of building a single agent that handles all of it, attach existing agents to one **coordinator** agent as its **sub-agents**. The coordinator then assigns each part of the work to the relevant sub-agent and returns the results as one response.

<Note>
  If the **Sub Agents** section does not appear in the Agent Builder, contact your Customer Success Manager (CSM) to confirm availability for your workspace.
</Note>

## How Delegation Works

A coordinator is an ordinary Custom Agent with one addition: a list of sub-agents that sits alongside its tools. This list is the coordinator's **roster**. Everything else stays the same, including the create, configure, test, publish, edit, pause, and delete lifecycle described in [Create and Manage Custom Agents](/docs/user-guide/ai-and-intelligence/merlin-ai/custom-agents/create-and-manage-custom-agents).

Delegation follows these rules:

* **Delegation extends one level:** A coordinator delegates to the agents on its roster, and each sub-agent completes its assigned task directly. A sub-agent cannot delegate onward to sub-agents of its own.
* **A single session covers the entire workflow:** Running a coordinator opens one session. MoEngage runs the delegated work inside that session and records it as one task in the **All tasks** history.
* **The running user's permissions apply:** A sub-agent carries the tools its own creator assigned to it, but MoEngage authorizes each MoEngage data or campaign action against the permissions of the user who starts the session. A sub-agent that holds a write tool the running user does not hold cannot complete that action, so delegation never widens what a run reaches.
* **Sub-agents run concurrently:** The coordinator does not wait for one sub-agent to finish before it starts the next.

## Eligible Sub-Agents

You can add any **Live** agent that you can see: a public agent, including one your teammates built, or one of your own private agents. The **Sub Agents** picker lists only these agents, and you can add each one to a roster once. A roster holds up to 20 sub-agents.

The picker leaves out the following agents:

| Agent                                | Why you cannot add it                                                 |
| :----------------------------------- | :-------------------------------------------------------------------- |
| A Draft or paused agent              | Only a Live agent is ready to run a task on the coordinator's behalf. |
| Another user's private agent         | A private agent stays visible to its creator alone.                   |
| The agent you are editing            | An agent cannot delegate a task to itself.                            |
| An agent that already has sub-agents | Delegation extends one level only.                                    |

## Assign Sub-Agents

To attach sub-agents to an agent:

1. Open the agent in the Agent Builder. For a new agent, refer to [Create a Custom Agent](/docs/user-guide/ai-and-intelligence/merlin-ai/custom-agents/create-and-manage-custom-agents#create-a-custom-agent). For an existing published agent, go to **Manage** > **Edit** on the agent's detail page; for a Draft, click its card on the Custom Agents dashboard to open the builder.
2. In the right panel, locate the **Sub Agents** section below **Tools**.
3. Search for an agent by name and select it.
4. To check an agent before you add it, open its **Agent Info** view. Agent Info opens in a new browser tab and shows who created the agent, when they created it, and who last updated it.
5. Tell the coordinator how to use its sub-agents. In the instructions, name the sub-agent responsible for each part of the task, and state how the coordinator combines their results. A coordinator delegates only what its instructions describe. For guidance, refer to [Configure your Agent's Instructions](/docs/user-guide/ai-and-intelligence/merlin-ai/custom-agents/create-and-manage-custom-agents#configure-your-agents-instructions).
6. Run a **Test agent** session to confirm that each delegation behaves as expected, and then click **Make live**.

<Note>
  Adding an agent to a roster gives your coordinator the use of that agent, not control over it. To change a sub-agent, open it directly from the Custom agents dashboard. Only its creator can edit its configuration, change its visibility, or delete it.
</Note>

### Visibility Rules

MoEngage blocks you from adding another user's private agent to a roster, so a coordinator never delegates to an agent you cannot see.

Your own private Live agents remain eligible. Review a roster before you make a coordinator public, so that you know which of your agents the coordinator reaches. For more on visibility, refer to [Set Visibility](/docs/user-guide/ai-and-intelligence/merlin-ai/custom-agents/create-and-manage-custom-agents#set-visibility).

### Update a Roster

Each time you save a coordinator, MoEngage records the published version of every sub-agent on its roster. The coordinator keeps using those recorded versions, so a teammate who republishes a sub-agent does not change how your live coordinator behaves.

To use a sub-agent's latest version, open the coordinator in the builder, save it, and click **Make live**.

To take an agent off a roster, open the coordinator in the builder and remove the agent from the **Sub Agents** section.

<Note>
  MoEngage blocks the deletion of an agent for as long as it sits on any coordinator's roster, and names the coordinators that use it. Remove the agent from every roster that lists it, and then delete it. Refer to [Delete an Agent](/docs/user-guide/ai-and-intelligence/merlin-ai/custom-agents/create-and-manage-custom-agents#delete-an-agent).
</Note>

## Run a Coordinator

Start a coordinator using the same methods as any other agent: from the agent card, from the agent's detail page, or through **Test agent** in the builder. For details on starting, monitoring, and resuming a session, refer to [Run and Manage Agent Sessions](/docs/user-guide/ai-and-intelligence/merlin-ai/custom-agents/run-and-manage-agent-sessions).

A delegated run behaves as follows:

* The transcript shows the delegated work as it happens, with each sub-agent's messages indented under the coordinator's steps, so you can see which sub-agent handles which part of the task.
* Sub-agents share the coordinator's session, its attached files, and its credentials.
* A file that a sub-agent produces appears in the coordinator's session outputs, alongside the files the coordinator produces itself. Refer to [Session Outputs Panel](/docs/user-guide/ai-and-intelligence/merlin-ai/custom-agents/run-and-manage-agent-sessions#session-outputs-panel).
* The **All tasks** history records the run as one task, with a single transcript covering the coordinator and every sub-agent it calls.

<Warning>
  Review the tools you assign to every agent on the roster before you publish the coordinator. Delegated work follows the same rules as any other run: an agent with write tools makes real changes to your workspace, in Test runs as well as Live runs.
</Warning>

## FAQs

<AccordionGroup>
  <Accordion title="Can a sub-agent have sub-agents of its own?">
    No. Delegation extends one level. A coordinator delegates to its sub-agents, and each sub-agent completes its task directly. When you build a roster, the picker leaves out any agent that already has sub-agents.
  </Accordion>

  <Accordion title="Whose permissions does a sub-agent use?">
    The permissions of the user who starts the session. A sub-agent keeps the tools its own creator assigned to it, so a roster can list an agent that holds tools the coordinator itself does not. That list does not grant access: MoEngage checks each MoEngage data or campaign action against the running user's permissions, so a delegated write fails if that user cannot perform it themselves. For details, refer to [Custom Agent Essentials: Permissions and Security](/docs/user-guide/ai-and-intelligence/merlin-ai/custom-agents/custom-agents-essentials-permission-and-security).
  </Accordion>

  <Accordion title="I updated an agent that other coordinators use. Do those coordinators adopt my changes automatically?">
    No. Each coordinator uses the version of the sub-agent recorded at its last save. For a coordinator to use your update, its creator opens it in the builder, saves it, and clicks **Make live**.
  </Accordion>

  <Accordion title="Can I add a teammate's private agent to my agent's roster?">
    No. A roster accepts a teammate's agent only when that agent is public and Live. Your own private Live agents remain eligible. If your workflow needs what a teammate's private agent does, ask its creator to make the agent public.
  </Accordion>

  <Accordion title="Does MoEngage log a delegated run differently from a standard run?">
    No. The delegation runs inside the coordinator's single session, and MoEngage logs it as one task in the **All tasks** history with one transcript covering the coordinator and every sub-agent it calls.
  </Accordion>
</AccordionGroup>