> 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/agent/custom-max-tokens.md).

# 回覆長度與 Agent 執行上限

設定 Agent 每次回覆的長度上限（最大輸出 Token 數），以及 Agent 模式的工具呼叫次數上限（最大迭代次數，預設 20）與執行逾時時間；說明達到工具使用上限時使用者會看到什麼。

Agent 的 <mark style="color:blue;">進階設定</mark> 有兩組上限：

* **回覆長度**：<mark style="color:blue;">最大輸出 Token 數</mark>，限制 AI 每次回覆最多能寫多長，說明從下方[功能簡介](#feature-introduction)開始。
* **Agent 執行上限**：<mark style="color:blue;">最大迭代次數</mark>（也就是工具呼叫次數上限，預設 20）與 <mark style="color:blue;">執行逾時時間（秒）</mark>，限制 Agent 模式的 Agent 每回答一則訊息最多呼叫幾輪工具、最多跑多久。想查「工具最多能呼叫幾次」或回覆出現「已達本輪的工具使用上限」，請直接看 [Agent 執行上限](#agent-iteration-timeout-relationship)。

### 功能簡介 <a href="#feature-introduction" id="feature-introduction"></a>

自訂輸出 Token 上限功能讓您能精確控制 Agent 每次回覆的最大長度。透過調整此設定,您可以根據不同應用情境,讓 Agent 產生簡短摘要或詳細說明,同時有效控制 Token 消耗成本。

{% hint style="info" %}
**Token 說明**

Token 是 AI 模型處理文字的基本單位。一般而言:

* 中文:1 個字約等於 1.5-2 個 Tokens
* 英文:1 個單字約等於 1-1.5 個 Tokens
* 標點符號也會計入 Token 數量
  {% endhint %}

***

### 設定輸出 Token 上限 <a href="#configure-token-output-limit" id="configure-token-output-limit"></a>

#### 進入設定頁面 <a href="#navigate-to-settings" id="navigate-to-settings"></a>

1. 點選左側選單「<mark style="color:blue;">AI 助理</mark>」
2. 在列表中點選要設定的 Agent 右側的「<mark style="color:blue;">編輯</mark>」
3. 在「<mark style="color:blue;">設定</mark>」分頁左側導覽點選「<mark style="color:blue;">管理與進階</mark>」下的「<mark style="color:blue;">進階設定</mark>」

#### 調整 Token 上限 <a href="#adjust-token-limit" id="adjust-token-limit"></a>

1. **選擇 Token 上限模式**
   * 「<mark style="color:blue;">使用模型最大值</mark>」：直接套用所選模型支援的最大輸出 Token 數（預設）
   * 「<mark style="color:blue;">自訂數量</mark>」：自行指定上限
2. **輸入自訂數值（選擇「自訂數量」時）**
   * 在數字輸入框輸入目標數值
   * 可輸入範圍依所選模型而定，畫面會即時顯示該模型允許的範圍（如下圖的「範圍：512 - 64000 tokens」）
3. **儲存設定**
   * 點選「<mark style="color:blue;">儲存</mark>」按鈕
   * 設定立即生效,無需重啟 Agent

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-cb789624285313a34f8f8026b39a6c577512d2a4%2Fbuild-custom-max-tokens.png?alt=media" alt="進階設定：最大輸出 Token 數"><figcaption><p>「最大輸出 Token 數」區塊：選擇「自訂數量」後輸入上限，下方顯示目前模型允許的範圍</p></figcaption></figure>

{% hint style="warning" %}
**注意事項**

* 設定過低可能導致回覆被截斷,影響完整性
* 設定過高會增加 Token 消耗成本
* 建議依實際需求調整,並透過測試找到最佳平衡點
  {% endhint %}

***

### 建議設定值 <a href="#recommended-settings" id="recommended-settings"></a>

根據不同應用情境,以下是推薦的 Token 上限設定:

<table><thead><tr><th width="200">應用情境</th><th width="150">建議 Token 數</th><th>說明</th></tr></thead><tbody><tr><td><strong>簡短問答</strong></td><td>256 - 512</td><td>適合快速回答,如 FAQ 機器人<br>約 100-200 中文字</td></tr><tr><td><strong>一般客服</strong></td><td>512 - 1024</td><td>平衡詳細度與成本<br>約 200-400 中文字</td></tr><tr><td><strong>專業諮詢</strong></td><td>1024 - 2048</td><td>提供詳細說明與解決方案<br>約 400-800 中文字</td></tr><tr><td><strong>內容生成</strong></td><td>2048 - 4096</td><td>生成長篇文章或報告<br>約 800-1600 中文字</td></tr><tr><td><strong>程式碼生成</strong></td><td>1024 - 2048</td><td>產生完整的程式碼片段<br>含註解與說明</td></tr></tbody></table>

***

### 應用情境範例 <a href="#use-case-examples" id="use-case-examples"></a>

#### 情境一:FAQ 快速回答機器人 <a href="#scenario-1-faq-quick-response-bot" id="scenario-1-faq-quick-response-bot"></a>

**需求**:客戶常問的問題需要簡短明確的回答,避免冗長說明

**設定方式**:

* 輸出 Token 上限:256-512
* 角色指令:「請用簡短明確的方式回答問題,不超過 3 句話」
* 預期效果:快速回應,降低 Token 消耗

**範例對話**:

```
使用者:營業時間是幾點到幾點？
AI:我們的營業時間是週一至週五上午 9:00 至下午 6:00,
週六上午 10:00 至下午 5:00,週日公休。
```

#### 情境二:技術支援詳細說明 <a href="#scenario-2-technical-support-detailed-explanation" id="scenario-2-technical-support-detailed-explanation"></a>

**需求**:使用者遇到技術問題,需要詳細的步驟說明

**設定方式**:

* 輸出 Token 上限:1024-2048
* 角色指令:「請提供詳細的步驟說明,確保使用者能夠按步驟操作」
* 預期效果:完整的問題解決指引

**範例對話**:

```
使用者:軟體無法啟動怎麼辦？
AI:請依照以下步驟排除問題:

1. 確認系統需求
   - 作業系統: Windows 10 以上
   - 記憶體: 至少 4GB
   - 硬碟空間: 至少 2GB

2. 重新安裝軟體
   - 移除現有版本（控制台 > 程式集）
   - 下載最新版本 [連結]
   - 以管理員身分執行安裝程式

3. 檢查防火牆設定
   - 將軟體加入例外清單
   - 允許軟體存取網路

如以上步驟無法解決,請提供錯誤訊息截圖,我們將進一步協助。
```

#### 情境三:內容摘要生成 <a href="#scenario-3-content-summary-generation" id="scenario-3-content-summary-generation"></a>

**需求**:從長篇文章中提取重點摘要

**設定方式**:

* 輸出 Token 上限:512-768
* 角色指令:「請將重點整理為 3-5 個要點,每點不超過 2 句話」
* 預期效果:簡潔的摘要,易於快速理解

***

### 與其他設定的關係 <a href="#relationship-with-other-settings" id="relationship-with-other-settings"></a>

#### 角色指令 (System Prompt) <a href="#system-prompt-settings" id="system-prompt-settings"></a>

即使設定高 Token 上限,角色指令仍可約束回覆長度:

```
良好範例:
「請用簡潔的方式回答,除非使用者要求詳細說明」

不良範例:
「請儘可能詳細回答每個問題」（可能導致過長回覆）
```

#### 模型選擇 <a href="#model-selection" id="model-selection"></a>

不同模型支援的最大輸出 Token 數不同。當您切換 Agent 使用的模型時,可自訂的範圍會隨之改變,畫面上的範圍提示即為目前所選模型的上下限。選擇「使用模型最大值」時,系統會自動套用該模型的最大值。

***

### Agent 執行上限：工具呼叫次數與執行逾時時間 <a href="#agent-iteration-timeout-relationship" id="agent-iteration-timeout-relationship"></a>

{% hint style="info" %}
本節僅適用於\*\*回覆模式設為「Agent 模式」\*\*的 Agent。若 Agent 使用其他回答模式，進階設定裡不會出現這個區塊。
{% endhint %}

回答模式為 Agent 模式的 Agent 會自行判斷要呼叫哪些工具、執行幾輪推理才能回答問題。為了避免 Agent 無止盡執行下去，<mark style="color:blue;">進階設定</mark> 的 <mark style="color:blue;">Agent 工作流設定</mark> 提供兩個獨立的「煞車」設定：

* **最大迭代次數**（工具呼叫次數上限）：Agent 回答一則訊息時，最多可以執行幾輪「思考 → 呼叫工具 → 取得結果」的循環，範圍 1–100，預設 20。一輪可以同時呼叫多個工具，所以上限是以「輪」計算；使用者傳下一則訊息時重新計算。開啟 <mark style="color:blue;">啟用工具搜尋功能</mark>（預設開啟）時，只用來搜尋可用工具的那幾輪不計入
* **執行逾時時間（秒）**：Agent 回答一則訊息最多可以跑多久，範圍 30–1200 秒，預設 600 秒

#### 達到工具呼叫次數上限時會發生什麼 <a href="#when-tool-limit-reached" id="when-tool-limit-reached"></a>

用完最後一輪後，Agent 不會再呼叫工具，而是用已取得的資訊整理出回覆，並在回覆最後加上一行提示：

> 回覆已達本輪的工具使用上限，內容可能不完整。請傳送後續訊息以繼續。

若 Agent 在這時還沒寫出任何內容，回覆會是「我在完成任務前就達到了本輪的工具使用上限。請再試一次，或縮小問題範圍。」這兩種情況都是設定的上限生效，不是系統錯誤：使用者可以傳一則訊息請 Agent 繼續，管理員也可以調高 <mark style="color:blue;">最大迭代次數</mark>（記得一併檢查逾時時間，見下方說明）。

#### 兩者是什麼關係？ <a href="#how-they-interact" id="how-they-interact"></a>

**這兩個設定彼此獨立，沒有換算公式，純粹「誰先達到門檻，誰就先決定結果」**——逾時先到會直接強制中斷對話，迭代次數先到則由 Agent 產生一段總結回覆、不會被視為錯誤。

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-8ecbaed6be78c2706aebf7f03c456c047546bc30%2Fagent-iteration-warning.png?alt=media" alt="執行逾時時間警告"><figcaption><p>逾時 100 秒 ÷ 20 次迭代（每次僅 5 秒預算）時觸發的黃色警告示例</p></figcaption></figure>

#### 逾時自訂訊息 <a href="#agent-timeout-message" id="agent-timeout-message"></a>

<mark style="color:blue;">Agent 工作流設定</mark> 最下方的 「<mark style="color:blue;">逾時自訂訊息</mark>」 決定逾時中斷時使用者看到的文字。畫面說明是「僅在 Agent 工作流逾時時顯示給使用者。留空則使用系統預設訊息」，可填例如「系統忙碌中，請稍後再試」或引導改問較小的問題；達到迭代上限的提示文字固定，不受這個欄位影響。

### 進階設定裡的其他開關 <a href="#other-advanced-switches" id="other-advanced-switches"></a>

同一個 <mark style="color:blue;">進階設定</mark> 分頁還有幾個與回覆長度、成本相關的開關，一般維持預設即可：

| 位置     | 開關                                                                                   | 畫面說明與用法                                                                                                                          |
| ------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| 知識庫設定  | <mark style="color:blue;">強制使用完整檢索範圍</mark>                                          | 啟用後忽略模型自動決定的檢索數量，固定回傳「檢索區塊最大數量」設定的完整結果；適用於包含長表格等需要較多區塊才能完整呈現的知識庫。會提高每次回答的輸入 token                                                |
| 對話記憶設定 | <mark style="color:blue;">工具結果截斷</mark>、<mark style="color:blue;">每次工具結果最大字元數</mark> | 自動截斷過大的工具回傳結果（例如網頁搜尋、程式碼執行輸出），避免記憶膨脹；超過上限的結果會保留前後兩端內容。工具常回傳整頁 HTML 或大量資料時建議開啟                                                    |
| 持久記憶之後 | <mark style="color:blue;">啟用 Claude 串流自動重試</mark>                                    | Claude 串流呼叫停滯（首個 chunk 未抵達或傳輸途中中斷）時自動中止，並以非串流模式重發一次。每次重試會對同一個 prompt 重複計費一次，只在遇到 Claude 回覆常卡住時開啟                                 |
| 最下方    | <mark style="color:blue;">開啟自動評估</mark>                                              | 啟用後在 <mark style="color:blue;">AI 助理監控</mark> 自動用 LLM 計算每次對話的品質分數，會消耗組織的使用額度，見 [自動評估與 Agent 監控](/build/agent-ops/evaluations.md) |

對話記憶設定裡的 <mark style="color:blue;">向量記憶</mark>、<mark style="color:blue;">跨對話檢索</mark> 與 Embedding／Reranker 模型見 [跨對話檢索](/build/agent/cross-conversation-search.md#other-memory-settings)。

***

### 成本優化建議 <a href="#cost-optimization-recommendations" id="cost-optimization-recommendations"></a>

#### 計算 Token 消耗 <a href="#calculate-token-consumption" id="calculate-token-consumption"></a>

一次對話的 Token 消耗包含:

* **輸入 Tokens**:使用者問題 + 歷史對話 + 角色指令
* **輸出 Tokens**:AI 回覆（受此設定限制）

**範例計算**:

```
輸入:使用者問題 50 Tokens + 歷史對話 200 Tokens + 角色指令 100 Tokens = 350 Tokens
輸出:AI 回覆（上限設為 512 Tokens）
總計:350 + 512 = 862 Tokens（最多）
```

#### 優化策略 <a href="#optimization-strategies" id="optimization-strategies"></a>

1. **依情境調整**
   * 簡單問題用低 Token 上限
   * 複雜問題才提高上限
2. **避免不必要的長回覆**
   * 在角色指令中明確要求簡潔
   * 使用多輪對話取代單次長回覆
3. **定期檢視使用狀況**
   * 在 Agent 的「<mark style="color:blue;">使用分析</mark>」→「<mark style="color:blue;">使用統計</mark>」查看 Token 用量與對話字數趨勢
   * 調整設定以優化成本

{% hint style="info" %}
詳細的成本計算與優化建議,請參考 [用量計算](/others/usage.md)。
{% endhint %}

***

### 常見問題 <a href="#faq" id="faq"></a>

#### Q:設定 Token 上限後,AI 回覆會被強制截斷嗎？ <a href="#q-will-ai-response-be-cut-off-after-setting-token-limit" id="q-will-ai-response-be-cut-off-after-setting-token-limit"></a>

**A**:是的。當 AI 生成的回覆達到 Token 上限時,會在該位置停止,可能導致句子不完整。建議:

* 設定適當的上限（不要過低）
* 在角色指令中要求「在達到字數限制前自然結束」

#### Q:如何知道我的 Agent 平均使用多少 Tokens？ <a href="#q-how-to-check-average-token-usage" id="q-how-to-check-average-token-usage"></a>

**A**：進入 Agent 的「<mark style="color:blue;">使用分析</mark>」分頁，切到「<mark style="color:blue;">使用統計</mark>」，<mark style="color:blue;">Token 用量</mark> 圖會依日期列出這個 Agent 每個模型的 Token 數與 Token 總用量。圖表說明見 [使用分析](/build/agent/usage.md)。

#### Q:設定較高的 Token 上限會降低回覆速度嗎？ <a href="#q-does-higher-token-limit-slow-down-responses" id="q-does-higher-token-limit-slow-down-responses"></a>

**A**:會有輕微影響。更長的回覆需要更多生成時間,但通常差異不大（數秒內）。主要影響因素仍是:

* 模型選擇
* 網路連線速度
* 伺服器負載

#### Q:不同語言需要不同的 Token 上限設定嗎？ <a href="#q-different-languages-need-different-token-limits" id="q-different-languages-need-different-token-limits"></a>

**A**:建議適度調整:

* **中文**:同樣字數消耗較多 Tokens,可略為提高上限
* **英文**:Token 效率較高,可使用較低上限
* **多語言環境**:建議設定較高上限以確保彈性

#### Q:Token 上限會影響知識庫檢索結果嗎？ <a href="#q-does-token-limit-affect-knowledge-base-retrieval" id="q-does-token-limit-affect-knowledge-base-retrieval"></a>

**A**:不會直接影響檢索,但會影響如何呈現檢索結果:

* **高 Token 上限**:可引用更多知識庫片段
* **低 Token 上限**:只引用最相關的片段

#### Q：Agent 回答一則訊息，工具最多能呼叫幾次？ <a href="#q-max-tool-calls" id="q-max-tool-calls"></a>

**A**：由 <mark style="color:blue;">最大迭代次數</mark> 決定，預設 20 輪、最多可調到 100 輪，每一則使用者訊息重新計算。用完時回覆最後會出現「回覆已達本輪的工具使用上限，內容可能不完整。請傳送後續訊息以繼續。」，這是上限生效而不是故障，詳見 [達到工具呼叫次數上限時會發生什麼](#when-tool-limit-reached)。

#### Q：調高最大迭代次數，是不是就一定要跟著調高執行逾時時間？ <a href="#q-do-i-need-to-raise-timeout-with-iterations" id="q-do-i-need-to-raise-timeout-with-iterations"></a>

**A**：強烈建議這樣做，但系統不會強制要求。兩個設定彼此獨立，即使只調高迭代次數、不調整逾時時間，系統也允許儲存，但很可能還沒跑到您設定的迭代次數上限，就先被逾時機制強制中斷。建議依照「執行逾時時間 ÷ 最大迭代次數 ≥ 15 秒」的比例一起調整，避免觸發黃色警告。

#### Q：逾時中斷跟迭代次數跑完，對使用者體驗有什麼差別？ <a href="#q-timeout-vs-max-iterations-difference" id="q-timeout-vs-max-iterations-difference"></a>

**A**：差異很大。迭代次數先到上限時，Agent 會直接把目前掌握的資訊整理成一段總結回覆給使用者，對話正常結束；但執行逾時先觸發時，對話會被強制中斷並標記為錯誤，使用者只會看到逾時前已產生的部分內容（如果有）加上逾時提示訊息，不會有整理過的總結回覆，先前已消耗的 Credit 也不會退還。

***

### 測試與調整 <a href="#testing-and-adjustment" id="testing-and-adjustment"></a>

#### 測試流程 <a href="#testing-process" id="testing-process"></a>

1. **設定初始值**
   * 從建議值開始（如 1024）
2. **進行測試對話**
   * 輸入典型的使用者問題
   * 觀察回覆長度與完整性
3. **評估結果**
   * 回覆是否完整？
   * 是否有不必要的冗長內容？
   * Token 消耗是否合理？
4. **逐步調整**
   * 過長→降低 Token 上限
   * 過短/截斷→提高 Token 上限
5. **持續監控**
   * 定期檢視使用狀況
   * 根據實際需求微調

#### 測試範例 <a href="#testing-examples" id="testing-examples"></a>

```
測試 1:Token 上限 256
使用者:請介紹一下你們公司
AI:我們是一家專注於 AI 技術的公司,提供企業級對話機器人解決方案。[回覆被截斷]
評估:太短,需提高

測試 2:Token 上限 1024
使用者:請介紹一下你們公司
AI:我們是一家專注於 AI 技術的公司...[完整詳細介紹]...歡迎聯繫我們了解更多。
評估:適中,採用
```

***

### 相關功能 <a href="#related-features" id="related-features"></a>

{% hint style="info" %}
**延伸功能**

* [建立 Agent](/build/agent/setup.md)
* [角色指令設計指南](/build/agent/system-prompt.md)
* [用量計算](/others/usage.md)
* [使用分析](/build/agent/usage.md)
  {% 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/agent/custom-max-tokens.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.