Agent Engineering 是怎么工作的？我用一条真实链路把它讲清楚

这条链路从 Notion 需求开始

真实场景是这样的：你正在开发一个微服务，需要在已有代码库中新增一个告警模块。任务写在 Notion 上，你需要 Agent 帮你完成从需求解析到代码提交的全流程。

第一步不是写代码，而是定义工具。你需要告诉 Agent：Notion 文档的获取方式、代码库的搜索工具、终端命令的执行权限、Git 操作的接口。每一个工具都是一个 API 调用声明——包括参数、返回值和失败处理。这就是 Agent Engineering 中最基础也最容易被忽略的环节：工具定义。

如果工具定义不完整，Agent 会在第一关卡住。例如只给了 Notion API 却没给身份验证令牌，Agent 会尝试三次然后报错退出——很多团队把这种失败归结为“AI 能力不够”，其实是工具层没做扎实。

核心循环：规划、调用、观察、调整

工具就绪后，Agent 开始它的核心循环。拿刚才的告警模块任务为例：

1. 规划：Agent 阅读 Notion 需求，调用代码搜索工具找到当前项目结构，然后生成执行计划——新建文件、修改配置文件、添加依赖。
2. 调用工具：它先执行 git pull 获取最新代码，然后创建新文件。这里的关键是 Agent 会生成具体命令，系统将其转发到终端执行。
3. 观察结果：如果文件创建成功，终端返回路径和权限信息；如果失败（比如目录不存在），返回错误码。Agent 需要根据观察调整下一步。
4. 调整：失败时 Agent 会重新规划，比如先创建目录再创建文件。这个过程可能迭代数次。

这个循环看似简单，但失败点藏在细节里。最典型的错误是：Agent 在第一次工具调用成功后过度自信，跳过验证直接执行下一步。比如创建完文件后没有检查内容是否正确，直接执行了代码格式化，结果格式化了空文件。

上下文与 MCP：不要让 Agent 迷失

有了循环，Agent 还需要记住它在做什么。这就是 上下文管理。

每个工具调用的输入和输出都会写入上下文窗口。问题是，上下文窗口有上限——GPT-4 是 128K token，Claude 是 200K。当循环执行 10 次以上，上下文可能被历史日志填满。这时 Agent 开始“遗忘”：它可能忘记最初的需求，或者重复执行已经完成的操作。

解决方案是 MCP（Model Context Protocol）。这本质上是一种上下文裁剪策略：只保留当前步骤相关的系统提示、工具结果和摘要，丢弃无关细节。实现时可以通过滑动窗口、重要性打分等方式控制上下文质量。

例如我的实践中，每轮循环只保留最近 5 次工具调用的结果，超过的就压缩成一句话摘要。这使 Agent 在超过 30 步的复杂任务中仍能保持 90% 以上的准确率。

权限模型：最容易被忽略的坑

Agent Engineering 和普通编程的最大区别在于：你授予 Agent 的是操作权限，不是代码逻辑。

你需要回答三个问题：

• Agent 能访问哪些文件系统路径？
• Agent 能执行哪些终端命令（如 rm -rf 要禁止）？
• Agent 能调用哪些外部 API（如生产环境数据库要只读）？

失败场景很具体：有个团队允许 Agent 直接执行 npm publish，结果它在调试过程中把未完成的包发布到了 npm 官方仓库。这类问题无法通过提示工程解决，必须从工具权限层管控。

我的做法是：在工具定义中为每个命令绑定安全 ID，终端执行前校验权限。例如文件写入只允许在 /src 和 /tests 目录下，命令黑名单包含 rm -rf、sudo、publish 等。

失败恢复：不打断工作流

即使有工具定义、循环、上下文和权限，Agent 仍然会失败。问题在于：失败后怎么办？

大多数实现是抛出异常然后停止。但真实开发场景需要更多：可能是手动介入修正，然后让 Agent 从断点继续。

一种可行的设计是“检查点模式”：每完成一个子任务（如文件创建、测试通过），就把当前状态保存到磁盘。当 Agent 在后续步骤失败时，你可以手动恢复到这个检查点，修正问题后重新开始后续流程。

另一种是“显式授权模式”：当 Agent 遇到无法自动解决的错误（如 API 认证过期），它应该暂停并请求人工输入，而不是盲目重试。

例如，我的工作流中有一个“人工介入门”：如果 Agent 连续两次执行同一个操作失败，系统会弹出一个终端提示，要求开发者输入新的凭据或修改路径。开发者在终端输入后，Agent 继续执行。

什么时候该放弃 Agent？

Agent Engineering 的适用边界并非无限。以下几种情况下，手工编码或传统自动化更合适：

• 高度安全敏感的操作：比如修改生产环境配置、操作金融数据真实订单。
• 需要人类判断的决策：比如接口设计、命名冲突解决。
• 非确定性任务：Agent 不适合包含随机性（如自动生成密码）或需要多轮人工审批的工作流。
• 超长周期任务：单个任务超过 1 小时或 200 步，当前上下文管理技术很难保持一致性。

在这些边界外，Agent Engineering 的效果会明显下降。比如在做代码重构时，Agent 可能因为无法理解整个项目的隐式依赖关系而引入 bug。此时，你应该退回到传统方式：手动重构 + 单元测试。

一条可执行的检查清单

如果你准备在真实项目中使用 Agent Engineering，以下是我实践后提炼的清单：

1. 工具定义完整性检查：每个工具的输入/输出/错误码是否都声明了？
2. 权限最小化：Agent 只能访问它真正需要的文件和命令。
3. 上下文裁剪策略：设置最大保留轮次（建议 5-10 轮），超过后压缩。
4. 失败恢复机制：检查点 + 人工介入接口。
5. 监控日志：记录每一次工具调用和决策，方便回溯。
6. 测试沙箱：先在隔离环境运行，确认无误再放开权限。

这条清单不是一次性配置就完事，而是每次任务前都要过一遍。我见过太多因为“上周没事”就跳过权限检查，结果这周 Agent 删了数据库的案例。

下一步：成为 Agent 工程师

如果你想从普通开发者转型成为 Agent 工程师，这篇内容的下一步应该进入更系统的原创付费文章或课程。在课程中你会学到如何设计工具调用协议、如何调试 Agent 的上下文窗口、以及如何构建生产级的失败恢复系统。