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

# 建立與編排團隊

建立與編排多 Agent 協作團隊：新建團隊、設定內建入口（模型、分流指令、知識庫）、在畫布拖入 Agent 節點、拉連線設定互動方式（自動／移交／委派）、升級舊版入口，到設定安全護欄（含自訂停止訊息）與開始對話的完整流程。

本頁說明如何從零建立一個 Agent Team：新建團隊、設定團隊的入口、在畫布上加入 Agent、設定它們之間的連線與互動方式，並開始與整個團隊對話。

{% hint style="info" %}
**先備好要加入團隊的 Agent。** 團隊裡的每個節點都是一個既有的 Agent，所以請先在〈AI 助理〉建立好各專長的 Agent（例如分流、訂單、退換貨 Agent），再回到這裡把它們組成團隊。
{% endhint %}

## <mark style="color:blue;">一、新建團隊</mark> <a href="#create-team" id="create-team"></a>

### 1. 進入團隊列表 <a href="#team-list" id="team-list"></a>

從左側選單進入 <mark style="color:blue;">AI 功能</mark> →〈<mark style="color:blue;">團隊</mark>〉。列表會顯示目前組織所有的團隊，包含**團隊名稱、狀態、說明與建立時間**等資訊，可用搜尋欄找團隊。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e4b4ade565ac92a82627769032207321143b9e52%2Fteams-list.png?alt=media" alt="團隊列表頁"><figcaption><p>團隊列表：可看到每個團隊的名稱、啟用狀態、說明與建立時間</p></figcaption></figure>

### 2. 建立團隊 <a href="#new-team" id="new-team"></a>

點右上角 <mark style="color:blue;">新建團隊</mark>，填入**團隊名稱**（必填）與**說明**，即可建立。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e963d0a321f92e60860565c434e1eeda62099a02%2Fteams-new-modal.png?alt=media" alt="新建團隊視窗"><figcaption><p>新建團隊：填入團隊名稱與說明</p></figcaption></figure>

{% hint style="success" %}
建立成功後，畫布上會自動出現這個團隊的**入口節點**，系統也會建立對應的 **Web Chat 對話平台**，讓你之後可以直接與整個團隊對話。入口由系統內建，不需要再從助理列表拉一個 Agent 來當入口。
{% endhint %}

## <mark style="color:blue;">二、在畫布上編排團隊</mark> <a href="#compose-canvas" id="compose-canvas"></a>

點進團隊後，預設進入 <mark style="color:blue;">畫布編排</mark> 檢視。畫面分成三個區域：左側〈**助理列表**〉、中間**畫布**、右側**設定面板**（點選節點或連線時出現）。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-32544819c639bb999b22a532554a911790206eb7%2Fteams-entry-node-settings.png?alt=media" alt="剛建立的團隊畫布：中間是紫色的入口節點，標示「入口」、模型與「分流」、「不可刪除」；左側為助理列表，右側為入口設定面板，含名稱、模型、分流指令與知識庫"><figcaption><p>剛建立的團隊：畫布上只有內建的入口節點，點選後右側出現〈入口設定〉</p></figcaption></figure>

{% hint style="warning" %}
**畫布編排建議使用桌機瀏覽器操作。** 在手機等小螢幕上，畫布編排區會顯示提示，請改用桌機完成編排。
{% endhint %}

### 1. 認識入口節點 <a href="#entry-node" id="entry-node"></a>

入口節點是團隊對外的第一站：使用者每段新對話都會先到入口，由入口依〈分流指令〉判斷該交給哪位成員，再把對話移交過去。

入口節點在畫布上以紫色顯示，上方標示「**入口**」，副標顯示使用的模型與「**分流**」，右下角標示「**不可刪除**」。它和團隊同時建立、同時刪除，名稱跟隨團隊名稱；要改名稱，到〈基本資訊〉修改團隊名稱即可。

剛建立的團隊還沒有成員時，畫布上方會提示〈入口尚未連到任何成員：對話會全部由入口自己回答〉。把成員加進畫布、再從入口拉連線過去（見下方[加入 Agent 節點](#add-nodes)與[拉連線](#add-edges)），入口就會開始分流。

一家電商的客服主管想讓「訂單」「退換貨」「商品推薦」三位專長助理一起服務客人。她新建團隊後，畫布上已經有入口節點；她把三位助理拖進畫布，從入口各拉一條「移交」連線過去，再到入口設定換成反應快的模型。之後客人在網頁對話問「我的包裹到哪了」，入口就把對話移交給訂單助理接手，客人不需要自己選擇要找哪位助理。

### 2. 設定入口 <a href="#entry-settings" id="entry-settings"></a>

點選入口節點，右側會出現〈<mark style="color:blue;">入口設定</mark>〉，可調整：

| 設定       | 說明                                             |
| -------- | ---------------------------------------------- |
| **名稱**   | 跟隨團隊名稱，這裡不能修改。                                 |
| **模型**   | 入口分流時使用的模型，預設為組織預設模型。                          |
| **分流指令** | 告訴入口什麼情況交給哪位成員。留空時使用系統預設指令，預設指令會列出目前從入口連出去的成員。 |
| **知識庫**  | 入口可以參考的知識庫，可多選。未綁定時，入口只依分流指令回答。                |

調整後按 <mark style="color:blue;">儲存</mark>；按 <mark style="color:blue;">取消</mark> 會還原成上次儲存的內容。

{% hint style="info" %}

* **自己寫了分流指令之後又增減成員**：入口設定會提示〈成員已變動，建議更新分流指令〉，請記得把新成員寫進指令，或清空指令改用系統預設。
* **沒有編輯權限時**：欄位只能查看，面板下方顯示「您沒有編輯權限，僅可查看」。團隊只有組織擁有者與團隊建立者可以修改。
  {% endhint %}

### 3. 加入 Agent 節點 <a href="#add-nodes" id="add-nodes"></a>

在左側〈助理列表〉找到要加入的 Agent，**拖曳到畫布**，或**點擊**它即可加入。已經在團隊裡的 Agent 會標示〈已在團隊中〉，點它可以定位到畫布上對應的節點。Agent 多時可用上方搜尋框過濾。

每個節點會顯示 Agent 名稱、使用的模型，以及它是 <mark style="color:blue;">Agent</mark> 或 <mark style="color:blue;">RAG</mark> 模式，方便你辨識。

{% hint style="info" %}
若節點位置雜亂，可點畫布上的 <mark style="color:blue;">自動排版</mark> 讓系統重新整理版面。節點位置會自動儲存。
{% endhint %}

### 4. 設定節點 <a href="#node-settings" id="node-settings"></a>

點選一個節點，右側會出現〈**節點設定**〉。可調整：

| 設定                    | 說明                                                                                            |
| --------------------- | --------------------------------------------------------------------------------------------- |
| **入口節點**              | 只在[舊版入口](#upgrade-legacy-entry)的團隊出現。開啟後，團隊收到訊息時從此節點開始處理對話。**一個團隊只能有一個入口節點。** 使用內建入口的團隊不需要設定。 |
| **此節點單則訊息的 Token 上限** | 此節點在單次團隊回合內可用的 Token 上限（輸入＋輸出，選填）；留空或 0 則只受團隊層級上限約束。達到上限時整個回合會被護欄停止。                          |
| **最大迭代次數**            | 此節點在單次團隊回合內可執行的步數上限（選填）；留空或 0 則只受團隊層級上限約束。只經由委派連線被呼叫的節點，改由子 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-a7f77a14215fd1233dc58146d81f4ca511c0896d%2Fteams-node-settings.png?alt=media" alt="節點設定面板：連線、入口節點、等使用者回覆再繼續、此節點單則訊息的 Token 上限、最大迭代次數、可見原始使用者輸入"><figcaption><p>節點設定：出線清單可勾選「等使用者回覆再繼續」，下方是 Token／迭代上限與〈可見原始使用者輸入〉（此畫面為舊版入口團隊，所以多一個〈入口節點〉開關）</p></figcaption></figure>

### 5. 拉連線並設定互動方式 <a href="#add-edges" id="add-edges"></a>

從一個節點的連接點拖到另一個節點，建立一條**有向連線**（來源 → 目標）。從入口拉到成員的連線，就是入口可以分流的對象；成員也可以把連線拉回入口，但連到入口的連線只能是〈移交〉，也不能繼承來源 Agent 的工具。點選連線，右側會出現〈**連線設定**〉：

| 設定                 | 說明                                                                                                                                                                                        |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **觸發條件描述**         | 用白話描述「什麼時候該走這條連線」。這段描述會提供給 AI 作為判斷依據，寫清楚有助於路由更準確。                                                                                                                                         |
| **互動方式**           | 選擇〈**自動**〉〈**移交**〉或〈**委派**〉（三者差異見下表）。                                                                                                                                                     |
| **等使用者回覆再繼續**      | 開啟後，上游 Agent 回覆完先停下，等使用者回覆了才交給下一個 Agent；預設關閉。打開後可再開〈**請助理附上選項**〉，停下時用 Agent UI 提問工具列出選項讓使用者點選回答（來源 Agent 須已啟用 Agent UI 提問工具）。只有〈自動〉與〈移交〉可開，〈委派〉型連線停用並顯示「委派型連線不支援，請改用移交」；已開啟的連線改成委派時會自動關閉。 |
| **繼承來源 Agent 的工具** | 開啟後，目標 Agent 可使用來源 Agent 的所有工具與資源。                                                                                                                                                        |

**互動方式**（各選項在設定面板中的說明）：

| 互動方式       | 說明                                                                                                                                   |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **自動（預設）** | 由 LLM 自動判斷最適合的互動方式。                                                                                                                  |
| **移交**     | 移交控制權——來源代理休眠，目標代理接管對話。                                                                                                              |
| **委派**     | 委派任務——目標代理執行後回傳結果給來源。子 Agent 以提問選項、Quick Reply、圖文卡片或檔案收尾時，這些內容會直接呈現給使用者，各對話平台的差異見下方[委派子 Agent 的互動收尾](#delegate-interactive-endings)。 |

畫布上開了「等使用者回覆再繼續」的連線會變成琥珀色並多一個「⏸ 待回覆」徽章。團隊執行到這條連線時停下，執行記錄的狀態顯示為「待回覆」，展開步驟可看到「等使用者回覆」與「回覆後接著交給：○○」（見[團隊執行記錄](/build/teams/traces.md#waiting-for-user)）；使用者回覆後才繼續交給目標 Agent。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-efed918ce4340db9339cc601faf459056c16cf9f%2Fteams-edge-settings.png?alt=media" alt="連線設定面板：互動方式選移交、觸發條件描述填顧客提到退貨換貨退款或商品瑕疵時，等使用者回覆再繼續已開啟，下方有請助理附上選項與繼承來源 Agent 的工具開關"><figcaption><p>連線設定：觸發條件描述、互動方式、等使用者回覆再繼續（開啟後可再開請助理附上選項），以及是否繼承來源 Agent 的工具</p></figcaption></figure>

例如電商的客服分流 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-c15198d3385ff482d99e4701f652c7b241c954e7%2Fteams-wait-reply-webchat-options.png?alt=media" alt="Web Chat 畫面：使用者說藍牙耳機右耳沒有聲音，客服分流助理停下並跳出提問選項「耳機右耳沒有聲音，您希望如何處理？」，選項為退貨退款、換新品、先檢測／維修、還不確定，想先了解方案"><figcaption><p>Web Chat：客服分流助理走到「等使用者回覆再繼續」的連線時停下，用提問選項請使用者選擇處理方式</p></figcaption></figure>

#### 等使用者回覆再繼續的運作規則 <a href="#wait-for-reply-rules" id="wait-for-reply-rules"></a>

* **只有決定走這條連線時才會停**：來源 Agent 如果自己就把問題答完、沒有交給目標 Agent，這一輪照常結束，不會停下。每次走到這條連線都會停，不只第一次。
* **停下是正常結束**：這一輪在來源 Agent 回覆後結束，執行記錄顯示〈待回覆〉，不算失敗。使用者的下一則訊息不論內容，都由目標 Agent 接續；如果逾時、出錯、觸發安全護欄或使用者按停止，這一輪不會進入待回覆。
* **編輯或重新產生訊息**：使用者改寫或重新產生已送出的訊息時，會從來源 Agent 重新開始，不會直接交給目標 Agent。
* **選項只在 Web Chat 與 API 顯示**：〈請助理附上選項〉的提問選項在 Web Chat 與 API 回覆中呈現；LINE 等其他對話平台只看得到來源 Agent 的文字說明，使用者直接打字回覆即可。
* **選項由 Agent 產生**：題目與選項是來源 Agent 依當時的對話寫出的，不是固定清單，不同模型照做的程度也不同。上線前建議用實際對話測試，確認停下時有出現選項。
* **節點設定是捷徑**：在〈節點設定〉把某個節點的出線全部勾起來，等於這個 Agent 每次交棒都會停下等使用者回覆。

{% hint style="warning" %}
**來源節點的 Agent 使用〈畫布模式 (Canvas)〉時，這個設定不會生效。** 開關仍可打開，畫布也會顯示「⏸ 待回覆」，但團隊執行時不會停下，照沒開啟時的方式交棒（Agent 模式見[Agent 模式的子選項](/build/agent/setup.md#agent-mode-normal-vs-canvas)）。需要在這條連線停下等使用者回覆時，請讓來源節點的 Agent 使用〈一般模式〉。
{% endhint %}

#### 委派子 Agent 的互動收尾 <a href="#delegate-interactive-endings" id="delegate-interactive-endings"></a>

用〈委派〉把工作交給子 Agent 時，子 Agent 的一般文字、思考與工具呼叫過程不會顯示給使用者。但子 Agent 若以下列互動元件收尾，元件會直接送到使用者面前，不必等來源 Agent 轉述：

| 子 Agent 的收尾             | Web Chat、後台對話、API | LINE                               | 其他對話平台（Telegram、Slack 等） |
| ----------------------- | ----------------- | ---------------------------------- | ------------------------ |
| **提問選項**（Agent UI 提問工具） | 直接顯示選項            | 不顯示選項，由來源 Agent 用文字轉述              | 不顯示選項，由來源 Agent 用文字轉述    |
| **Quick Reply**         | 直接顯示按鈕            | 顯示 LINE 快速回覆按鈕，來源 Agent 可能再用文字說明一次 | 由來源 Agent 用文字轉述          |
| **圖文卡片**                | 直接顯示卡片            | 顯示卡片，來源 Agent 可能再用文字說明一次           | 不送卡片，由來源 Agent 用文字轉述卡片內容 |
| **檔案面板**                | 直接顯示檔案卡片，可下載      | 由來源 Agent 用文字轉述                    | 由來源 Agent 用文字轉述          |

{% hint style="info" %}
子 Agent 以提問選項、Quick Reply 或圖文卡片收尾時，在 Web Chat、後台對話與 API，元件已經送到使用者面前，來源 Agent 不會再重複一次內容。因此子 Agent 收尾時寫在這些元件前面的說明文字（例如「查到三個方案，請選擇」）不會出現，使用者只會看到元件本身；Quick Reply 尤其明顯。若需要說明，請把它寫進提問的題目或卡片內容裡。檔案面板不適用這項收尾規則，來源 Agent 仍可能接續文字說明。
{% endhint %}

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-f51a387c2396cd384df57b8073fa2d2b0d22067c%2Fteams-canvas.png?alt=media" alt="團隊圖（放大）"><figcaption><p>連線範例：「客服分流助理」透過「移交」分流到訂單查詢／退換貨／商品推薦助理，訂單查詢助理再「委派」倉儲查詢助理。每個節點顯示 Agent 名稱、模型與 Agent／RAG 模式（此範例為舊版入口團隊，由成員「客服分流助理」擔任入口）</p></figcaption></figure>

{% hint style="info" %}
**留意畫布上方的語意警告。** 當團隊圖有問題時，畫布上方會出現黃色提示，例如：〈入口尚未連到任何成員：對話會全部由入口自己回答〉〈有重複的連線〉〈連線形成循環〉；舊版入口的團隊還可能出現〈尚未設定入口節點〉〈有多個入口節點，應只保留一個〉。建議在對話前先把這些警告排除。
{% endhint %}

### 6. 升級舊版入口 <a href="#upgrade-legacy-entry" id="upgrade-legacy-entry"></a>

較早建立的團隊沒有內建入口，而是由某個成員節點擔任入口（節點設定裡開啟〈入口節點〉的那一個）。這類團隊照常運作，不需要改動；若想改用內建入口統一分流，可以自行升級。

在桌機寬度開啟這類團隊的畫布，團隊名稱旁會有橘色的「**舊版入口**」標籤，畫布上方顯示橫幅：「此團隊使用舊版入口（由成員節點擔任入口）。升級後畫布會多一個分流入口節點，且無法還原。」

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-23afb6c145962dce632daf3e2e7fb7cb08fda892%2Fteams-legacy-entry-banner.png?alt=media" alt="舊版入口團隊的畫布上方：團隊名稱旁有橘色「舊版入口」標籤，下方橘色橫幅說明此團隊使用舊版入口、升級後無法還原，右側有「升級入口」按鈕"><figcaption><p>舊版入口團隊：名稱旁的「舊版入口」標籤與畫布上方的升級橫幅</p></figcaption></figure>

升級步驟：

1. 點橫幅右側的 <mark style="color:blue;">升級入口</mark>。
2. 確認視窗「**升級成內建入口？**」會說明：升級後無法還原。每段新對話會先經過入口，再移交給原本的入口成員；成員的設定與連線都不會被改動。
3. 確認後畫面顯示「已升級為內建入口」，畫布上原本入口成員的左邊會多一個入口節點，並以〈移交〉連線連到原本的入口成員。

升級後，入口預設把每段新對話都移交給原本的入口成員，所以使用者感受到的對話流程和升級前一樣。之後若想讓入口直接分流給其他成員，從入口拉連線到這些成員，再到[入口設定](#entry-settings)更新分流指令即可。

{% hint style="warning" %}

* **升級無法還原。** 建議先在測試用的團隊確認流程，再升級正式使用中的團隊。
* 只有組織擁有者與團隊建立者可以升級，其他人看到的〈升級入口〉按鈕會停用。
  {% endhint %}

## <mark style="color:blue;">三、設定基本資訊與安全護欄</mark> <a href="#settings-guardrails" id="settings-guardrails"></a>

點進團隊後，左側選單有四個檢視：〈<mark style="color:blue;">畫布編排</mark>〉、〈<mark style="color:blue;">基本資訊</mark>〉、〈<mark style="color:blue;">執行記錄</mark>〉、〈<mark style="color:blue;">API 串接</mark>〉，下方另列出這個團隊的 <mark style="color:blue;">對話平台</mark>。切換到〈**基本資訊**〉可調整團隊層級的設定：

* **基本資訊**：團隊名稱、說明、是否啟用。
* **安全護欄**：
  * **最大迭代數**（預設 `25`）——一次對話中，Agent 之間最多可以來回幾次，避免無限循環。
  * **單則訊息的 Token 上限**（預設 `200000`）——整個團隊處理單則使用者訊息的 Token 預算上限。
  * **整個對話的 Token 上限**（預設 `0`）——整段對話從頭累計的 Token 預算；畫面標示「0 代表停用此護欄」，只想限制單則訊息時維持 0 即可。
  * **逾時秒數**（預設 `600`）——整個團隊處理流程的硬性逾時。
  * **安全護欄自訂訊息**（預設留空）——前三種護欄把回覆停下來時顯示給使用者的文字；留空則使用系統預設訊息。說明見下方[安全護欄自訂訊息](#guardrail-stop-message)。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-acc619316f285d3cc8af1f8b85ff3312a5b4d3ce%2Fteams-settings.png?alt=media" alt="團隊基本資訊與安全護欄"><figcaption><p>基本資訊與安全護欄：調整團隊名稱、啟用狀態，以及最大迭代數、兩個 Token 上限與逾時秒數</p></figcaption></figure>

### 安全護欄自訂訊息 <a href="#guardrail-stop-message" id="guardrail-stop-message"></a>

團隊處理到一半，若碰到**最大迭代數**、**單則訊息的 Token 上限**或**整個對話的 Token 上限**，系統會停下這一輪回覆，並在回覆最後附上一段停止訊息告訴使用者。「安全護欄自訂訊息」讓你決定這段文字要寫什麼；沒填時，系統會依停止原因與使用者的語言顯示預設訊息。

一家線上購物平台用 API 把 Agent Team 串進自家官網的導購助理。工程師希望護欄觸發時，回覆結尾出現一段固定格式的文字，方便程式辨識後改顯示「聯絡客服」按鈕。團隊管理員在〈基本資訊〉的「安全護欄自訂訊息」填入「\[LIMIT] 本次對話已達使用上限，請開啟新對話或聯絡客服。」並儲存。之後有位訪客一次要求比較十幾款商品，團隊處理到用量上限而停下，回覆在已經寫出的部分內容與一條分隔線之後，接上這段固定文字；官網程式比對到回覆結尾的 `[LIMIT]`，就把輸入框換成聯絡客服按鈕。

#### 1. 填入自訂訊息 <a href="#fill-stop-message" id="fill-stop-message"></a>

在團隊的〈<mark style="color:blue;">基本資訊</mark>〉找到〈**安全護欄**〉卡片，四個數值欄位下方就是 <mark style="color:blue;">安全護欄自訂訊息</mark>。輸入框右下角顯示目前字數（例如 `34 / 500`），下方說明為「安全護欄觸發時顯示給使用者。留空則使用系統預設訊息。」

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-f3a64721b05fce13808039b100c06e653790698f%2Fteams-guardrail-stop-message.png?alt=media" alt="安全護欄卡片：最大迭代數、單則訊息的 Token 上限、整個對話的 Token 上限、逾時秒數四個欄位，下方為安全護欄自訂訊息輸入框、0 / 500 字數與說明文字"><figcaption><p>「安全護欄」卡片下方的「安全護欄自訂訊息」：留空時顯示範例文字與 0 / 500</p></figcaption></figure>

填寫規則：

* **最多 500 字**：超過時字數會變紅，欄位下方顯示「訊息長度不可超過 500 字」，按儲存會被擋下。這時同一次在頁面上做的其他修改（例如改了最大迭代數）**也不會存入**，請先把訊息縮短到 500 字以內再儲存。
* **原樣顯示**：不翻譯、不代換變數，填什麼就顯示什麼；換行會保留，頭尾的空白會自動去掉。只填空白等同留空。

#### 2. 儲存 <a href="#save-stop-message" id="save-stop-message"></a>

按 <mark style="color:blue;">儲存</mark>。儲存後立即生效，下一次觸發護欄的回覆就會使用新的文字。要改回系統預設訊息，把欄位清空再儲存即可。

#### 使用者會看到什麼 <a href="#what-users-see" id="what-users-see"></a>

三種護欄觸發時，**Web Chat 與 API 回覆顯示的是同一段文字**：

* 若停下前 Agent 已經回覆了一部分，會先保留那段部分回覆，接著一條分隔線，再接上停止訊息。
* 停止訊息前面不加任何系統前綴。

| 觸發的護欄              | 有填自訂訊息 | 留空時的預設訊息（繁體中文）              | 留空時的預設訊息（英文）                                                                                |
| ------------------ | ------ | --------------------------- | ------------------------------------------------------------------------------------------- |
| **最大迭代數**          | 顯示自訂訊息 | 這次回覆的處理步驟已達上限，請換個方式再問一次。    | This reply has reached its processing step limit. Please try asking in a different way.     |
| **單則訊息的 Token 上限** | 顯示自訂訊息 | 這則訊息的用量已達上限，請縮短內容或換個方式再問一次。 | This message has reached its usage limit. Please shorten it or try asking differently.      |
| **整個對話的 Token 上限** | 顯示自訂訊息 | 本次對話的用量已達上限，請開啟新對話繼續。       | This conversation has reached its usage limit. Please start a new conversation to continue. |

預設訊息會跟著使用者的語言顯示，支援繁體中文、簡體中文、英文、日文、韓文：Web Chat 依建立對話當下的介面語言；API 依請求帶的語言資訊，沒有時依訊息內容判斷；都判斷不出來時顯示英文。自訂訊息則不分語言。

{% hint style="warning" %}
**以下情況不會顯示安全護欄自訂訊息：**

* **逾時秒數**觸發時：顯示的是團隊入口 Agent 的[逾時訊息](/build/agent/custom-max-tokens.md#agent-timeout-message)（未設定時為系統預設）。
* **節點層級**的〈此節點單則訊息的 Token 上限〉〈最大迭代次數〉觸發時（見[設定節點](#node-settings)）：顯示一句指出節點名稱與上限數值的系統訊息，不受這個欄位影響。
  {% endhint %}

{% hint style="info" %}
**用 API 串接、要讓程式辨識停止訊息時：**

* 比對「**回覆結尾**」是不是你的自訂訊息，不要比對整則回覆——停下前可能已有部分回覆，中間還隔著一條分隔線。
* 不要拿系統預設訊息來比對，預設訊息會隨使用者的語言改變。
* 節點層級上限觸發時不會出現自訂訊息；若要靠固定文字辨識，節點的 Token 與迭代上限請留空。
* Web Chat 會以 Markdown 呈現這段文字，例如 `**重要**` 會顯示成粗體。
  {% endhint %}

## <mark style="color:blue;">四、與團隊對話</mark> <a href="#talk-to-team" id="talk-to-team"></a>

編排完成、確認團隊為〈啟用中〉後，就能透過團隊的 **Web Chat 對話平台** 與整個團隊對話。使用者只面對一個入口，系統會自動把問題路由給合適的 Agent。

當團隊在 Agent 之間移交或委派時，對話介面會顯示切換提示，例如〈**正在移交給**〉〈**正在委派給**〉〈**正在切換至**〉，讓使用者知道目前由哪個 Agent 服務中。

## <mark style="color:blue;">五、刪除團隊</mark> <a href="#delete-team" id="delete-team"></a>

在〈基本資訊〉檢視最下方的危險區可以〈**刪除團隊**〉。刪除會一併移除此團隊的入口，且**此操作無法復原**，請確認後再執行。成員節點對應的 Agent 不會被刪除，仍保留在〈AI 助理〉。

## <mark style="color:blue;">六、API 串接</mark> <a href="#api-integration" id="api-integration"></a>

要從自己的系統呼叫整個團隊，切換到左側的〈**API 串接**〉。這一頁沿用 Agent 的 API 說明（請求範例、欄位與回應格式），差別只在呼叫對象是這個團隊建立時自動產生的**入口 Agent**：對它送訊息就等於對整個團隊送訊息，路由與移交由團隊自行處理。範例中的 ID 已經代入入口 Agent，直接複製即可；完整的欄位說明見[開發者工具](/org/developer.md#integration-docs)。

{% hint style="info" %}
頁面顯示「此團隊尚未建立入口 Chatbot，暫無 API 範例」時，代表這個團隊沒有入口 Agent。入口 Agent 在建立團隊時由系統自動建立，正常不會缺少；若出現這個提示，請洽 MaiAgent 窗口協助補建。
{% endhint %}

## <mark style="color:blue;">七、常見問題</mark> <a href="#faq" id="faq"></a>

### 建立團隊後，AI 助理列表裡沒有和團隊同名的助理？ <a href="#faq-entry-agent-hidden" id="faq-entry-agent-hidden"></a>

團隊的入口背後是一個和團隊同名的 Agent，專門給這個團隊使用，所以不會出現在〈AI 助理〉列表，也不會出現在畫布的〈助理列表〉裡讓你拉進其他團隊。入口的模型、分流指令與知識庫都在團隊畫布的[入口設定](#entry-settings)調整。

如果從其他頁面的連結打開這個入口 Agent 的設定頁，畫面只會顯示「這是團隊「團隊名稱」的入口」的說明，點 <mark style="color:blue;">前往團隊畫布</mark> 即可回到團隊設定；它的模式固定為團隊，不能改成一般助理。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-6d90132dbdf46d46eabf748a91cd6baf13515cd2%2Fteams-entry-agent-guide.png?alt=media" alt="入口 Agent 的設定頁：顯示「這是團隊「客服團隊」的入口」，說明入口的模型、分流指令與知識庫在團隊畫布上設定，下方有「前往團隊畫布」按鈕"><figcaption><p>打開入口 Agent 的設定頁時，會引導你回到團隊畫布</p></figcaption></figure>

### 入口節點可以刪除嗎？ <a href="#faq-delete-entry" id="faq-delete-entry"></a>

不行。入口節點標示「不可刪除」，會跟著團隊一起存在；只有[刪除團隊](#delete-team)時才會一併移除。

### 舊版入口的團隊一定要升級嗎？ <a href="#faq-legacy-upgrade" id="faq-legacy-upgrade"></a>

不用。舊版入口的團隊照常運作；想改用內建入口時再依[升級舊版入口](#upgrade-legacy-entry)操作即可。升級無法還原，請確認後再執行。

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

團隊開始運作後，你可以在 [團隊執行記錄](/build/teams/traces.md) 查看每一次執行經過了哪些 Agent、各自花了多少 Token、以及耗時，確認團隊如預期分工。


---

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