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

# Agent Teams

Agent Teams：多 Agent 協作。把多個各有專長的 Agent 組成團隊，透過「移交」與「委派」讓一個 Agent 呼叫另一個 Agent（子 Agent）自動分工——使用者只跟一個入口對話，系統就把問題交給最合適的 Agent。

## <mark style="color:blue;">一、什麼是 Agent Teams？</mark> <a href="#what-is-teams" id="what-is-teams"></a>

過去一個 Agent 要包辦所有事情：客服分流、訂單查詢、退換貨、商品推薦，全塞進同一組角色指令、同一個知識庫、同一批工具。任務一多，這個「全能助理」就開始顧此失彼——角色指令太長、知識庫互相干擾、成本也降不下來。

**Agent Teams 讓你改用「一群專才」取代「一個通才」。** 你可以把多個既有的 Agent 組成一個團隊，讓每個 Agent 各司其職（例如：分流 Agent、訂單 Agent、退換貨 Agent、推薦 Agent），再用視覺化畫布定義它們之間「什麼時候該把問題交給誰」。

使用者只會看到**一個對話入口**；在背後，團隊會自動把問題路由給最適合的 Agent 來回答，就像在跟一整個專業團隊互動。

{% hint style="success" %}
**對你的價值：** 每個 Agent 保有獨立的知識庫、工具與模型設定，互不干擾；只有真正處理問題的 Agent 才載入相關內容，省 Token、也讓每個 Agent 更專注、答得更準。新增業務場景時，只要加一個 Agent 節點、拉一條連線，不用重寫既有 Agent。
{% endhint %}

## <mark style="color:blue;">二、和「單一助理 + 技能」有什麼不同？</mark> <a href="#vs-single-agent" id="vs-single-agent"></a>

| 面向    | 單一 Agent（含技能）          | Agent Teams               |
| ----- | ---------------------- | ------------------------- |
| 分工    | 一個 Agent 處理所有情境        | 多個 Agent 各自負責專長領域         |
| 知識與工具 | 全部掛在同一個 Agent 上，容易互相干擾 | 每個 Agent 獨立擁有自己的知識庫、工具與模型 |
| 模型成本  | 只能用一個模型應付所有任務          | 簡單任務用輕量模型、複雜判斷用強模型，分開配置   |
| 協作方式  | 無法在 Agent 之間移交或委派      | 支援 Agent 之間的**移交**與**委派** |
| 擴充    | 新情境要改動既有 Agent 的設定     | 新增一個節點與一條連線即可             |

## <mark style="color:blue;">三、三種互動方式：移交、委派、自動</mark> <a href="#interaction-types" id="interaction-types"></a>

團隊裡的 Agent 透過\*\*連線（有向箭頭）\*\*彼此協作。每條連線可以設定一種互動方式，決定「問題到了對方手上之後，控制權怎麼走」。以下三種方式，可對照示意圖理解。

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

移交是把整段對話的控制權**交出去**：來源 Agent 判斷這件事該由別人處理，就把對話交給目標 Agent，由對方**接手繼續**跟使用者對話——就像客服把電話轉接給另一個部門，之後就由接手的人服務。

**適合情境**：各司其職的平行分工。例如分流 Agent 判斷使用者的意圖後，把對話移交給訂單查詢 Agent 或退換貨 Agent 接手處理。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-b4bdcab485a980765804effea04ffbd7e0f7fad3%2Fteams-concept-handoff.png?alt=media" alt="移交示意圖：來源 Agent 把對話控制權交給目標 Agent 接手"><figcaption><p>移交：來源 Agent 交出控制權，目標 Agent 接手繼續與使用者對話</p></figcaption></figure>

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

委派是把一個子任務**外包**出去：來源 Agent 請目標 Agent 處理某件事，目標 Agent 做完把**結果回傳**，控制權仍留在來源 Agent 手上——就像同仁幫你查了一份資料回報給你，最後仍由你彙整回覆。

**適合情境**：階層式協作。例如客服助理收到查庫存的需求，委派倉儲 Agent 查詢庫存後，再由客服助理彙整回覆客戶。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-6c884168d164fa8f6171dcc0a853adb3525cfb08%2Fteams-concept-delegate.png?alt=media" alt="委派示意圖：來源 Agent 外包子任務給目標 Agent 並取回結果"><figcaption><p>委派：來源 Agent 把子任務交給目標 Agent，取回結果後自己彙整回覆</p></figcaption></figure>

### 自動（預設） <a href="#type-auto" id="type-auto"></a>

自動是交給 AI **依當下情況自行判斷**該用移交還是委派。當你不確定該用哪一種、或希望保留彈性時，就用自動。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-9fb6d9b2817640519f728da4c5a9f8847470b799%2Fteams-concept-auto.png?alt=media" alt="自動示意圖：AI 依情況自行決定要移交還是委派"><figcaption><p>自動：由 AI 依當下情況，自行決定要移交還是委派</p></figcaption></figure>

### 三種方式的溝通量與成本差異 <a href="#cost-comparison" id="cost-comparison"></a>

多個 Agent 協作，最常見的疑慮是：**這樣 token 成本會不會失控？** 關鍵在於三種方式「Agent 之間會傳遞多少內容」不同：

| 面向               | 移交                              | 委派                                                   | 自動                 |
| ---------------- | ------------------------------- | ---------------------------------------------------- | ------------------ |
| **控制權**          | 交給目標 Agent 接手                   | 留在來源 Agent                                           | 由 AI 當下決定          |
| **Agent 間傳遞的內容** | 目標 Agent 接手時，會讀到目前累積的對話脈絡       | 來源 Agent 只把「一個子任務」交給目標 Agent，範圍精簡明確                  | 視當下選擇而定            |
| **Token／成本特性**   | 隨對話長度與移交次數增加；同一時間只有一個 Agent 在運作 | 在原本這一輪之外，多跑一段子 Agent（多一次 LLM 呼叫），但子 Agent 的輸入精簡、範圍可控 | 落在被選中的那種方式上，較難事先預估 |
| **可預測性**         | 中                               | 高（任務範圍明確）                                            | 低（依情況變動）           |

{% hint style="success" %}
**成本是可控、也可觀測的。** 團隊內建多道防線：

* **最大迭代數**（預設 `25`）：限制一次對話中，Agent 之間最多來回幾次，避免無限循環。
* **整體 Token 上限**（預設 `200000`）：整個團隊處理單則訊息的 Token 預算上限。
* **逾時秒數**、以及每個節點可各自設定的**此節點單則訊息的 Token 上限**。
* **上下文策略**：把某個節點的〈可見原始使用者輸入〉關掉，該 Agent 就只會收到上游整理過的摘要，而非完整對話，可進一步省 Token。
* **執行記錄**：每一次執行都記錄總 Token 與**各 Agent 的成本分攤**，花在哪個 Agent 一目了然（見 [團隊執行記錄](/build/teams/traces.md)）。
  {% endhint %}

{% hint style="info" %}
**對話會「記住」目前是誰在服務。** 一次移交之後，接手的 Agent 會繼續服務接下來的對話，直到它判斷需要再移交出去為止；下一則訊息不會又回到入口重新分流。
{% endhint %}

## <mark style="color:blue;">四、典型應用場景</mark> <a href="#scenarios" id="scenarios"></a>

* **電商客服團隊**：分流 Agent 判斷意圖 → **移交**給訂單／退換貨／推薦 Agent，每個 Agent 用自己的知識庫與工具處理。
* **企業內部諮詢**：HR Agent + IT Agent + 財務 Agent，依員工提問自動分流到對應窗口。
* **技術支援團隊**：L1 Agent 初步排查 → **委派** L2 Agent 深入分析 → 結果回傳 L1 統整後回覆。

## <mark style="color:blue;">五、運作原理（概念）</mark> <a href="#how-it-works" id="how-it-works"></a>

Agent Teams 以**一張有向圖**來描述團隊：

* **節點（Agent）**：圖上的每個節點就是一個既有的 Agent，帶著它自己的角色指令、知識庫、工具與模型。
* **入口節點**：團隊收到訊息時，從這個節點開始處理對話，再依分流指令移交給合適的成員。新建立的團隊會自動帶一個內建入口節點，不需要另外指定；一個團隊只會有一個入口節點。
* **連線（有向箭頭）**：定義「從哪個助理、在什麼條件下、用哪種互動方式，交給哪個助理」。
* **安全護欄**：整個團隊有最大迭代數、整體 Token 上限與逾時秒數的上限，避免 Agent 之間無限來回。護欄把回覆停下來時，使用者看到的訊息可以自訂（見[安全護欄自訂訊息](/build/teams/setup.md#guardrail-stop-message)）。

建立團隊時，系統會自動幫這個團隊建立**入口**與對應的 **Web Chat 對話平台**，你可以直接透過對話平台與整個團隊對話。入口的模型、分流指令與知識庫在團隊畫布上設定（見[設定入口](/build/teams/setup.md#entry-settings)）。

## <mark style="color:blue;">六、下一步</mark> <a href="#next-steps" id="next-steps"></a>

* 想開始建立團隊？請見 [建立與編排團隊](/build/teams/setup.md)——如何新建團隊、設定入口、拖入 Agent 節點、拉連線設定互動方式，並開始對話。
* 想查看團隊怎麼運作的？請見 [團隊執行記錄](/build/teams/traces.md)——每一次執行經過哪些 Agent、各自花了多少 Token、耗時多久。

{% hint style="info" %}
**前置條件：** Agent Teams 需由 MaiAgent 為你的組織啟用。若你在後台的〈AI 功能〉底下看不到〈團隊〉選單，請聯繫 MaiAgent 團隊開通。
{% 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/teams.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
