来源：抖音 @益牙是AI教练
核心原则：让长程Agent稳定运行的四大铁律
设计一个能够自主跑完长程任务的Agent系统，本质上是一个典型的分布式系统设计问题。为了确保Agent在复杂环境下不“跑偏”、不崩溃，需要遵循以下四条核心设计铁律。
1. 别把循环简单等同于 While 循环
许多Agent“变笨”的根源在于将执行流程简化为单一的 while 循环（即：调模型->跑工具->丢结果->再来一遍）。这种扁平化的结构无法处理长程任务的复杂性。
正确的做法是对循环进行精细化分层：
- Turn-level (单轮)：对应一次LLM调用。包括组上下文、调模型、解析工具、执行工具、回传结果。
- Task-level (任务级)：将多个Turn拼装成一次完整的任务执行。拥有 Plan（计划）-> Act（执行）-> Verify（验证）的完整生命周期，具备终止条件和异常处理机制。
- Session-level (会话级)：管理任务间的持久状态、Session生命周期，以及跨任务的 Checkpoint（检查点）。
通过这种分层，可以在不同层级控制不同的循环逻辑，例如“跑一轮失败重试，跑完一任务归档”。
2. 状态要外置，上下文靠不住
对于长程Agent，其运行的状态绝不能仅依赖大模型有限的上下文窗口。
- 避免上下文过载：很多人认为给了100万 Token 窗口就万事大吉，这是巨大的误区。真正的多日任务，上下文不仅装不下，而且会产生严重的“Context Rot”（上下文旋转/退化），在达到窗口上限前性能就会拖垮。
- 状态外置方案：核心原则是“Agent是健忘的，但文件系统不会忘”。应将Agent的状态写入外部文件。
AGENTS.md：保存项目规范、约束及历史教训。plan.md：记录里程碑、验收标准和已做决策。progress.txt：实时更新已完成内容和当前卡点。init.sh：初始化环境脚本。
这种方式能保证无论Session如何重启，Agent都能通过读取文件快速恢复现场。
3. Workspace 不是临时目录
在多Agent协作场景下，Workspace（工作空间）不应被视为用完即弃的临时目录，而应作为Agent的运行时现场和操作基座。
- Git Worktree 隔离：推荐使用 Git Worktree 技术。即使多个Agent在同一个
.git对象库下，也可以 checkout 到不同的独立目录。这既实现了文件隔离，避免了并行Agent间的文件冲突，又无需进行完整的代码克隆，运行效率极高。 - 运行环境持久化：Workspace 应包含 Agent 的思考日志（Event Log）、Session 状态文件等。它是Agent感知物理世界和执行操作的唯一入口。
4. 别盲目重试，先修状态
Agent 常见的“死法”莫过于：工具调用出错 -> 盲目重试 -> 再次出错 -> 再次重试 -> 耗尽 Budget 烧光。重试本身不是问题，问题在于是否知道错误类别。
需要根据错误类型采取不同的精细化处理策略：
- 瞬态错误（如网络超时/限流）：可以采用指数退避重试（不要超过五到六次）。
- 可规划错误（如工具返回意外结果、路径不通）：不要盲目重试，而是改变 Plan 或 State 后重新执行。
- 永久错误（如权限不够、任务本身不可能）：停止挣扎，停下来并反馈给人类或丢弃任务。
- 语义错误（模型理解歪了、方向错了）：改写 Plan 重来，不要试图用同样的操作再碰一次。
总结
长程Agent的系统设计，本质上是在解决分布式系统中的通信不可靠、状态持久化、资源隔离等经典问题。通过分层循环、外部状态存储、Git隔离工作区及分类错误恢复，可以显著提高长程任务端到端执行的概率。