> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/teams/teams.md).

# What is Agent Teams?

## <mark style="color:blue;">1. What is Agent Teams?</mark> <a href="#what-is-teams" id="what-is-teams"></a>

In the past, a single AI assistant had to handle everything: customer service routing, order inquiries, returns and exchanges, product recommendations — all crammed into one system prompt, one knowledge base, and one set of tools. As tasks piled up, this "jack-of-all-trades" assistant started dropping the ball — the system prompt grew too long, knowledge bases interfered with each other, and costs stayed high.

**Agent Teams lets you replace "one generalist" with "a group of specialists."** You can compose multiple existing AI assistants into a team, each with its own role (for example: a routing agent, an order agent, a returns agent, and a recommendation agent), then use a visual canvas to define "when should a question be handed to whom."

Users see **a single conversation entry point**; behind the scenes, the team automatically routes questions to the most suitable agent, as if the user were interacting with an entire professional team.

{% hint style="success" %}
**Value to you:** Each agent retains its own independent knowledge base, tools, and model settings without interference. Only the agent actually handling the question loads the relevant content, saving tokens and making each agent more focused and accurate. When you add a new business scenario, you simply add an agent node and draw a connection — no need to rewrite existing agents.
{% endhint %}

## <mark style="color:blue;">2. How is this different from "single agent + skills"?</mark> <a href="#vs-single-agent" id="vs-single-agent"></a>

| Aspect            | Single Agent (with Skills)                                    | Agent Teams                                                                                              |
| ----------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Division of work  | One agent handles all scenarios                               | Multiple agents each responsible for their area of expertise                                             |
| Knowledge & tools | All attached to the same agent, prone to interference         | Each agent independently owns its own knowledge base, tools, and model                                   |
| Model cost        | Only one model for all tasks                                  | Use lightweight models for simple tasks and powerful models for complex reasoning, configured separately |
| Collaboration     | Cannot hand off or delegate between agents                    | Supports **handoff** and **delegate** between agents                                                     |
| Scalability       | New scenarios require modifying the existing agent's settings | Just add a new node and draw a connection                                                                |

## <mark style="color:blue;">3. Three interaction types: Handoff, Delegate, Auto</mark> <a href="#interaction-types" id="interaction-types"></a>

Agents in a team collaborate through **connections (directed arrows)**. Each connection can be configured with an interaction type that determines "how control flows once the question reaches the other agent." The three types are explained below, with accompanying diagrams.

### Handoff <a href="#type-handoff" id="type-handoff"></a>

Handoff **transfers control of the entire conversation**: the source agent determines that someone else should handle this matter and passes the conversation to the target agent, who **takes over** and continues talking with the user — like a customer service rep transferring a call to another department, after which the new person takes over.

**Best for**: Parallel division of work where each agent handles its own domain. For example, a routing agent determines the user's intent and hands the conversation off to an order inquiry agent or a returns agent.

### Delegate <a href="#type-delegate" id="type-delegate"></a>

Delegate **outsources a subtask**: the source agent asks the target agent to handle something specific, the target agent completes it and **returns the result**, while control remains with the source agent — like a colleague looking up some data for you and reporting back, with you still being the one who compiles the final response.

**Best for**: Hierarchical collaboration. For example, a customer service agent receives an inventory check request, delegates the inventory query to a warehouse agent, and then compiles the response for the customer.

### Auto (Default) <a href="#type-auto" id="type-auto"></a>

Auto lets the AI **decide on the spot** whether to use handoff or delegate based on the current situation. Use this when you are not sure which type to choose or want to keep things flexible.

### Communication volume and cost differences across the three types <a href="#cost-comparison" id="cost-comparison"></a>

When multiple agents collaborate, the most common concern is: **will token costs spiral out of control?** The key lies in how much content is passed between agents across the three types:

| Aspect                            | Handoff                                                                              | Delegate                                                                                                                             | Auto                                                              |
| --------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------- |
| **Control**                       | Transferred to the target agent                                                      | Stays with the source agent                                                                                                          | Decided by the AI on the spot                                     |
| **Content passed between agents** | The target agent reads the accumulated conversation context when taking over         | The source agent only sends "one subtask" to the target agent — concise and well-scoped                                              | Depends on the type chosen                                        |
| **Token/cost characteristics**    | Grows with conversation length and number of handoffs; only one agent runs at a time | Adds a sub-agent run on top of the current turn (one extra LLM call), but the sub-agent's input is concise and scope is controllable | Falls on whichever type is selected, harder to predict in advance |
| **Predictability**                | Medium                                                                               | High (task scope is well-defined)                                                                                                    | Low (varies by situation)                                         |

{% hint style="success" %}
**Costs are controllable and observable.** The team has multiple built-in safeguards:

* **Max iterations** (default `25`): Limits how many times agents can go back and forth in a single conversation, preventing infinite loops.
* **Overall token limit** (default `200000`): The token budget cap for the entire team processing a single message.
* **Timeout**, and per-node configurable **per-call token limits**.
* **Context strategy**: Turn off "visible original user input" for a node so that agent only receives the summarized output from upstream agents rather than the full conversation, further saving tokens.
* **Execution traces**: Every execution records total tokens and **cost breakdown per agent**, making it clear where tokens are spent (see [Team execution traces](/maiagent-user-guide/maiagent-user-guide-en/teams/traces.md)).
  {% endhint %}

{% hint style="info" %}
**The conversation "remembers" who is currently serving.** After a handoff, the receiving agent continues serving the subsequent conversation until it determines another handoff is needed; the next message does not go back to the entry point for re-routing.
{% endhint %}

## <mark style="color:blue;">4. Typical use cases</mark> <a href="#scenarios" id="scenarios"></a>

* **E-commerce customer service team**: A routing agent determines intent and **hands off** to order / returns / recommendation agents, each with their own knowledge base and tools.
* **Enterprise internal helpdesk**: HR agent + IT agent + Finance agent, automatically routing employee questions to the appropriate desk.
* **Technical support team**: L1 agent performs initial troubleshooting, **delegates** to L2 agent for deeper analysis, and the result is returned to L1 for a compiled response.

## <mark style="color:blue;">5. How it works (concepts)</mark> <a href="#how-it-works" id="how-it-works"></a>

Agent Teams uses **a directed graph** to describe the team:

* **Nodes (agents)**: Each node on the graph is an existing AI assistant, carrying its own system prompt, knowledge base, tools, and model.
* **Entry node**: When the team receives a message, processing starts from this node. A team has exactly one entry node.
* **Connections (directed arrows)**: Define "from which agent, under what conditions, using which interaction type, to which agent."
* **Guardrails**: The team has upper limits for max iterations, overall token limit, and timeout to prevent agents from looping endlessly.

When you create a team, the system automatically creates an **entry agent** and a corresponding **Web Chat channel** for the team, allowing you to chat with the entire team directly through the channel.

## <mark style="color:blue;">6. Next steps</mark> <a href="#next-steps" id="next-steps"></a>

* Ready to create a team? See [Create and orchestrate teams](/maiagent-user-guide/maiagent-user-guide-en/teams/setup.md) — how to create a new team, drag in agent nodes, draw connections to set interaction types, designate an entry point, and start a conversation.
* Want to see how the team operates? See [Team execution traces](/maiagent-user-guide/maiagent-user-guide-en/teams/traces.md) — which agents were involved in each execution, how many tokens each used, and how long it took.

{% hint style="info" %}
**Prerequisite:** Agent Teams must be enabled by MaiAgent for your organization. If you do not see the "Teams" menu under "AI Features" in the admin panel, contact the MaiAgent team to activate it.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/maiagent-user-guide/maiagent-user-guide-en/teams/teams.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.