Anthropic Agent 工程实战笔记（四）长任务与多 Agent

桂花很香,旭很美2026-02-24 11:01

本模块主要参考（官方）

  • 1\] [Effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)（Anthropic Engineering，Nov 2025）

  • 3\] [Code execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp)（Anthropic Engineering）

本模块在整体中的位置

前三个模块解决了「选形态、做工具、管 context」；当任务从「单次对话」变成跨多 context window、多 session、甚至多 Agent 协作 时，会出现「一次做太多、过早宣布完成、环境脏、进度不可见、没验证就标完成」等典型失败。本模块讲如何用 Harness （长任务运行框架：Initializer （首轮生成功能列表与环境配置）+ Coding Agent （每轮执行开发与验证的 Agent））和多 Agent 架构把这些失败模式系统化解掉。依赖 01（选型）、02（工具设计）、03（上下文/记忆）；若工具设计或 context 管理没做好，长任务 Harness 会事倍功半。

逻辑线索（本模块阅读顺序）

  1. 失败模式：先看清长跑 Agent 常犯的几类错（做太多、早宣布完成、环境脏、未验证就标完成）。
  2. 对策表 ：Initializer 与 Coding Agent 分别负责什么（feature list （功能项列表 JSON，每项含 passes 等）、progress、git、端到端验证（像真实用户一样跑完整流程验证，如浏览器））。
  3. 具体做法 ：feature_list 结构、每轮「上场就位」（读进度、跑冒烟、再选下一项）步骤。
  4. 多 Agent 与执行 ：Orchestrator--Workers （中心编排 + 多个子 Worker，见 03 §3.3）、MCP（Model Context Protocol，见 01）代码执行。

本模块总流程图：Harness 与长跑一轮 [1]

是
否
是
否
用户目标
Initializer
feature_list.json
init.sh + claude-progress.txt + git
Coding Agent 每轮
上场就位: 读 progress + git + 跑 init + 冒烟
选一项未完成功能
开发 + 端到端验证
验证通过?
更新 passes + commit + progress
还有未完成?
完成

1. 长跑 Agent 的典型失败与对策 [1]

  • 据 [1]，一次做太多 / 过早宣布完成 ：用 Initializer 在首轮生成功能列表（如 feature_list.json），每项带描述与 passes（该功能项是否已通过验证的布尔标记）状态；Coding Agent 每轮只攻一项，且只有在端到端验证通过后才把该项标为 passes。强烈禁止删改测试项。
  • 环境脏、进度不可见 [1]：Initializer 建 init.sh、claude-progress.txt、初始 git commit；Coding Agent 每轮开始读 progress + git log，先跑基础冒烟，再选下一个未完成功能；结束时写 commit 与 progress 更新。
  • 没做端到端验证就标完成 [1]：明确要求用浏览器自动化等做「像用户一样」的验证，仅单元测试或 curl 不足；提供 Puppeteer（浏览器自动化工具）等 MCP 可显著减少「代码看起来对但实际跑不通」的情况。

2. Harness 设计要点表 [1]

据 [1] 整理的失败模式与对策对应关系：

问题 Initializer 行为 Coding Agent 行为
过早宣布整体完成 生成结构化功能列表（如 JSON），全部初始为未通过 每轮只选一个未完成项；仅验证通过后改 passes
环境有 bug 或进度不明 建 git 与 progress 文件 开场读 progress + git log，跑 init.sh 与基础测试；结束写 commit + progress
未验证就标完成 同上 必须做端到端自测后再改状态
不知道如何跑项目 写 init.sh 启动开发环境 开场读 init.sh，先确认能跑再开发

3. 功能列表与「上场就位」流程

3.1 功能列表示例（feature_list.json）[1]

Initializer 根据用户目标展开为可勾选的功能项，每项含 category、description、steps、passes。完整文件为上述结构的数组（见 §3.5）。单条示例如下：

json 复制代码 
{
  "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
}
  • 只允许 Coding Agent 修改 passes 字段；禁止删除或改写测试项，以免漏功能或引入 bug。
  • 用 JSON 而非 Markdown 可减少模型误改结构的概率。

3.2 每轮开场「上场就位」步骤 [1]

据 [1]，每轮开场建议顺序为：

  1. 读 feature list，选一个未完成的最高优先级项。
  2. 读 git log 与 progress 文件，了解最近做了什么。
  3. 跑 pwd 确认工作目录；只允许在该目录下改文件。
  4. 若有 init.sh，跑它启动开发环境；跑一次基本端到端测试（如用 Puppeteer 打开应用、发消息、收回复），确认没有遗留坏状态再开始新功能。

这样可在每轮少用 token，并尽早发现上一轮留下的问题。原因 [1]：长跑时每轮都是「新 context」；若没有结构化进度与冒烟测试，新 session 会花大量 token 猜「上次做到哪、现在坏没坏」，甚至在新功能上叠加旧 bug。

3.3 典型一轮开场的对话流 [1]

每轮开场 Agent 会按「上场就位」步骤执行，原文给出的典型消息序列如下（便于你对照自己的实现或日志）：

复制代码 
[Assistant] I'll start by getting my bearings and understanding the current state of the project.
[Tool Use] <bash - pwd>
[Tool Use] <read - claude-progress.txt>
[Tool Use] <read - feature_list.json>
[Assistant] Let me check the git log to see recent work.
[Tool Use] <bash - git log --oneline -20>
[Assistant] Now let me check if there's an init.sh script to restart the servers.
<Starts the development server>
[Assistant] Excellent! Now let me navigate to the application and verify that some fundamental features are still working.
<Tests basic functionality>
[Assistant] Based on my verification testing, I can see that the fundamental functionality is working well. ... Now let me review the tests.json file more comprehensively to understand what needs to be implemented next.
<Starts work on a new feature>

这样先定位 + 读进度 + 跑冒烟，再选下一个功能开发，避免在坏状态上继续堆代码。

3.4 分流程图：每轮开场顺序

读 feature_list
读 progress + git log
pwd / init.sh
跑基础端到端测试
选下一未完成项开发

3.5 可运行代码示例：feature_list 与 init.sh [1]

以下为可直接使用 的 Harness 工件示例：feature_list.json 与 init.sh。Initializer 可生成类似 JSON；Coding Agent 每轮只改 passes 字段。

feature_list.json（仅保留两项示意）：

json 复制代码 
[
  {
    "category": "functional",
    "description": "New chat button creates a fresh conversation",
    "steps": ["Navigate to main", "Click New Chat", "Verify new conversation", "Check welcome state"],
    "passes": false
  },
  {
    "category": "functional",
    "description": "User can send a message and see it in thread",
    "steps": ["Open thread", "Type message", "Send", "Verify message in thread"],
    "passes": false
  }
]

init.sh（开发环境启动与基础检查；按项目替换）：

bash 复制代码 
#!/usr/bin/env bash
set -e
cd "$(dirname "$0")"
# 若为 Node 项目示例：
# npm install
# npm run build
# npm run dev &
# sleep 3
# curl -s -o /dev/null -w "%{http_code}" http://localhost:3000 || true
echo "Init done. Run smoke test (e.g. Puppeteer) before starting next feature."

Coding Agent 每轮应先执行：cat claude-progress.txt、cat feature_list.json、git log --oneline -20、./init.sh，再选未完成项开发；验证通过后仅更新对应项的 passes: true 并 commit。

示例：读 feature_list 选下一未完成项 [1]

每轮开场可用脚本选出第一个未通过项，再交给 Agent 实现：

python 复制代码 
import json

def next_unfinished(feature_list_path: str = "feature_list.json") -> dict | None:
    with open(feature_list_path, "r", encoding="utf-8") as f:
        items = json.load(f)
    for i, item in enumerate(items):
        if not item.get("passes", False):
            return {"index": i, "description": item["description"], "steps": item.get("steps", [])}
    return None

# 使用
if n := next_unfinished():
    print(f"下一项: [{n['index']}] {n['description']}")
else:
    print("全部完成")

LangGraph 1.0 下 feature_list 读取与 next_unfinished 的用法与上一致（无框架差异）；完整 Harness 与图的结合示例见 延伸阅读 的「五、LangGraph 1.0 对照代码」§5.4。

4. 多 Agent 与执行环境 [2][3]

  • 多 Agent 研究系统 [2]：Orchestrator--Workers；子 Agent 做深度探索后只返回压缩结果，主 Agent 综合决策；复杂研究与分析类任务收益明显。架构细节见原文。
  • MCP 代码执行 [3]：通过 MCP 统一管理代码执行环境，便于隔离与复用；与（六）安全与生产 中的沙箱配合。

参考文献（本模块）

编号 来源 链接
[1] Anthropic, Effective harnesses for long-running agents https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
[2] Anthropic, How we built our multi-agent research system https://www.anthropic.com/engineering/multi-agent-research-system
[3] Anthropic, Code execution with MCP https://www.anthropic.com/engineering/code-execution-with-mcp

5. 实战自检清单

  • 长任务是否有「首轮 Initializer」生成 feature list + init.sh + progress + 初始 commit？
  • Coding Agent 是否每轮只做一项、且用端到端（如浏览器）验证后才改 passes？
  • 是否每轮开场读 progress + git log 并跑基础测试，避免在坏状态上继续开发？
  • 是否需要多 Agent？若需要，是否明确主 Agent 与子 Agent 的输入输出与压缩格式？

6. 本模块要点回顾（便于自检与分享）

  • 问题：长跑 Agent 易出现「一次做太多、过早宣布完成、环境脏、未验证就标完成」。
  • 对策：Initializer 建 feature list、init.sh、progress、git；Coding Agent 每轮只做一项、读 progress+git、跑冒烟、端到端验证后才改 passes。
  • 纪律：只允许改 passes 字段；禁止删改测试项；用 JSON 功能列表减少误改。
  • 多 Agent：Orchestrator--Workers，子 Agent 返回压缩结果；MCP 统一代码执行环境。

7. 延伸

相关推荐
今儿敲了吗1 小时前
30| 木材加工
数据结构·c++·笔记·学习·算法
土拨鼠烧电路1 小时前
笔记08：供应链的生命线：预测、库存与韧性
人工智能·笔记
hqk1 小时前
鸿蒙项目实战：手把手带你从零架构 WanAndroid 鸿蒙版
前端·架构·harmonyos
xhyu611 小时前
【学习笔记】推荐系统 (3.召回：矩阵补充、线上服务、双塔模型)
笔记·学习·矩阵
wb1891 小时前
LVS各种调度以及Haproxy调度重习
笔记·云计算·lvs·haproxy
fanged2 小时前
IT数学基础番外1--手算梯度下降（TODO）
笔记
Kayshen2 小时前
春节期间我们开源了一个 AI-Native 的矢量设计工具，对标 Pencil.dev，让 AI Agent 直接画 UI
前端·aigc·agent
日更嵌入式的打工仔2 小时前
C/S 与 B/S 架构
笔记
蒸蒸yyyyzwd2 小时前
数据库学习笔记
数据库·笔记
热门推荐
01GitHub 镜像站点02AI Agent 平台横评：ZeroClaw vs OpenClaw vs Nanobot03Claude Code + GLM4.7 避坑指南：解决 Unable to connect to Anthropic services04【OpenClaw 本地实战 Ep.3】突破瓶颈：强制修改 openclaw.json 解锁 32k 上下文记忆05Clawdbot部署教程：解决‘gateway token missing’授权问题的完整步骤06openClaw安装飞书插件｜核心踩坑：spawn EINVAL 错误终极解决指南07全面体验 Grok API 中转站（2025 · Grok 4 系列最新版）08HTML 早已不是标签了，它现在是系统级接口：这 9 个 API 直接干翻常用 JS 库09AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南10jdk21下载、安装（Windows、Linux、macOS）