> 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/setup.md).

# Create and orchestrate teams

This page explains how to build an Agent Team from scratch: create a team, add agents on the canvas, configure connections and interaction types between them, designate the entry node, and start chatting with the entire team.

{% hint style="info" %}
**Prepare the AI assistants you want to add to the team first.** Each node in a team is an existing AI assistant, so create your specialized assistants (e.g., routing, order, returns agents) under "AI Assistants" first, then come back here to compose them into a team.
{% endhint %}

## <mark style="color:blue;">1. Create a team</mark> <a href="#create-team" id="create-team"></a>

### 1. Go to the team list <a href="#team-list" id="team-list"></a>

From the left menu, navigate to <mark style="color:blue;">AI Features</mark> > <mark style="color:blue;">Teams</mark>. The list shows all teams in your organization, including **team name, number of agents, and status**. Use the search bar in the upper right to find a team.

### 2. Create a team <a href="#new-team" id="new-team"></a>

Click <mark style="color:blue;">Create Team</mark> in the upper right corner, fill in the **Team name** (required) and **Description**, then create.

{% hint style="success" %}
After successful creation, the system automatically creates an **entry agent** and a corresponding **Web Chat channel** for this team, so you can chat with the entire team right away.
{% endhint %}

## <mark style="color:blue;">2. Orchestrate the team on the canvas</mark> <a href="#compose-canvas" id="compose-canvas"></a>

Click into a team to enter the default <mark style="color:blue;">Canvas Orchestration</mark> view. The screen is divided into three areas: the **Agent List** on the left, the **Canvas** in the center, and the **Settings Panel** on the right (appears when you select a node or connection).

{% hint style="warning" %}
**Canvas orchestration is best done on a desktop browser.** On small screens like mobile devices, the canvas area will show a prompt asking you to switch to desktop for orchestration.
{% endhint %}

### 1. Add agent nodes <a href="#add-nodes" id="add-nodes"></a>

In the <mark style="color:blue;">Agent List</mark> on the left, find the agent you want to add and **drag it onto the canvas**, or **click** it to add. Agents already in the team are labeled "Already in team" — clicking them will navigate to the corresponding node on the canvas. Use the search box at the top to filter when you have many agents.

Each node displays the agent name, the model it uses, and whether it is in <mark style="color:blue;">Agent</mark> or <mark style="color:blue;">RAG</mark> mode for easy identification.

{% hint style="info" %}
If node positions are messy, click <mark style="color:blue;">Auto Layout</mark> on the canvas to have the system rearrange them. Node positions are saved automatically.
{% endhint %}

### 2. Configure nodes <a href="#node-settings" id="node-settings"></a>

Click a node to open the <mark style="color:blue;">Node Settings</mark> panel on the right. You can adjust:

| Setting                  | Description                                                                                                                                                                                                                                                                       |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entry node**           | When enabled, the team starts processing conversations from this node. **A team can have only one entry node.**                                                                                                                                                                   |
| **Per-call token limit** | Limits the token count for a single response from this node (optional).                                                                                                                                                                                                           |
| **Max iteration count**  | Limits the number of iterations for a single processing cycle on this node (optional).                                                                                                                                                                                            |
| **Context strategy**     | Controls what this agent can see: "**Visible original user input**" determines whether it can read the user's original message (when off, it only sees the processed output from upstream agents); "**Visible output sources**" lets you specify which nodes' outputs it can see. |

### 3. Draw connections and set interaction types <a href="#add-edges" id="add-edges"></a>

Drag from one node's connection point to another node to create a **directed connection** (source -> target). Click the connection to open the <mark style="color:blue;">Connection Settings</mark> panel on the right:

| Setting                           | Description                                                                                                                                                                                    |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Trigger condition description** | Describe in plain language "when should this connection be used." This description is provided to the AI as a basis for routing decisions — writing it clearly helps improve routing accuracy. |
| **Interaction type**              | Choose <mark style="color:blue;">Auto</mark>, <mark style="color:blue;">Handoff</mark>, or <mark style="color:blue;">Delegate</mark> (see the table below for differences).                    |
| **Inherit source agent's tools**  | When enabled, the target agent can use all tools and resources from the source agent.                                                                                                          |

**Interaction types** (descriptions as shown in the settings panel):

| Interaction type   | Description                                                                                     |
| ------------------ | ----------------------------------------------------------------------------------------------- |
| **Auto (default)** | The LLM automatically determines the most suitable interaction type.                            |
| **Handoff**        | Hand off control — the source agent goes idle and the target agent takes over the conversation. |
| **Delegate**       | Delegate a task — the target agent executes and returns the result to the source.               |

{% hint style="info" %}
**Watch for semantic warnings at the top of the canvas.** When the team graph has issues, a yellow notice appears at the top of the canvas, such as: "No entry node set," "Multiple entry nodes — keep only one," "Duplicate connections," or "Connections form a cycle." It is recommended to resolve these warnings before starting a conversation.
{% endhint %}

## <mark style="color:blue;">3. Configure basic information and guardrails</mark> <a href="#settings-guardrails" id="settings-guardrails"></a>

In the team page, switch to the <mark style="color:blue;">Basic Information</mark> view to adjust team-level settings:

* **Basic information**: Team name, description, and whether it is enabled.
* **Guardrails**:
  * **Max iterations** (default `25`) — The maximum number of 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 user message.
  * **Timeout** (default `600` seconds) — The hard timeout for the entire team's processing flow.

## <mark style="color:blue;">4. Chat with the team</mark> <a href="#talk-to-team" id="talk-to-team"></a>

Once orchestration is complete and the team is "Enabled," you can chat with the entire team through the team's **Web Chat channel**. Users face a single entry point, and the system automatically routes questions to the appropriate agent.

When the team performs handoffs or delegates between agents, the chat interface displays transition messages such as "**Handing off to**," "**Delegating to**," or "**Switching to**," letting users know which agent is currently serving them.

## <mark style="color:blue;">5. Delete a team</mark> <a href="#delete-team" id="delete-team"></a>

In the danger zone at the bottom of the <mark style="color:blue;">Basic Information</mark> view, you can <mark style="color:blue;">Delete Team</mark>. Deleting a team also removes its entry agent, and **this action cannot be undone** — please confirm before proceeding.

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

Once the team is running, you can check the [Team execution traces](/maiagent-user-guide/maiagent-user-guide-en/teams/traces.md) to see which agents were involved in each execution, how many tokens each used, and how long it took — confirming the team is dividing work as expected.


---

# 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/setup.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.