如何在 AgentGPT 中設定循環限制與匯出任務成果以防 Token 消耗失控

自主 AI 代理（Autonomous Agents）的一大優勢在於能將宏觀目標自動拆解為子任務並遞迴推進。然而，若缺乏明確的邊界限制，遞迴執行機制也是迅速耗盡 API Token 額度的主要原因之一。一旦代理陷入邏輯迴圈、反覆嘗試存取失效連結，或不斷繁衍多餘的子任務，開發者的 API 預算可能在幾分鐘內迅速消耗。在由 Reworkd 開發的開源平台 AgentGPT 中，開發者主要透過兩項核心控制項來降低風險：嚴格的執行循環上限設定與多格式任務輸出匯出。

在啟動代理前確立循環次數與 Token 配額，並在任務完成或停止時及時提取結構化成果，是確保自主工作流程兼具穩定性與成本效益的關鍵作法。

1. AgentGPT 遞迴循環的 Token 消耗機制

若要精確設定循環限制，必須先釐清 AgentGPT 的基本執行生命週期：

1. 目標拆解（Goal Ingestion）：系統接收使用者輸入的主目標後，呼叫大型語言模型（如 GPT-3.5-Turbo 或 GPT-4）生成第一批子任務陣列。
2. 任務執行與分析（Task Execution）：代理依序取出待處理任務，呼叫 LLM 或外部工具執行，並將中間結果寫回上下文。
3. 任務衍生與更新（Task Creation）：依據執行回傳的資訊，代理評估是否需要新增子任務或重新編排佇列。
4. 遞迴循環（Recursive Loop）：上述步驟 2 與步驟 3 持續循環，直到佇列清空或觸發硬性終止條件。

每一次迭代皆計為一次執行循環（Loop）。在標準流程中，單次循環通常伴隨多次 API 呼叫，且每次傳遞的對話歷史會隨之增長。若目標設定過於寬泛或缺乏終止判定，代理極易發散運行，引發嚴重的 Token 失控消耗。

2. 在使用者介面設定執行循環限制

AgentGPT 在 Web 介面與本地客戶端中內建了便捷的控制面板，方便開發者直接進行參數約束。

進入進階設定

1. 開啟 AgentGPT 介面，點擊左側導覽列的 Settings（⚙️ 設定），或直接瀏覽至 /settings。
2. 確認已完成登入（支援 GitHub、Google、Discord）或處於本地部署狀態。在線上託管版本中，未登入的訪客將無法存取 Advanced Settings（進階設定），以防範公共資源遭到惡意耗用。

調整循環滑桿（customMaxLoops）

在 Advanced Settings 區塊中尋找 Loop 參數：

• 滑桿範圍：支援在 1 至 25 次循環之間調整（遞增級距為 1）。
• 預設配置：免費展示模式預設為 25 次；若填入自訂 OpenAI API Key，系統預設提供 10 次之安全值。
• 觸發效果：當執行累積循環達到設定上限時，系統將強制中斷後續任務生成，並在控制台顯示保護提示：

  The maximum number of loops have been reached, this agent is shutting down.
  

  (在舊版介面中，該提示為經典的："To save your wallet, and our infrastructure costs, this agent is shutting down.")

各類任務之建議循環預算

• 重點摘要、單一主題問答與資訊整理：建議設定 3 ~ 7 次。
• 多步驟內容撰寫、方案對比與架構構想：建議設定 8 ~ 12 次。
• 跨來源深度網路調研與複合任務拆解：建議設定 15 ~ 25 次。

搭配之成本治理選項

建議在設定頁面同步調整相關連動參數：

• Token 上限（Tokens / maxTokens）：滑桿範圍為 200 至模型上限（如 4000 Token），用以限制單次 API 呼叫的最大生成長度，避免個別回答過長造成浪費。
• 模型選擇（Model）：在初期驗證階段選用高性價比的 gpt-3.5-turbo；涉及高難度推理時才啟用 gpt-4。
• 溫度設定（Temperature）：將溫度降至 0.0 ~ 0.2，促使輸出更加確定與聚焦，減少因幻覺衍生無效循環。
• 自訂金鑰（API Key）：輸入個人 OpenAI Key 並透過 Test 按鈕完成有效性驗證，直接由自身帳戶控管預算。

3. 即時執行生命週期介入控制

除了事前靜態設定，AgentGPT 在控制台上方提供了即時的生命週期控制項（AgentControls）：

• 暫停按鈕（Pause / FaPause）：讓代理在執行完目前動作後進入暫停狀態。開發者可藉此檢視模型產生的子任務邏輯是否符合預期。
• 繼續按鈕（Play / FaPlay）：確認任務執行無誤後，點擊繼續推進下一項子任務。
• 強制停止按鈕（Stop / FaStop）：若察覺代理陷入發散迴圈或產出無效內容，點擊紅色停止按鈕即可立即切斷連線（狀態標記為 stopped），中止正在傳輸的串流請求，即刻止損。

4. 本地部署與後端環境級設定

對於透過 Docker 本地運行或架設於內部基礎設施的團隊，可在伺服端與程式碼層面落實全域安全防護。

後端環境變數防護

AgentGPT 的 Python 後端（reworkd_platform）採用 Pydantic 管理設定，支援以環境變數覆寫全域最大循環限制：

# 於環境設定檔 .env 中配置
REWORKD_PLATFORM_MAX_LOOPS=20

此設定對應 platform/reworkd_platform/settings.py 中的 settings.max_loops 參數，從伺服端徹底杜絕超限呼叫。

調整前端介面極限值

若需自訂滑桿上限，可直接修改 Next.js 前端原始碼：

• 於 next/src/pages/settings.tsx 中自訂輸入屬性：

  <Input
    label={`${t("LOOP")}`}
    value={settings.customMaxLoops}
    name="loop"
    type="range"
    onChange={(e) => updateSettings("customMaxLoops", parseFloat(e.target.value))}
    attributes={{
      min: 1,
      max: 50, // 依需求調高上限
      step: 1,
    }}
    helpText={t("CONTROL_THE_MAXIMUM_NUM_OF_LOOPS")}
    icon={<FaSyncAlt />}
    disabled={disableAdvancedSettings}
  />
  

• 於 next/src/utils/constants.ts 中調整預設常數：

  export const DEFAULT_MAX_LOOPS_FREE = 25 as const;
  export const DEFAULT_MAX_LOOPS_CUSTOM_API_KEY = 10 as const;
  

5. 匯出任務成果與執行記錄

當代理順利達成目標或因達上限停止時，即時匯出結果能確保成果不因重新整理頁面而遺失，同時避免重複呼叫帶來的額外成本。

主控制台內建匯出選單

在對話視窗右上角（MacWindowHeader）點擊 Export（匯出） 圖示（CgExport），即可使用三種原生匯出模式：

1. 複製（Copy）：
   • 透過剪貼簿 API 擷取目前面板中的純文字（innerText），涵蓋目標定義、已加入之子任務及各步驟之執行反饋。
   • 便於快速貼入筆記或程式碼編輯器中。
2. 長圖匯出（Image / PNG）：
   • 呼叫前端 html-to-image 模組，完整擷取視窗的滾動內容（element.scrollHeight）。
   • 輸出並下載高解析度的 agent-gpt-output.png，保留完整時間線排版，適合展示或歸檔。
3. 結構化文件（PDF）：
   • 採用 @react-pdf/renderer 技術，透過 PDFButton 元件將訊息陣列依類別格式化：
     • Agent Goal: 標明總體目標；
     • Adding Task: 呈現新建立的子任務；
     • Executing: 呈現各任務的實質輸出與執行結論。
   • 自動生成並下載 my-document.pdf，提供具備閱讀結構的報告樣式。

平台批次匯出與資料庫串接

• 批次匯出（Bulk Exports）：在 Reworkd 商業介面端，可於 app.reworkd.ai/exports 依據群組或工作項目匯出完整的 CSV 或 JSON 格式資料。
• 資料庫直連檢索：在本地自託管環境中，執行紀錄會寫入資料庫的 agent_run 與 agent_task 表格。開發者可直接透過 SQL 查詢或介接 FastAPI 的 /api/agent/execute 端點，將產出無縫導入內部自動化管線。

6. 成本治理實務原則

1. 先設限、後佈署：養成啟動前先進入 Settings 檢查 Loop 數值的習慣，原型驗證建議維持在 5 至 10 次。
2. 雙軌防線阻截過度耗損：將 Loop 次數與 maxTokens（如 1250 ~ 2000）同時收緊，兼顧步驟數與單次回答長度。
3. 初期步驟人工審視：代理執行前兩三個任務時保持關注，若出現偏題立即以 Pause 或 Stop 停機。
4. 結束即刻備份匯出：任務一旦終止或完成，立即使用 Copy 或 PDF 功能存檔，防止前端狀態重置造成資料流失。

(註：開源專案 reworkd/AgentGPT 於 2026 年 1 月正式進入唯讀封存狀態。自行維護分支出版或下游架構的開發團隊，可基於既有架構持續強化上述限制與匯出流程。)

參考資料

• AgentGPT
• GitHub - reworkd/AgentGPT: 🤖 Assemble, configure, and deploy autonomous AI Agents in your browser.
• AgentGPT Settings Page Component
• AgentGPT Console Window Header Component
• AgentGPT PDF Export Implementation
• AgentGPT Backend Platform Settings
• AgentGPT Bulk Exports Documentation