五层 Agent 工程手册：指令、上下文、执行环境、局部收敛与跨节点控制
直接阅读： 下载 54 页 PDF · 单文件 Markdown · 离线 HTML
本版包含 9 张统一手绘风插图：1 张封面与 8 张核心概念图。章节文件仍保留为独立 Markdown，便于按主题阅读和引用。
过去几年，Agent 圈先后流行过 Prompt Engineering、Context Engineering、Harness Engineering、Loop Engineering 和 Graph Engineering。它们很容易被讲成一串互相替代的版本号，但更准确的理解是：它们分别控制 Agent 系统的不同工程边界。
这套手册提供一个统一但非官方的五层模型：
| 层 | 核心问题 | 主要产物 |
|---|---|---|
| Prompt | 这一轮要模型做什么？ | 指令、约束、输出契约、示例 |
| Context | 这一轮让模型看见什么？ | 上下文选择、检索、压缩、记忆装载 |
| Harness | 模型能在什么环境里行动？ | 工具、权限、沙箱、运行时、观测 |
| Loop | 一个工作单元如何根据证据收敛？ | 状态、动作、验证、反馈、停止条件 |
| Graph | 多个工作单元如何连接与恢复？ | 节点、边、共享状态、路由、检查点、审批 |
一句话版本：
Prompt 决定“怎么说”
Context 决定“看什么”
Harness 决定“能做什么”
Loop 决定“如何反复做到”
Graph 决定“多个工作单元如何协作”
- 五层不是替代关系。外层依赖内层，生产系统通常会同时拥有五层。
- Loop 与 Graph 不冲突。从拓扑上看，Loop 可以表示为带回边的简单 Graph；从工程职责上看，Loop 管局部收敛，Graph 管跨节点控制。
- Graph 不等于多 Agent。节点可以是普通代码、一次模型调用、工具调用，也可以是内部带 Loop 的完整 Agent。
- Graph Engineering 也不等于知识图谱。前者首先讨论控制流、状态与恢复；知识图谱讨论实体及关系，二者可以结合但不是同一概念。
- 不是任务重复就必须上 Graph。关键是路径是否稳定、状态是否要跨节点持久化、失败是否值得局部恢复、结果是否能机械验收。
- 最常见的生产形态不是 “Loop 或 Graph”，而是 外层 Graph，内层 Loop。
- 为什么需要五层模型
- Prompt Engineering：把这一轮话说清楚
- Context Engineering：管理有限的注意力预算
- Harness Engineering：设计 Agent 与环境的接口
- Loop Engineering：让一个工作单元根据证据收敛
- Graph Engineering：把跨节点控制显式化
示例只使用 Python 标准库，不需要 API Key。它们使用可预测的测试 Worker，把注意力放在控制结构而不是某个模型 SDK 上：
$env:PYTHONUTF8='1'
python -m examples.stage_01_prompt
python -m examples.stage_02_context
python -m examples.stage_03_harness
python -m examples.stage_04_loop
python -m examples.stage_05_graph
python -m examples.stage_06_hybrid
python -m unittest discover -s tests -v六个示例使用同一个“技术简报”任务，逐层增加能力：
| 示例 | 新增能力 |
|---|---|
stage_01_prompt.py |
目标、约束与输出契约 |
stage_02_context.py |
在预算内选择高信号材料 |
stage_03_harness.py |
工具白名单、输入校验与执行记录 |
stage_04_loop.py |
生成—验证—反馈—重试 |
stage_05_graph.py |
显式节点、条件边、持久状态与恢复 |
stage_06_hybrid.py |
外层 Graph 编排、内层 Loop 收敛 |
这些代码是教学用最小实现，不是对 LangGraph、Temporal、Dagster 或其他生产运行时的替代。
如果想先检验自己是否分得清五层：
python exercises/layer_diagnosis.py再完成 五层故障定位 checkpoint。可单独打开的五层关系图位于 diagrams/five-layers.html。
- 不声称五个术语有严格、统一的学术定义。
- 不声称 Agent 工程一定要按五层依次升级。
- 不声称 Graph 天然比 Loop 更可靠、更便宜或更智能。
- 不把社交媒体转述的 AutoResearch 运行数字包装成 Loop 与 Graph 的对照实验。
- 不把一份独立汇编的 Graph Engineering PDF 误称为 Karpathy 或 Anthropic 官方材料。
这套模型的价值是给设计、排错和选型提供共同语言：当系统失败时，我们可以先问“失败发生在哪一层”，而不是第一反应就换模型或增加 Agent。
- 版本：
0.2.0 - 核验日期：2026-07-28
- 语言：中文
- 许可证：MIT