Hotdry.
归档
ai-systems

Anthropic 长运行 Agent 可靠支架实现：自动回滚、评估驱动恢复与故障分类

基于 Anthropic Claude Agent SDK，构建长运行 Agent 的工程化支架，包括双 Agent 架构、Git 回滚、JSON 评估循环与常见故障模式处理参数。

在 AI Agent 向长时序任务演进的当下，Anthropic 工程团队针对 Claude Agent SDK 提出 “Effective harnesses for long-running agents” 方案。该方案通过简单文件支架与提示工程，实现跨越多会话的可靠执行，避免上下文窗口限制导致的遗忘与混乱。核心是模拟人类工程师手 off：用结构化进度文件、Git 历史与端到端测试，确保每个新 Agent 实例快速 “接棒”。

问题诊断：长运行 Agent 的两大痛点

长运行任务（如构建 claude.ai 克隆，超 200 功能点）无法单次上下文窗口完成。常见失败模式包括：

  1. 一次性蛮干：Agent 试图全盘实现，导致中途上下文耗尽，遗留半成品无文档，后续实例需猜测修复，效率低下。
  2. 过早完工：后期实例见部分功能即误判完成，忽略剩余任务。

Anthropic 测试显示，仅靠上下文压缩无效。解决方案转向外部 “harness”：双 Agent 架构 + 三大支柱（功能列表、增量进展、端到端测试）。

支架核心组件与落地参数

1. 双 Agent 架构

  • Initializer Agent（首次会话专用提示）：

    • 生成 init.sh：一键启动开发服务器（e.g., npm run dev）。
    • 创建 claude-progress.txt：记录整体摘要、最近变更。
    • 构建 feature_list.json：详列所有功能，格式如下（初始 passes: false）： 
      {
  "category": "functional",
  "description": "New chat button creates a fresh conversation",
  "steps": [
    "Navigate to main interface",
    "Click the 'New Chat' button",
    "Verify a new conversation is created",
    "Check that chat area shows welcome state",
    "Verify conversation appears in sidebar"
  ],
  "passes": false
}
    • 初始化 Git 仓库，第一 commit 展示文件树。
    • 提示参数：强调 “禁止编辑测试步骤，仅改 passes 字段”；优先级排序功能列表。

  • Coding Agent（后续会话通用提示）：

    • 标准化启动序列（5 步，必执行）：
      1. pwd 确认目录。
      2. 读 claude-progress.txt 与 git log --oneline -20。
      3. 选 feature_list.json 中最高优先未完成项（唯一一項）。
      4. 运行 init.sh 重启服务器。
      5. 跑基础 E2E 测试确认无回归。
    • 实现后：浏览器自动化测试（Puppeteer MCP server，截图验证）；通过则改 passes: true，更新进度文件，Git commit（描述性消息，如 “feat: implement new chat button with E2E tests”）。

2. 自动回滚与并行执行

  • Git 作为回滚层：每个变更后强制 commit。若测试失败，Coding Agent 提示中嵌入 “若引入 bug，用 git revert HEAD 回滚”。阈值：连续 3 次失败后，手动干预或切换模型。
  • 并行执行潜力：虽官方单 Agent，扩展为多轨：用脚本 fork 多个 Coding Agent 实例（不同分支），每轨一功能群。监控脚本每 10min 拉取主分支，merge 通过测试者。参数：分支命名 agent-{id}-{feature}；冲突阈值 <5% 代码变更。

3. 评估驱动恢复循环

  • JSON 评估：功能列表即 “evals”。提示强制 “仅标记 passes 经截图 + 步骤全过”。恢复循环：启动时若发现 passes=false 但文件存在，优先修复（分类：环境 bug → 读 Git log；逻辑错 → 复现步骤）。
  • 监控参数：
    指标 阈值 动作
    会话 token 消耗 >80% 窗口 强制 commit 中止
    功能通过率 <70% 日增 暂停，审阅 progress.txt
    Git commit 频率 <1 / 会话 提示优化，疑过早完工
    测试失败率 >20% 回滚 + 分类日志（env / 逻辑 / 过早）

4. 故障模式分类与处理清单

Anthropic 总结 4 类故障，支架内置应对：

  • 环境遗留：读 init.sh + 测试启动。
  • 过早完工：功能列表全景，强制选未完成。
  • 无文档：进度文件 + Git 强制。
  • 测试不足：Puppeteer 强制 E2E，非 curl 单元。

快速部署清单：

  1. 环境：Node.js + Puppeteer + Claude Agent SDK。
  2. 提示模板：复制官方（工程博客），加 “严格 JSON，无 Markdown”。
  3. 脚本化：Bash wrapper 自动化 Agent 循环（while 未全 passes）。
  4. 扩展：Docker 隔离；Prometheus 监控 commit/tests。
  5. 回滚策略：每日 snapshot 分支；人工阈值：>5 连续失败。

工程价值与风险限界

此 harness 将 Claude Opus 4.5 在 claude.ai 克隆任务中成功率从 <20% 提至稳定增量（每会话 1-2 功能）。观点：简单文件> 复杂框架；证据如 Git 日志可审计，远胜纯提示。

风险：领域限 Web 开发，泛化科研需调 JSON 步骤；单 Agent vs 多 Agent 未定，建议 A/B 测试。

资料来源：Anthropic 工程博客《Effective harnesses for long-running agents》（2025-11-27），Hacker News 讨论，腾讯新闻总结。实际部署请参考官方 SDK 示例仓库。

（正文约 1050 字）

查看归档