AI Agent 入门不要再乱刷资料了|第 4 期:真正的 Agent 工程,不只是调用一次大模型

前两期，我们已经跑通了两类 Agent：

Calculator Agent：模型主动调用计算器工具

Web Research Agent：模型搜索、阅读、筛选资料，再输出带引用报告

到这里，一个最小 Agent 已经能完成基本闭环：

观察任务 → 判断下一步 → 调用工具 → 读取结果 → 继续执行

但如果你真的想把 Agent 做成一个能长期使用的产品，仅靠这个 Loop 还远远不够。

因为：

1.真实任务不会永远顺利。

2.工具可能报错。

3.网页可能打不开。

4.上下文可能越来越长。

5.模型可能重复执行同一个动作。

6.用户可能不允许 Agent 直接删除文件或发送邮件。

7.任务跑到一半中断后，还可能需要继续恢复。

所以这一期，我们要理解一个更重要的概念：

Agent Harness

Agent Loop 和 Agent Harness 有什么区别？

可以先用一个简单比喻理解。

Agent Loop 像发动机。

它负责让 Agent 动起来。

Agent Harness 像整辆车。

除了发动机，还要有方向盘、刹车、仪表盘、安全带、导航系统和维修记录。

一个最小 Agent Loop 通常只关心：

1.模型下一步想做什么

2.要调用哪个工具

3.工具返回了什么

4.是否输出最终答案

但一个真正可用的 Agent Harness，还要关心：

1.工具有没有权限

2.任务执行到哪一步

3.上下文是否过长

4.工具失败后是否重试

5.哪一步出了问题

6.是否需要人工确认

7.中断后能不能继续执行

8.每次调用花了多少成本

所以，Harness 解决的不是“Agent 能不能跑”。

而是：

Agent 能不能稳定、可控、可追踪地跑。

一个 Agent Harness 至少需要哪些模块？

一个基础 Harness，可以拆成 6 个模块。

1. Agent Loop

这是最核心的循环。

模型不断判断：

继续调用工具
读取工具结果
请求更多信息
输出最终答案

没有 Loop，Agent 就只是一次普通模型调用。

2. Tool Registry

Agent 需要知道自己有哪些工具。

例如：

search_webread_pageread_filewrite_filerun_codesend_email

Tool Registry 就像一张工具清单。

它不仅要告诉模型“有哪些工具”，还要规定：

每个工具能做什么
输入格式是什么
输出格式是什么
是否属于高风险操作

3. Permission Gate

这是权限控制。

比如：

读取文件，可以自动执行。

修改文件，需要记录日志。

删除文件、发邮件、付款，必须人工确认。

如果没有 Permission Gate，Agent 能力越强，风险反而越大。

4. Session Store

Agent 执行任务时，需要保存状态。

比如：

用户目标是什么
已经调用过哪些工具
哪些网页已经读过
哪一步失败了
当前任务是否完成

有了 Session Store，任务中断后才能继续恢复，而不是每次都从头开始。

5. Trace Log

Agent 每一步都应该留下记录。

记录包括：

模型决策
工具调用
工具输入
工具结果
错误信息
执行耗时
Token 成本

这样 Agent 答错时，你才能知道问题出在哪。

6. Context Manager

任务越复杂，上下文越长。

如果把所有历史信息都塞给模型，成本会越来越高，效果也会越来越差。

所以需要做：

历史压缩
重点摘要
只保留必要上下文
区分短期状态和长期记忆

用一个实际例子理解 Harness

假设我们做一个 Coding Agent。

用户输入：

帮我修复登录页面的报错，并补一个测试用例。

如果只有一个最小 Loop，Agent 可能会：

读取代码
修改文件
运行测试
输出结果

但真实情况往往更复杂。

比如：

测试失败了怎么办？
修改了哪些文件？
是否允许 Agent 执行 shell 命令？
如果它想删除文件怎么办？
任务中断后能不能恢复？
它为什么决定改这个函数？
运行一次任务花了多少 Token？

这时候，Harness 就开始发挥作用。

一个更合理的执行流程应该是：

读取代码库，建立任务 Session
调用 read_file，记录读取内容
模型生成修改计划
Permission Gate 判断：修改文件允许执行
调用 write_file，记录 Diff
调用 run_test，保存测试结果
如果失败，Agent 根据报错继续修复
如果涉及删除文件，弹出人工确认
完成后输出修改摘要、测试结果和 Trace
这才是一个真正可用的 Coding Agent。

Harness 最容易忽略的 4 个问题

问题 1：只关心“能跑”，不关心“能不能复现”

Demo 成功一次，不代表产品可用。

真正上线后，你必须知道：

为什么成功
为什么失败
哪一步出了问题
改完 Prompt 后能力有没有退化

所以 Trace 不是锦上添花，而是基础能力。

问题 2：工具权限设计太粗

不是所有工具都应该同样处理。

可以把工具分成三类：

低风险：读取网页、搜索资料
中风险：修改文件、执行代码
高风险：删除数据、发送邮件、付款

风险越高，人工确认越重要。

问题 3：上下文越积越多

很多 Agent 跑几轮后就开始变慢、变贵、变笨。

原因通常不是模型不够强，而是上下文管理太差。

真正的 Harness 必须会压缩历史，只保留与当前任务有关的信息。

问题 4：没有恢复机制

真实任务一定会中断。

网络失败、工具报错、页面变化、用户暂停，都会发生。

好的 Harness 要能记录当前状态，并从失败位置继续执行。

这一期你要交付什么？

这一期不要求你做完整 Harness。

只需要把上一期的 Web Research Agent 升级一下，增加 4 个能力：

记录每一次工具调用
保存搜索过的链接，避免重复读取
设置最大执行步数
工具失败时，记录错误并允许重试
可以先用一个简单列表保存 Trace：

trace = []trace.append({    "tool": "search_web",    "input": query,    "result": search_results,    "status": "success"})再加一个 Session：session = {    "topic": topic,    "visited_urls": [],    "step": 0,    "status": "running"}

这两个小改动，会让你的 Agent 从“能跑 Demo”，开始走向“可以调试”。

本期总结

这一期你只需要记住 4 句话：

Agent Loop 像发动机，Agent Harness 像整辆车

Harness 负责工具、权限、状态、日志和上下文

真正可用的 Agent，必须能控、能查、能恢复

Demo 跑通只是开始，工程化才决定它能不能上线

下一期，我们继续往前走：

多 Agent 不是几个 AI 聊天，而是任务协作系统

也就是开始理解：

Multi-Agent。