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

# Agent Grouping

Agent Grouping allows you to bundle multiple specialized agents under a single main agent.\
This enables users to dynamically switch between experts within the same chat interface, based on context.

With Agent Grouping, users can:

* Switch between agents dynamically inside the chat widget
* Interact with each agent’s unique knowledge base
* Optimize token usage by isolating prompts per sub-agent
* Organize agents for specialized tasks (e.g., Interviewer, Excel helper, Pronunciation coach)

***

## What is a Main Agent?

The **Main Agent** acts as the anchor. Other agents (called **Linked Agents**) will be accessed through the main agent’s widget.

Each Linked Agent:

* Is independently configured
* Has its own datastore and knowledge
* Can be selected in the frontend chat widget for specialized responses

***

## Requirements

Before setting up grouping:

* All agents (main and sub-agents) must be **set to live**
* Each agent should have at least one valid datastore
* Grouping must be **explicitly enabled** in the Main Agent’s channel config

***

## How to Group Agents

<Steps>
  <Step title="Create and activate your agents">
    Go to <strong>My Agents</strong> and ensure all agents you want to group are created and active.

    <Frame caption="My Agents: All agents live and ready for grouping">
      <img src="https://mintcdn.com/aptlytechnologies/Oomvhw_D5bjA43Sl/images_new/agentsconsole/grouping/chooseagent.png?fit=max&auto=format&n=Oomvhw_D5bjA43Sl&q=85&s=1249c871d64b28a2eebdc935cba7511c" alt="My Agents: All agents live and ready for grouping" width="2000" height="1066" data-path="images_new/agentsconsole/grouping/chooseagent.png" />
    </Frame>
  </Step>

  <Step title="Open the main agent playground">
    Select the agent that will act as the <strong>Main Agent</strong> and navigate to the <strong>Channels</strong> tab.

    <Frame caption="Channels: Navigate to Main Agent’s playground">
      <img src="https://mintcdn.com/aptlytechnologies/Oomvhw_D5bjA43Sl/images_new/agentsconsole/grouping/agentgrouping.png?fit=max&auto=format&n=Oomvhw_D5bjA43Sl&q=85&s=bc14d9608c4e9053a027c73d851fe578" alt="Channels: Navigate to Main Agent’s playground" width="2000" height="1066" data-path="images_new/agentsconsole/grouping/agentgrouping.png" />
    </Frame>
  </Step>

  <Step title="Enable Agent Grouping">
    Scroll to the <strong>Agent Grouping</strong> section and toggle “Enable Grouping”.

    <Frame caption="Enable Grouping: Toggle to activate agent grouping mode">
      <img src="https://mintcdn.com/aptlytechnologies/Oomvhw_D5bjA43Sl/images_new/agentsconsole/grouping/linkagent.png?fit=max&auto=format&n=Oomvhw_D5bjA43Sl&q=85&s=a4f3fa76ae9166dd8e8c1dc186332c50" alt="Enable Grouping: Toggle to activate agent grouping mode" width="2000" height="1066" data-path="images_new/agentsconsole/grouping/linkagent.png" />
    </Frame>
  </Step>

  <Step title="Set the Main Agent">
    Once grouping is enabled, the selected agent is tagged as the <strong>Main Agent</strong>.\
    Click <strong>Link Agent</strong> to start selecting sub-agents.

    <Frame caption="Link Agents: Assign specialized sub-agents to the main agent">
      <img src="https://mintcdn.com/aptlytechnologies/Oomvhw_D5bjA43Sl/images_new/agentsconsole/grouping/agentselect.png?fit=max&auto=format&n=Oomvhw_D5bjA43Sl&q=85&s=176df76969a8c47212171c630e76a742" alt="Link Agents: Assign specialized sub-agents to the main agent" width="2000" height="1066" data-path="images_new/agentsconsole/grouping/agentselect.png" />
    </Frame>
  </Step>

  <Step title="Select Linked Agents">
    Only active agents are shown in the dropdown. Select the agents you want to group and click <strong>Link Agent</strong>.

    <Frame caption="Dropdown: Select which agents to group under the Main Agent">
      <img src="https://mintcdn.com/aptlytechnologies/Oomvhw_D5bjA43Sl/images_new/agentsconsole/grouping/linkmybot.png?fit=max&auto=format&n=Oomvhw_D5bjA43Sl&q=85&s=f8d499cd06bc76c3982d79be03e39a3d" alt="Dropdown: Select which agents to group under the Main Agent" width="2000" height="1066" data-path="images_new/agentsconsole/grouping/linkmybot.png" />
    </Frame>

    Once you've selected your desired agents, they will be listed as part of the agent group under the main agent.

    <Frame caption="Success: Agents added to the group successfully">
      <img src="https://mintcdn.com/aptlytechnologies/Oomvhw_D5bjA43Sl/images_new/agentsconsole/grouping/linkedagent.png?fit=max&auto=format&n=Oomvhw_D5bjA43Sl&q=85&s=e5779a93940ff8f21ddc914fc967e5a1" alt="Success: Agents added to the group successfully" width="2000" height="1066" data-path="images_new/agentsconsole/grouping/linkedagent.png" />
    </Frame>
  </Step>

  <Step title="Chat Widget Experience">
    When the widget is loaded for the main agent, users can switch between all linked agents in real-time based on context.

    <Frame caption="Widget View: Switch between grouped agents at runtime">
      <img src="https://mintcdn.com/aptlytechnologies/Oomvhw_D5bjA43Sl/images_new/agentsconsole/grouping/chattest.png?fit=max&auto=format&n=Oomvhw_D5bjA43Sl&q=85&s=442d655a77364ea8799bf6dbdb814e30" alt="Widget View: Switch between grouped agents at runtime" width="2000" height="1066" data-path="images_new/agentsconsole/grouping/chattest.png" />
    </Frame>
  </Step>
</Steps>

***

## Tips & Notes

* Sub-agents do **not share** knowledge across the group.
* Switching agents does **not reset** the conversation unless designed to.
* Each sub-agent retains its independent model and prompt style.

***

## ✅ Example Use Cases

***

### 🧑‍💼 HR Assistant Suite

* **Main Agent**: *Job Application Guide*
* **Linked Agents**:
  * 📄 *Resume Reviewer* – Analyzes uploaded resumes and offers formatting or content improvements.
  * 🧪 *Interview Simulator* – Conducts mock interviews tailored to job roles.
  * 📬 *Offer Negotiator* – Helps craft polite counteroffers and answers negotiation-related queries.

**Why this works**:\
Candidates receive end-to-end job search support within a single chat interface — from resume polishing and interview practice to final-stage negotiation help.

***

### 🧑‍🎓 AI Student Mentor

* **Main Agent**: *Academic Coach*
* **Linked Agents**:
  * 📚 *Math Problem Solver* – Provides step-by-step solutions for algebra, calculus, and statistics problems.
  * 🧪 *Science Explainer* – Simplifies complex physics, chemistry, or biology concepts into digestible chunks.
  * 📝 *Essay Feedback Agent* – Reviews written submissions and suggests grammar and clarity improvements.

**Why this works**:\
Students can switch between topic-specific AI mentors to support homework, exam prep, and writing — without breaking flow or opening separate tools.

***