Manus 联创亲述 Agent“成功学”：如果模型进步是潮水上涨，我们希望是船

作者 | Manus 联合创始人季逸超 (Yichao 'Peak' Ji)

译者 | 平川

策划 | 华卫

Manus项目伊始，我和我的团队就面临一个关键决策：我们是应该以开源为基础训练一个端到端的代理模型（agentic model），还是应该基于前沿模型的上下文学习能力构建一个代理？

在我从事自然语言处理（NLP）的第一个十年里，我们没有这样奢侈的选择。在遥远的BERT（是的，已经过去七年了）时代，在将模型应用到新任务之前必须进行微调和评估。这个过程通常每次都需要迭代几周的时间，尽管与今天的大型语言模型（LLM）相比，当时的模型很小。对于快速变化的应用程序，如此慢的反馈循环是不可接受的。这是我从上一次创业经历中总结出的苦涩教训，当时我从头开始训练模型进行开放信息提取和语义搜索。然后GPT-3和Flan-T5出现了，一夜之间，我的内部模型变得无关紧要。具有讽刺意味的是，这些相同的模型标志着上下文学习的开始以及一条全新的前进道路。

那个来之不易的教训让我们的选择思路变得清晰：Manus 将押注于上下文工程。这使我们能够在几小时而不是几周内发布改进，并且使我们的产品与底层模型保持正交：如果模型进步是潮水上涨，我们希望 Manus 是船，而不是固定在海底的柱子。

尽管如此，事实证明，上下文工程并非易事。这是一门实验科学——我们的代理框架已经重建了四次，每次都是在发现了更好的塑造上下文的方法后。我们将这种手动的架构搜索、提示调整和经验猜测过程亲切地称为“随机梯度下降”（SGD）。它并不优雅，但有效。

这篇文章分享了我们如何通过自己的“SGD”达到局部最优解。如果你正在构建自己的 AI 代理，希望这些原则能帮助你更快地收敛。

围绕 KV 缓存进行设计

如果只能选择一个指标，那么我要说，KV 缓存命中率是生产阶段 AI 代理最重要的一个指标。它直接影响延迟和成本。为了理解原因，让我们看看一个典型的代理是如何工作的。

在接收到用户输入后，代理使用一系列工具来完成任务。在每次迭代中，模型根据当前上下文从预定义的动作空间中选择一个动作，然后在环境中（如 Manus 的虚拟机沙箱）执行它并生成一个观察结果。最后，将动作和观察结果追加到上下文中，形成下一次迭代的输入。这个循环会一直持续到任务完成。

你可能已经想到，上下文会随着每一次迭代的进行而增长，而输出——通常是结构化的函数调用——则保持相对简短。因此，与聊天机器人相比，代理的预填充和解码之间的比例非常不均衡。例如，在 Manus 中，平均输入输出令牌比大约是 100:1。

幸运的是，前缀相同的上下文可以利用KV缓存，这大大减少了首次生成答案的时间（TTFT）和推理成本——无论你是使用自托管模型还是调用推理 API。我们所说的节省可不是小数目：以 Claude Sonnet 为例，缓存输入令牌的成本是 0.30 美元/MTok，而未缓存的输入令牌成本是 3 美元/MTok——相差 10 倍。

从上下文工程的角度来看，提高 KV 缓存命中率涉及一些关键实践：

1.保持提示前缀不变。由于 LLM 的自回归特性，即使是单个令牌存在差异也可以使该令牌之后的缓存失效。一个常见的错误是在系统提示的开头包含一个时间戳——特别是精确到秒的时间戳。当然，它可以让模型告诉你当前时间，但同时也会降低你的缓存命中率。

2.使用仅限追加上下文。避免修改之前的动作或观察结果。确保你的序列化过程是确定性的。许多编程语言和库在序列化 JSON 对象时不能保证稳定的键排序，这可能会悄无声息地破坏缓存。

3.在需要时明确标记缓存断点。一些模型提供商或推理框架不支持增量前缀自动缓存，而是需要在上下文中手动插入缓存断点。在指定这些断点时，要考虑到潜在的缓存过期，至少要确保断点包括系统提示的结尾。

此外，如果你使用vLLM这样的框架自托管模型，请确保启用了前缀/提示缓存，并使用会话 ID 等技术在分布式工作进程之间一致地路由请求。

屏蔽，但不要移除

随着你的代理能力越来越强，其动作空间自然会变得更加复杂——换句话说，工具的数量激增。最近MCP的流行只是火上浇油。如果你允许用户配置工具，那么请相信：不可避免地，有人会将数百个神秘的工具插入到你精心策划的动作空间中。这样做的结果是，模型更有可能采取错误的行动或选择低效的路径。简而言之，你全副武装的代理变得更笨了。

对此，自然的反应是设计一个动态的动作空间——可能是使用类似RAG这样的工具按需加载工具。我们在 Manus 中也尝试过这种方法。但我们的实验表明：除非绝对必要，否则要避免在迭代过程中动态添加或移除工具，原因主要有两个：

1. 在大多数大型语言模型（LLM）中，在序列化之后，工具定义通常位于上下文的前端，在系统提示之前或之后。因此，任何更改都会使所有后续动作和观察结果的 KV 缓存失效。

2. 当之前的动作和观察结果仍然引用当前上下文中不再定义的工具时，模型会感到困惑。如果没有受限解码，这通常会导致模式违规或产生幻觉动作。

为了解决这个问题，同时仍然改进动作选择，Manus 使用一个上下文感知状态机来管理工具可用性。它不是移除工具，而是在解码过程中屏蔽令牌的 logit，以防止（或强制）根据当前上下文选择某些动作。

在实践中，大多数模型提供商和推理框架都支持某种形式的响应预填充，就是允许你在不修改工具定义的情况下限制动作空间。通常有三种函数调用模式（我们将以 NousResearch 的Hermes格式为例）：

• 自动：模型可以选择调用或不调用函数。通过仅预填充回复前缀来实现： <|im_start|>assistant

• 必需：模型必须调用函数，但选择不受限制。通过预填充到工具调用令牌来实现： <|im_start|>assistant<tool_call>

• 指定：模型必须从特定子集中调用函数。通过预填充到函数名的开头来实现： <|im_start|>assistant<tool_call>{"name": “browser_

使用这种方法，我们通过直接屏蔽 token logit 来限制动作选择。例如，当用户提供新的输入时，Manus 必须立即回复而不是采取行动。我们还故意将动作名称的前缀设计成了一致的——例如，所有与浏览器相关的工具都以 browser_开头，命令行工具以 shell_开头。这样，我们就能够轻松地强制代理在给定状态下仅从特定组工具中做出选择，而不需要使用有状态的 logit 处理器。

这些设计有助于确保 Manus 代理循环保持稳定——即使在模型驱动的架构下也是如此。

将文件系统作为上下文

现在，现代前沿大型语言模型可以提供 128K 或更多令牌的上下文窗口。但在现实世界的代理场景中，这通常不够，有时甚至还是一种负担。常见的痛点有三个：

1. 观察结果可能非常大，特别是当代理与像网页或 PDF 这样的非结构化数据交互时，很容易超过上下文限制。

2. 模型性能往往会在超出某个上下文长度之后下降，即使窗口从技术上讲支持。

3. 长输入很昂贵，即使有前缀缓存。你仍然需要支付传输和预填充每个令牌的费用。

为了解决这个问题，许多代理系统实现了上下文截断或压缩策略。但过于激进的压缩不可避免地会导致信息丢失。问题的根本在于：本质上，代理必须根据所有先前的状态预测下一个动作——你无法可靠地预测哪个观察结果可能在十步之后变得关键。从逻辑上讲，任何不可逆的压缩都带有风险。

这就是为什么我们在 Manus 中将文件系统视为终极上下文：大小无限，天生具有持久性，并且可以由代理本身直接操作。模型学会按需写入和读取文件——不仅将文件系统用作存储，而且作为结构化的外部记忆。

我们的压缩策略总是设计成可恢复的。例如，只要保留 URL，就可以从上下文中删除网页的内容；如果文档的路径在沙箱中仍然可用，就可以省略文档的内容。这样，Manus 就可以在不永久丢失信息的情况下缩短上下文长度。

在开发这个功能时，我一直在思考，在代理环境中，要让状态空间模型（SSM）有效工作需要什么。与 Transformer 不同，SSM 缺乏完整的注意力，并且难以处理长距离的后向依赖。但如果它们能够掌握基于文件的记忆——将长期状态外部化而不是保持在上下文中——那么它们的速度和效率可能会解锁一类新的代理。代理 SSM 可能是神经图灵机的真正继承者。

通过复述操纵注意力

如果你使用过 Manus，你可能已经注意到了一些奇怪的事情：在处理复杂任务时，它往往会创建一个 todo.md 文件，并随着任务进展逐步更新它，取消勾选已完成的项目。

这不仅仅是一种可爱的行为，而且是一种有意设计的注意力操纵机制。

在 Manus 中，一个典型的任务平均需要大约 50 次工具调用。这是一个漫长的循环——由于 Manus 依赖于大型语言模型（LLM）进行决策，容易偏离主题或忘记早期目标，特别是在长篇上下文或复杂的任务中。

通过不断地重写待办事项列表，Manus 将其目标复述到上下文的末尾，将全局计划推入模型的近期注意力范围，避免了“中间迷失”的问题，并减少了目标错位。实际上，它正在使用自然语言来引导自己的焦点朝向任务目标，而无需特殊的架构变化。

保留错误的东西

代理会犯错。这不是 Bug，而是现实。语言模型会产生幻觉，环境会返回错误，外部工具会行为失常，意料之外的边缘情况随时都会出现。在多步骤任务中，失败不是例外，而是循环的一部分。

然而，一个常见的冲动是隐藏这些错误：清理痕迹，重试动作，或重置模型的状态并将其留给神奇的“Temperature”。这样感觉更安全，更有控制感，但也有代价：擦除失败信息会移除证据，没有证据，模型就无法适应。

根据我们的经验，改进代理行为最有效的方法之一是：保留上下文中的错误。当模型看到一个失败的动作——以及由此产生的观察结果或堆栈跟踪——它就会暗中更新其内部信念。这样，它就能摆脱类似的动作，减少重复相同错误的机会。

事实上，我们认为，错误恢复是真正的代理行为最清晰的指标之一。不过，在大多数学术工作和公共基准中，它仍然被低估，因为这些工作通常关注理想条件下的任务成功。

不要陷入少样本困境

少样本提示是提高 LLM 输出的常用技术。但在代理系统中，它可能会以微妙的方式起到反作用。

语言模型是出色的模仿者；它们模仿上下文中的行为模式。如果你的上下文中有许多以前的类似的动作-观察对，那么模型将倾向于遵循这种模式，即使它不再是最优的。

在涉及重复决策或动作的任务中，这可能会带来危险。例如，当使用 Manus 帮助审查一批 20 份简历时，代理经常会陷入这样一种节奏——仅仅因为在上下文中看到了类似的动作而重复类似的动作。这会导致漂移、过度泛化，有时甚至是幻觉。

解决方案是增加多样性。Manus 在动作和观察结果中引入了少量的结构变化——不同的序列化模板、措辞交替、顺序或格式中的小噪声。这种受控的随机性有助于打破模式并调整模型的注意力。

换句话说，不要让自己陷入少样本的困境。你的上下文越统一，你的代理就越脆弱。

小结

上下文工程仍然是一个新兴的科学，但对于代理系统来说，它已经变得至关重要。模型可能变得更强、更快、更便宜，但任何原始能力都无法取代对记忆、环境和反馈的需求。你塑造上下文的方式最终定义了代理的行为：运行速度、恢复能力以及扩展能力。

在 Manus，我们通过反复重写、dead end 以及对数百万用户的实际测试总结出了这些经验教训。我们在这里分享的并不是普遍真理，但都是我们已经取得成功的模式。如果它们能帮助你避免哪怕是一次痛苦的迭代，那么这篇文章就已经完成了它的任务。

声明：本文为 InfoQ 翻译，未经许可禁止转载。

原文链接：

https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus