为什么光有大模型还不够?learn-agent-architecture 讲透Agent驾驭工程(Harness)的核心命题

原创2026-10-14 22:39:411,969 阅读

为什么光有大模型还不够?learn-agent-architecture 讲透Agent驾驭工程(Harness)的核心命题

"为什么大模型明明很聪明,却不能自己干活?"——这正是开源教程 learn-agent-architecture 要回答的核心问题。该项目用 24 个章节系统讲解 Agent 驾驭工程(Harness Engineering):模型只负责推理,而把推理变成受控行动的工具、状态、权限和循环,全部由模型外面那层代码——也就是 harness——来承担。🧠

为什么大模型推理 ≠ 能干活的 Agent

先记住一句话,它就是整个项目的立身之本:

模型负责推理。Harness 负责执行。

一次孤立的模型调用只能"根据输入产出一个响应"。它可以判断接下来该做什么,却做不到以下任何一件事:

  • ❌ 自己执行工具、读写文件或运行命令
  • ❌ 在多次调用之间保留工作进度(它没有持久状态)
  • ❌ 在执行有副作用的操作前进行安全检查
  • ❌ 把执行结果收回来,作为下一步推理的输入

所以,一个真正能"动手"的 AI Agent = 大模型 + 一套驾驭它的 harness。没有这层外壳,模型只能停留在聊天机器人的层次。

Agent 驾驭工程(Harness)核心机制图:模型负责判断,harness 提供知识、观察、动作与权限关卡

上图来自 sections/00-harness-thesis/ 开篇章节,展示了 harness 与模型的经典分工:

  1. 提供执行环境——工具运行时让模型"说"出来的动作能真正发生;
  2. 回传执行结果——把工具输出变成模型下一轮的"观察";
  3. 把关副作用——在权限关卡(Permissions)放行之前,任何写操作都不碰真实系统;
  4. 保存状态——让第 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)。

AI Agent 核心循环图:调用大模型、执行工具、追加结果并再次调用的完整 Agent loop

这里有个新手容易混淆的细节:内层循环和外层循环共享同一份 messages[]。

  • 🔄 内层循环:完成一个用户提问。你问"台北天气如何?要不要带伞?",模型可能先查气温、再查降雨概率、最后汇总成答案——这一个轮次里模型被调用了多次;
  • 📋 外层循环:把一轮轮对话串起来。你接着问"那明天呢?",模型依然知道你问的是台北,因为所有历史都留在同一份 messages[] 里。

messages[] 就是整个会话的唯一状态:工具结果和助手回复全部追加进去,下一次模型调用在这份完整状态上推理。

完整实现可以看 sections/01-agent-loop/src/loop.py 中的 run_turn()(约 15 行,附带 max_steps 防止循环失控),以及 sections/01-agent-loop/src/demo.py 里的两轮对话演示。

每一层只加一个机制:工具、权限与记忆

这个项目最聪明的教学法是:章节逐层累加,每章只往 loop 上加一个机制。你只需对比相邻两章的源码差异,就能看清那一章新增了什么。

Agent 工具运行时(Tool Runtime)机制图:注册表、按名调度分发与并发安全检查

几个关键层级的作用一览:

章节 解决的问题 关键机制
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 个章节,从最底层的循环到能自我运转的系统,层层叠加:

Agent 架构学习路径图:从 harness 命题到循环工程的 8 层 22 个章节完整路线图

  • 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 的源码,都会发现它们共享着同一套骨架。

登录后查看全文
learn-agent-architecture