Agent 循環引擎

概述

**Agent 循環引擎（Agent Loop）**是工作空間 Work 模組的核心執行機制。它驅動 AI Agent 進行自主推理-執行循環：分析任務 → 選擇工具 → 執行操作 → 評估結果 → 繼續推理，直到任務完成或觸發退出條件。

引擎採用 provider-agnostic 架構，透過統一的 LLM Adapter 介面支援多種模型供應商。

架構

LLM 適配器

AgentEngine │ ├── OpenAIAdapter │ ├── Responses API（增量狀態管理） │ └── Chat Completions API（全量上下文） │ └── AnthropicAdapter └── Messages API（原生 streaming + thinking）

                      
                      AgentEngine
    │
    ├── OpenAIAdapter
    │   ├── Responses API（增量狀態管理）
    │   └── Chat Completions API（全量上下文）
    │
    └── AnthropicAdapter
        └── Messages API（原生 streaming + thinking）

此代碼塊在浮窗中顯示

適配器自動處理：

訊息格式轉換（OpenAI ↔ Anthropic）
工具定義轉換
Think Tag 處理（自動剝離 DeepSeek 等模型的 <think> 標籤）

循環流程

┌─ 預檢驗證 ──────────────────────────────────────────────┐ │ 拒絕超過輸入預算 60% 的提示詞，防止靜默截斷 │ └──────────────────────────┬──────────────────────────────┘ ▼ ┌─ 主循環（Round 0 → maxTurns-1）─────────────────────────┐ │ │ │ ① 上下文管理 │ │ - 預防性工具結果截斷（Layer 1） │ │ - 檢查是否需要壓實（shouldPreemptiveCompact） │ │ │ │ ② LLM 呼叫 │ │ - 串流推理（text_delta + thinking + tool_use） │ │ - 事件即時推送到 UI │ │ │ │ ③ 工具執行 │ │ - validateToolCalls → 驗證合法性 │ │ - 併發分區 → 按 concurrency 中繼資料分組 │ │ - 並行執行 → 結果歸一化 │ │ │ │ ④ 退出判斷 │ │ - 無工具呼叫 → 退出（end_turn） │ │ - 達到限制 → 退出（max_rounds/max_budget/deadline） │ │ - 異常 → 退出（circuit_breaker/fatal_error） │ │ - 有工具呼叫 → 繼續下一輪 │ │ │ └──────────────────────────────────────────────────────────┘

                      
                      ┌─ 預檢驗證 ──────────────────────────────────────────────┐
│ 拒絕超過輸入預算 60% 的提示詞，防止靜默截斷              │
└──────────────────────────┬──────────────────────────────┘
                           ▼
┌─ 主循環（Round 0 → maxTurns-1）─────────────────────────┐
│                                                          │
│  ① 上下文管理                                            │
│     - 預防性工具結果截斷（Layer 1）                        │
│     - 檢查是否需要壓實（shouldPreemptiveCompact）          │
│                                                          │
│  ② LLM 呼叫                                              │
│     - 串流推理（text_delta + thinking + tool_use）        │
│     - 事件即時推送到 UI                                   │
│                                                          │
│  ③ 工具執行                                              │
│     - validateToolCalls → 驗證合法性                      │
│     - 併發分區 → 按 concurrency 中繼資料分組              │
│     - 並行執行 → 結果歸一化                               │
│                                                          │
│  ④ 退出判斷                                              │
│     - 無工具呼叫 → 退出（end_turn）                       │
│     - 達到限制 → 退出（max_rounds/max_budget/deadline）   │
│     - 異常 → 退出（circuit_breaker/fatal_error）          │
│     - 有工具呼叫 → 繼續下一輪                             │
│                                                          │
└──────────────────────────────────────────────────────────┘

此代碼塊在浮窗中顯示

循環參數

參數	預設值	說明
`maxTurns`	25	最大循環輪次
`maxErrors`	—	連續工具錯誤閾值
`maxBudgetInputTokens`	—	輸入 token 預算上限
`maxExecutionMs`	—	執行時間上限（毫秒）
`snapshotStrategy`	`every_tool_round`	快照儲存策略
`resumeSessionId`	—	還原中斷會話的 ID

8 種退出條件

退出原因	觸發條件
end_turn	Agent 完成任務，無更多工具呼叫
max_rounds	達到 maxTurns 上限（預設 25 輪）
circuit_breaker	連續 5 次 LLM 呼叫失敗
no_tool_calls	LLM 回應中無工具呼叫請求
user_cancel	使用者手動中止
context_overflow	上下文壓縮後仍然溢位
fatal_error	不可還原的錯誤（認證失敗、計費問題等）
compaction_exhausted	壓縮重試次數耗盡（最大 5 次）

斷路器機制

防止 LLM 連續失敗導致無限重試：

參數	值	說明
`CIRCUIT_OPEN_THRESHOLD`	5	連續失敗 5 次觸發斷路器
`CIRCUIT_OPEN_WAIT_MS`	60,000	斷路器打開後冷卻 60 秒

錯誤分類與重試策略：

錯誤類型	策略
`rate_limit`	指數退避 + 隨機抖動重試
`timeout` / `overloaded`	立即重試
`context_overflow`	觸發上下文壓縮
`auth` / `billing` / `model_not_found`	直接拋出（不重試）

串流事件

Agent 執行過程透過串流事件即時通知 UI：

事件類型	資料	說明
`text_delta`	文字片段	Agent 文字輸出的增量推送
`thinking`	思維片段	原生思維鏈內容（Anthropic thinking 模型）
`tool_use_start`	工具名 + 參數	工具呼叫開始
`tool_result`	執行結果	工具執行完成
`error`	錯誤訊息	執行過程中的錯誤
`done`	退出原因	本輪循環結束

子代理的事件會透傳到父 Agent 的 UI 介面。

EMA Token 校準

引擎使用**指數移動平均（EMA）**動態校準 token 估算精度：

參數	值	說明
初始值	3.0 chars/token	保守估算（適配中文 + 程式碼混合場景）
前 3 次	均值收斂	快速接近真實值
後續	EMA α=0.15	平滑追蹤實際消耗
過濾	0.5 < observed < 8	排除異常值

每次 LLM 呼叫後，用實際 token 消耗更新校準因子，確保上下文預算估算越來越準確。

會話快照

支援持久化會話狀態，防止意外中斷遺失進度：

策略	觸發時機
`every_tool_round`（預設）	每次工具呼叫完成後
`every_round`	每輪 LLM 互動後
`manual`	僅手動觸發

快照儲存為 JSON 檔案，使用原子寫入（.tmp + rename）防止檔案損毀。透過 resumeSessionId 可還原中斷的會話。

對使用者意味著什麼

Agent Loop 是你能感受到的「Agent 在連續工作」的能力。 當你說「幫我重構這個專案的程式碼結構」，Agent 不會只回一句建議就停下——它會自動瀏覽檔案、分析結構、逐個修改、執行測試，直到完成。

你能觀察到的現象：

Agent 連續呼叫多個工具（列檔案 → 讀檔案 → 修改檔案 → 執行測試），介面上工具呼叫依次出現
如果 Agent 連續失敗 5 次（如 API 逾時），它會暫停 60 秒而不是無限重試——你會看到一段等待後 Agent 告訴你遇到了問題
預設最多執行 25 輪，極端複雜的任務可能會在 25 輪後停止，並告訴你「已達到最大輪次」

你可以做什麼：

在任何時候點擊停止按鈕中止 Agent 的執行
如果 Agent 執行方向偏了，中止後給出更明確的指示
對於特別複雜的任務，可以讓 Agent 先列計畫再執行（「先列一個計畫，等我確認後再執行」）