为什么光有大模型还不够?learn-agent-architecture 讲透Agent驾驭工程(Harness)的核心命题
为什么光有大模型还不够?learn-agent-architecture 讲透Agent驾驭工程(Harness)的核心命题
"为什么大模型明明很聪明,却不能自己干活?"——这正是开源教程 learn-agent-architecture 要回答的核心问题。该项目用 24 个章节系统讲解 Agent 驾驭工程(Harness Engineering):模型只负责推理,而把推理变成受控行动的工具、状态、权限和循环,全部由模型外面那层代码——也就是 harness——来承担。🧠
为什么大模型推理 ≠ 能干活的 Agent
先记住一句话,它就是整个项目的立身之本:
模型负责推理。Harness 负责执行。
一次孤立的模型调用只能"根据输入产出一个响应"。它可以判断接下来该做什么,却做不到以下任何一件事:
- ❌ 自己执行工具、读写文件或运行命令
- ❌ 在多次调用之间保留工作进度(它没有持久状态)
- ❌ 在执行有副作用的操作前进行安全检查
- ❌ 把执行结果收回来,作为下一步推理的输入
所以,一个真正能"动手"的 AI Agent = 大模型 + 一套驾驭它的 harness。没有这层外壳,模型只能停留在聊天机器人的层次。
上图来自 sections/00-harness-thesis/ 开篇章节,展示了 harness 与模型的经典分工:
- 提供执行环境——工具运行时让模型"说"出来的动作能真正发生;
- 回传执行结果——把工具输出变成模型下一轮的"观察";
- 把关副作用——在权限关卡(Permissions)放行之前,任何写操作都不碰真实系统;
- 保存状态——让第 N 次调用能接续前 N-1 次的进度。
项目还有一个反直觉的观点值得新手警惕:harness 不是越复杂越好。每一层外壳都是在补"当下这代模型做不到"的事,模型换代时,原来需要的规划、重试、检查可能新模型自己就会做了——这时该做的是删掉那层,而不是继续加。这就是驾驭工程里"加"与"删"的平衡。
Agent 核心循环:它如何一直跑到给出答案
理解了分工,我们看最内层的控制流程——Agent Loop(智能体循环)。大多数 Agent 共享同一个极简控制流:
# 核心思想(伪代码,详见 src/loop.py)
while stop_reason == "tool_use":
response = model(messages) # 1. 调用大模型
run_tools(response) # 2. 执行模型请求的工具
messages.append(results) # 3. 结果追加回对话
# stop_reason 变为 end_turn 时,返回最终答案
流程只有四步:调用模型 → 执行它请求的工具 → 把结果加回对话 → 再次调用模型,直到模型给出最终答案(stop_reason: end_turn)。
这里有个新手容易混淆的细节:内层循环和外层循环共享同一份 messages[]。
- 🔄 内层循环:完成一个用户提问。你问"台北天气如何?要不要带伞?",模型可能先查气温、再查降雨概率、最后汇总成答案——这一个轮次里模型被调用了多次;
- 📋 外层循环:把一轮轮对话串起来。你接着问"那明天呢?",模型依然知道你问的是台北,因为所有历史都留在同一份
messages[]里。
messages[] 就是整个会话的唯一状态:工具结果和助手回复全部追加进去,下一次模型调用在这份完整状态上推理。
完整实现可以看 sections/01-agent-loop/src/loop.py 中的 run_turn()(约 15 行,附带 max_steps 防止循环失控),以及 sections/01-agent-loop/src/demo.py 里的两轮对话演示。
每一层只加一个机制:工具、权限与记忆
这个项目最聪明的教学法是:章节逐层累加,每章只往 loop 上加一个机制。你只需对比相邻两章的源码差异,就能看清那一章新增了什么。
几个关键层级的作用一览:
| 章节 | 解决的问题 | 关键机制 |
|---|---|---|
| 01 Agent loop | Agent 如何持续运转 | messages[]、循环、stop_reason |
| 02 Tool runtime | 工具如何被调用和路由 | 注册表、schema、调度分发 |
| 03 Permission & sandbox | 副作用如何被把关 | 权限模式、审批、沙箱 |
| 05 Planning & todos | 大任务如何拆解 | 计划模式、待办清单、编辑前审批 |
| 08 Context management | 长会话如何塞进上下文窗口 | 预算、压缩、摘要 |
| 09 Memory | 如何跨会话记住你 | 选择、召回、提取、固化 |
| 16 Coordination | 多个 Agent 如何协作 | 收件箱、广播、权限上浮 |
以第 2 章的工具运行时为例(sections/02-tool-runtime/):每个工具在**注册表(Registry)**中登记名称与 schema;模型点名某个工具后,**调度(dispatch)**按名字找到它并执行;并发调用还会先过一道"并发安全?"检查——读操作可以批量并行,写操作必须串行。工具名、参数、返回值全都走同一份契约,这就是"harness owns 工具,model owns 判断"的落地方式。
而第 3 章的 sections/03-permission-sandbox/ 则演示了另一面:工具执行前必须穿过权限关卡,拒绝(deny)和追问(ask)本身也会被追加进对话,模型知道"为什么没做成",从而可以自行调整策略——这正是权限属于 harness 而非模型的典型例子。
8 层架构、24 个章节:完整 Agent 学习路线图
整个项目把 harness 划分为 8 层、24 个章节,从最底层的循环到能自我运转的系统,层层叠加:
- Layer 0 基础:Harness 命题——智能性从何而来
- Layer 1 核心循环:loop、工具、权限、hooks
- Layer 2 复杂工作:规划、子 Agent、Skills、上下文管理
- Layer 3 知识与韧性:记忆、系统提示词组装、错误恢复
- Layer 4 长时运行与异步:任务系统、后台执行、调度、worktree 隔离
- Layer 5 多 Agent:协作、协议、自主性
- Layer 6 扩展与集成:MCP/插件/通道、可观测性与评估
- Layer 7 组合:循环工程、图工程——循环如何叠加成自己跑的系统
每一章都采用统一的四段式视角:解决什么问题 → 通用机制与控制流 → 不同系统怎么实现 → 什么情况下会坏掉。而且所有章节都是自包含的,代码也从第 1 章开始逐章累积演进,diff 一下相邻章节的 src/ 就能看到本章新增的唯一机制。
5 分钟跑通第一个 Agent loop:环境准备步骤
想动手验证?步骤如下:
git clone https://gitcode.com/gh_mirrors/aw/learn-agent-architecture
cd learn-agent-architecture
uv venv
uv pip install -r requirements.txt
cp .env.example .env # 然后填入你的 ANTHROPIC_API_KEY
python sections/01-agent-loop/src/test.py # 离线检查,无需 API key
uv run python sections/01-agent-loop/src/demo.py # 联网演示,需要 key
依赖锁定在 requirements.txt 中。每个可运行章节都同时提供离线测试(test.py)和联网演示(demo.py),建议的学习顺序是:先读 README.md 的章节地图 → 按顺序读各章 → 读 src/loop.py → 跑 demo.py。
结语:一次学会 harness,读懂所有 Agent
learn-agent-architecture 还横向对比了 4 个真实系统——Claude Code、Hermes Agent、mini-swe-agent 和 deepseek-harness——从"完整 harness"到"几乎没有 harness 的 150 行极简实现",展示了同一个循环在不同取舍下的面貌。💡
一句话总结这个项目教给你的东西:模型负责推理,harness 负责执行;编码工具、聊天助手和自主运行器之间的差异,本质上只是 harness 的选型差异。把这个命题吃透,你再去读任何一个 Agent 的源码,都会发现它们共享着同一套骨架。



