Agent循环状态机设计：工具编排、上下文分配与错误恢复策略

从无限循环到有界状态机

传统 ReAct 模式的 Agent 实现往往陷入一个危险的陷阱：while not task_complete的无限循环结构。这种模式在演示环境中表现良好，但在生产环境中却暴露出致命缺陷：Agent 可能在推理中陷入死循环、工具调用幻觉导致数据损坏、上下文窗口膨胀使延迟飙升至 12 秒以上。

DeepSeek Reasonix 的架构设计揭示了一个关键洞察：生产级 Agent 需要状态机约束，而非开放式循环。通过引入显式的状态定义、转换条件和强制退出机制，可以将 Agent 的执行轨迹从不可控的无限空间压缩到可预测的有界空间。

状态机核心设计

状态定义与转换图

一个健壮的 Agent 循环应包含以下核心状态：

[INIT] → [REASON] → [PLAN] → [EXECUTE] → [VERIFY] → [COMPLETE]
           ↑           ↓           ↓           │
           └──────── [RECOVER] ← [FAILED] ────┘

状态说明：

• INIT：初始化阶段，加载系统提示词、工具定义、会话上下文
• REASON：推理阶段，分析当前上下文并生成思考过程
• PLAN：规划阶段，确定下一步工具调用序列
• EXECUTE：执行阶段，实际调用工具并获取结果
• VERIFY：验证阶段，检查结果有效性并评估置信度
• COMPLETE：完成阶段，输出最终结果并清理资源
• FAILED：失败状态，记录错误上下文
• RECOVER：恢复阶段，尝试修复或降级处理

关键转换条件

每个状态转换都应配备明确的守卫条件（guard conditions）：

上下文窗口三分区架构

分区策略

Reasonix 采用的 Cache-First Loop 架构将上下文划分为三个严格隔离的区域：

┌─────────────────────────────────────────┐
│ IMMUTABLE PREFIX (固定前缀)              │
│   system prompt + tool_specs + few_shots │ ← 会话级缓存，命中率>90%
├─────────────────────────────────────────┤
│ APPEND-ONLY LOG (追加日志)               │
│   [assistant₁][tool₁][assistant₂]...    │ ← 单调增长，保留前缀连续性
├─────────────────────────────────────────┤
│ VOLATILE SCRATCH (临时草稿)              │
│   reasoning_content, transient plan     │ ← 每轮重置，不上传上游
└─────────────────────────────────────────┘

设计约束：

1. Immutable Prefix：仅在会话初始化时计算一次，哈希值固定。包含系统提示词、工具定义、少样本示例，利用 DeepSeek 的 prefix caching 机制（缓存命中成本仅为未命中的 10%）。
2. Append-Only Log：严格按追加顺序序列化，禁止任何重写操作。这是保证缓存命中率的核心 —— 一旦重写，前缀匹配失效。
3. Volatile Scratch：存放 R1 推理链、临时计划状态等易变内容。通过 Pillar 2 的蒸馏机制，在折叠到 Log 前提取关键信息。

上下文压缩策略

当工具返回结果超过TURN_END_RESULT_CAP_TOKENS（默认 3000 tokens）时，触发自动压缩：

// 伪代码示例
if (toolResult.tokens > TURN_END_RESULT_CAP_TOKENS) {
  const summary = await llm.summarize(toolResult, {
    model: 'v4-flash',
    effort: 'high',
    maxOutputTokens: 800
  });
  appendToLog(summary);
} else {
  appendToLog(toolResult);
}

预压缩阈值：当上下文比例达到 40% 时，主动触发压缩，避免触及 80% 的紧急阈值。

工具编排与并行调度

并行安全声明

每个工具在注册时需声明parallelSafe属性（默认为 false）：

interface ToolSpec {
  name: string;
  description: string;
  parameters: JSONSchema;
  parallelSafe?: boolean;  // 默认false
  timeout?: number;         // 默认5s
}

并行安全工具类型：

• 只读文件系统操作：read_file, list_directory, search_files
• 网络查询：web_search, web_fetch
• 内存检索：recall_memory, semantic_search
• 子 Agent 调用：run_skill, spawn_subagent

串行屏障工具：

• 文件修改：write_file, edit_file
• 命令执行：run_command
• 数据库写入操作

调度算法

调度器将连续的并行安全调用分组为 chunks，使用Promise.allSettled执行：

async function dispatchChunk(calls: ToolCall[]): Promise<ToolResult[]> {
  const results = await Promise.allSettled(
    calls.map(call => executeWithTimeout(call, TOOL_TIMEOUT))
  );
  
  // 保持声明顺序，无论哪个调用先完成
  return results.map((result, index) => ({
    callId: calls[index].id,
    status: result.status,
    value: result.status === 'fulfilled' ? result.value : null,
    reason: result.status === 'rejected' ? result.reason : null
  }));
}

配置参数：

• REASONIX_PARALLEL_MAX：最大并行数，默认 3，硬上限 16
• REASONIX_TOOL_DISPATCH=serial：强制串行调度的逃生舱

四级错误恢复机制

Level 1: 参数扁平化修复

当工具 schema 包含超过 10 个叶子参数或嵌套深度超过 2 层时，自动触发扁平化：

// 原始schema（嵌套）
{
  "config": {
    "database": {
      "host": "...",
      "port": 5432
    }
  }
}

// 扁平化呈现给模型
database.host = "..."
database.port = 5432

Level 2: 工具调用回收

模型可能在reasoning_content中生成工具调用，但未在tool_calls字段中正式声明。通过正则 + JSON 解析器扫描推理内容，回收遗漏的调用：

function scavengeToolCalls(reasoning: string): ToolCall[] {
  const pattern = /```json\s*(\{[\s\S]*?\})\s*```/g;
  const matches = reasoning.matchAll(pattern);
  return matches
    .map(m => safeParseJSON(m[1]))
    .filter(obj => obj && obj.name && obj.arguments);
}

Level 3: 截断修复

当max_tokens限制导致 JSON 结构截断时，检测未平衡的括号并请求续写：

function repairTruncation(partialJSON: string): string {
  const openBraces = (partialJSON.match(/\{/g) || []).length;
  const closeBraces = (partialJSON.match(/\}/g) || []).length;
  const missing = openBraces - closeBraces;
  
  if (missing > 0) {
    return partialJSON + '}'.repeat(missing);
  }
  return partialJSON;
}

Level 4: 调用风暴抑制

在滑动窗口内检测到重复的(tool, args)元组时，抑制重复调用并注入反思轮次：

function detectStorm(calls: ToolCall[], windowSize: number = 5): boolean {
  const recent = calls.slice(-windowSize);
  const signatures = recent.map(c => `${c.name}:${JSON.stringify(c.arguments)}`);
  const unique = new Set(signatures);
  return unique.size < signatures.length;  // 存在重复
}

可落地参数配置

核心阈值参数

模型分层策略

监控指标

interface LoopMetrics {
  // 每轮指标
  turnCost: number;           // 当前轮成本
  cacheHitRate: number;       // 缓存命中率
  stepCount: number;          // 实际执行步数
  repairCount: number;        // 修复触发次数
  
  // 会话级指标
  sessionCost: number;        // 累计成本
  avgLatency: number;         // 平均延迟
  toolSuccessRate: number;    // 工具调用成功率
}

实施检查清单

状态机实现：

• 定义所有状态及转换条件
• 实现状态守卫（guard conditions）
• 配置最大步数限制（max_steps）
• 设计确定性回退策略（fallback）

上下文管理：

• 实现三分区架构
• 配置 prefix pinning 机制
• 设置自动压缩阈值
• 验证缓存命中率监控

工具编排：

• 标注所有工具的 parallelSafe 属性
• 实现 chunk 分组算法
• 配置并行数上限
• 测试串行屏障逻辑

错误恢复：

• 集成四级修复管道
• 配置失败升级阈值
• 实现调用风暴检测
• 设置工具超时策略

总结

生产级 Agent 循环的设计核心在于约束而非开放。通过状态机将执行空间限制在有界范围内，通过三分区架构优化上下文管理成本，通过四级修复机制提升系统韧性。这些设计不是对 Agent 能力的限制，而是对生产环境可靠性的保障。

关键设计原则可归纳为：显式状态优于隐式循环、追加写入优于随机访问、并行安全显式声明优于隐式假设、分层降级优于单一模型硬撑。

资料来源：

• Reasonix Architecture Documentation (esengine.github.io)
• "I Reverse-Engineered DeepSeek's Agent Architecture" by Shivam Singla

ai-systems