Agent 循环引擎

概述

**Agent 循环引擎（Agent Loop）**是工作空间 Claw 模块的核心执行机制。它驱动 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 先列计划再执行（"先列一个计划，等我确认后再执行"）