Manus：构建AI Agent上下文工程的实践经验

该文分享了Manus团队在构建智能体过程中，搭建合适的上下文工程的经验教训，读完获益匪浅。

当然，你也可以将其看作Manus团队所总结的构建AI Agent所需遵循的原则，下文为本篇文章核心内容总结。原文地址如下：
https://manus.im/zh-cn/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus

首先，在构建一个AI Agent之前，面临的第一个抉择就是技术路线问题。

目前最常见的路线有两种：1-基于开源基础模型训练端到端的智能体；2-依托前沿上下文学习能力，在其之上构建智能体。Manus选择了第二种技术路线，依托于大模型的上下文学习能力进行任务构建和执行。

做一个很形象的比喻：如果模型能力的快速进步是不断上涨的潮水，那Manus则是潮水之上的船。

当然，Manus的构建过程并非一帆风顺，它也经历了多次框架重构。重构的原因，则是大模型的上下文构建能力在不断进化。

构建Manus的过程，大致要经过手动架构搜索、提示词微调，以及依据经验进行探索三个步骤。Manus团队将这个过程称之为SGD——随机梯度下降(Stochastic Graduate Descent)。

而本文的内容，则是Manus团队通过自身的SGD，抵达局部最优解的过程的实践经验总结。

一、KV‑Cache：构建 Agent 的核心指标

在智能体的循环执行中，每一步都会把“动作+观察”追加到上下文，导致输入 token 持续增长，而输出（函数调用）相对短小。

以 Manus 为例，输入/输出 token 比约为 100:1。KV‑Cache（键值缓存）能够在后续推理中复用已有的 KV 对，显著降低首 token 延迟（TTFT）和计算成本。因此，提高 KV‑Cache 命中率是提升 Agent 效率的首要手段。关键实践包括：

1、保持提示前缀稳定：LLM 的自回归特性使得哪怕一个 token 的差异也会导致缓存失效。

2、采用追加式上下文：避免修改已生成的动作或观察，确保序列化过程确定性。
3、显式标记缓存断点：部分模型或推理框架不支持自动增量前缀缓存，需要手动在上下文中插入断点（通常放在系统提示结尾），以防缓存过期。

二、通过掩码约束工具选择，避免动态增删

智能体功能越多，工具集合越大，若在任务迭代中随意增删工具，会导致 KV‑Cache 大面积失效，甚至出现模型选错工具、行为违规的情况。Manus 的做法是：

1、尽量不在迭代过程中增减工具：因为工具定义通常位于上下文前部，任何变动都会破坏后续 KV‑Cache。
2、使用上下文感知的状态机在解码阶段屏蔽不应出现的工具 token：而不是物理删除工具。这样可以在保持工具定义不变的前提下，限制模型的动作空间。
3、函数调用的三种模式（以 NousResearch 的 Hermes 为例）：
Auto：模型自行决定是否调用函数（仅预填充回复前缀）。
Required：模型必须调用函数，但具体是哪一个不受限制（预填充到函数调用标记）。
Specified：模型必须从指定子集调用函数（预填充到函数名开头）。
这些机制帮助循环保持稳定，防止因工具变动导致的缓存失效和幻觉行为。

三、将文件系统作为无限上下文

即便大模型已支持 128k 甚至更大的窗口，实际任务中仍会遇到观测数据庞大、模型性能随上下文长度下降、长输入成本高等痛点。Manus 将文件系统视为终极上下文，实现方式如下：

1、外部持久存储：文件系统容量无限、天然持久，Agent 可直接读写。
2、按需加载：只保留必要的引用（如 URL、文件路径），实际内容可在需要时重新读取，避免一次性塞满上下文。
3、可还原的压缩：例如保留网页 URL 而删除全文，或保留文件路径而省略文档内容，只要路径仍在沙盒即可随时恢复。
这种设计让 Agent 在长链任务中仍能保持高效推理，同时避免信息不可逆的压缩导致关键细节丢失。

四、通过复述操作引导注意力

Manus 在复杂任务中会创建 todo.md 待办清单，并在每次迭代后更新、勾选已完成项。此举相当于把全局目标“背诵”到上下文末尾，实现方式如下：

1、将目标推入近期注意力范围：防止在冗长上下文中遗忘早期目标。
2、降低目标错位风险：因为模型每一步都能看到最新的、已完成的任务列表。
这种纯语言层面的注意力操控无需额外架构改动，却能显著提升任务的聚焦度和执行效率。

五、保留错误内容以实现自我纠错

多步骤任务中错误是常态：LLM 幻觉、工具故障、边缘情况等都会导致失败。常见的错误处理方式是 清理错误记录或重置模型状态，但这会抹去宝贵的错误证据，使模型失去学习机会。Manus 的实践经验有如下几条：

1、将错误及其观察保留在上下文：让模型看到一次失败的完整过程（包括堆栈信息、错误提示）。

2、模型据此更新内部信息：在后续类似情境中倾向于规避相同错误，从而提升整体鲁棒性。
错误恢复的能力是衡量智能体真正智能的关键指标。

六、避免 Few‑Shot 的反噬影响

Few‑Shot Prompting能提升 LLM 输出质量，但在 Agent 场景中会产生副作用：

1、上下文中大量相似动作会让模型模仿固定模式：即使该模式已不再最优，导致结果漂移或幻觉。
2、在批量处理时，模型可能因上下文示例的重复而形成“惯性”，忽略个体差异。
解决方案是引入适度多样性：使用不同的序列化模板、替代表述、顺序或格式上的轻微扰动，使上下文保持一定的随机性，打破单一模式的束缚。

Manus团队的最终建议：

1、构建稳定的提示前缀保持上下文追加式，必要时插入缓存断点。
2、设计工具集时采用掩码约束，避免迭代中增删工具；利用 Auto/Required/Specified 三种调用模式控制动作空间。
3、将文件系统作为外部记忆，只在上下文中保留引用，按需读取，确保信息可还原。
4、使用待办清单等复述手段，把全局目标持续推入近期注意力。
5、保留错误记录，让模型在上下文中学习纠错，提高自适应能力。
6、在 Few‑Shot 示例中加入结构化多样性：防止模型固化不佳的行为模式。
通过上述六大实践，能够显著提升 AI Agent 的推理速度、恢复能力以及在复杂任务中的可扩展性。上下文工程虽不是模型的原生能力，却是决定智能体实际表现的关键因素。合理塑造上下文，即是塑造智能体行为的根本。