[翻译] Manus团队分享:Agent 上下文工程的 6 个阅历教训

译者注：

AI Agents已经 成为建立下一代智能体系的中心，而高低文办理（Context Engineering）则是 AI Agents 成败的枢纽之一。Manus 的开创人 Yichao 'Peak' Ji 正在原文中，毫无保存天分享了团队建立 Manus进程 中，颠末实践患上出的贵重经历——怎样有用截至高低文工程。

作家大白指出，高低文工程是一门尝试科学，正在理论开辟中需要颠末大批试错（他们戏称为“随机梯度降落”）去寻找部门最劣解。原文具体会商了 KV 慢存的劣化战略、行动空间的静态办理办法、文献体系动作高低文的奇妙使用、怎样使用待处事项操控模子留神力，和保存毛病疑息怎样增进智能体从失利中进修。共时，作家提醒开辟者稳重使用 Few-shot 手艺，制止果高低文的简单化招致模子表示僵化。

不管您是处置 AI Agent 产物开辟，仍是存眷 AI 前沿趋势的根究者，那篇文章皆值患上深入浏览取重复回味——它将辅佐您更快、更明了天建立起颠簸、下效且适应性强的智能代办署理体系。

---

作家：Yichao 'Peak' Ji

揭晓时间：2025/7/18

本文链交：

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

---

如下为本文翻译：

正在 Manus 名目的最初阶段，尔战尔的团队面对一个枢纽决议计划：咱们是该当使用启源根底锻炼一个端到真个 agentic 模子，仍是鉴于前沿模子的高低文进修才气建立一个 agent？

回到尔正在 NLP范围 的第一个十年，咱们不这类挑选的朴实。正在 BERT 的遥远年月（是的，已经七年了），模子必需颠末微调——并截至评介——才气迁徙到新任务。那个历程屡屡迭代凡是需要数周时间，固然其时的模子比拟来日诰日的 LLMs 要小很多。关于快速开展的使用，特别是正在产物商场匹配（PMF）以前，这类迟缓的反应轮回是致命的。那是尔上一野守业公司的一个凄惨经验，其时尔从整开端锻炼模子用于盛开疑息抽与战语义搜刮。随即呈现了 GPT-3 战 Flan-T5，尔自野的模子一晚上之间变患上相关紧急。具备挖苦表示的是，那些模子标记着高低文进修的开端——和一条崭新的前进门路。

那段去之不容易的经验让挑选变患上明了：Manus 将押注于高低文工程。那使咱们能够正在数小时内乱公布改良，而没有是数周，共时连结咱们的产物取下层模子邪接：假设模子进步是涨潮，咱们期望 Manus 成为船，而没有是牢固正在海床上的柱子。

可是，高低文工程近非简朴。那是一门尝试科学——咱们已经重修了四次代办署理框架，屡屡皆是正在发明了更佳的高低文塑制办法以后。咱们密切天称这类脚动的架构搜刮、提醒调解战经历推测历程为“随机梯度降落”（Stochastic Graduate Descent）。它没有文雅，但是有用。

那篇文章分享了咱们颠末自己的“随机梯度降落”到达的部门最劣解。假设您在建立自己的 AI 代办署理，期望那些绳尺能辅佐您更快支敛。

1/ 环绕 KV-Cache（KV 慢存）的设想

假设只可挑选一个目标，尔觉得 KV 慢存掷中率是消耗阶段 AI 代办署理中最主要的目标。它间接作用提早战本钱。要理解启事，咱们先去瞅一个典范代办署理的事情过程：

正在领受到用户输出后，代办署理颠末一系列东西挪用去完毕任务。正在屡屡迭代中，模子按照目前高低文从预约义的行动空间当选择一个行动。而后正在情况中施行该行动（比方，Manus 的假造机沙箱），以发生察看成果。行动战察看成果会被逃减到高低文中，组成下一次迭代的输出。那个轮回连续截至，曲到任务完毕。

邪如您所设想的，高低文会跟着每步增加，而输出——一般为构造化的函数挪用——则绝对较短。那使患上预添补息争码之间的比率正在代办署理中比拟谈天机械人隐患上极其不服衡。比方，正在 Manus 中，均匀输出取输出的 token 比率约为 100:1。

幸运的是，具备差异前缀的高低文能够使用 KV-cache，那年夜年夜削减了初度天生标识表记标帜时间（TTFT）战拉理本钱——不管您是使用自托管模子仍是挪用拉理 API。那里的节流可没有是小数量：以 Claude Sonnet 为例，慢存的输出标识表记标帜用度为 0.30 美圆/千标识表记标帜，而已慢存的则为 3 美圆/千标识表记标帜——出入 10 倍。

从高低文工程的角度去瞅，进步 KV-cache 掷中率涉及多少个枢纽作法：

连结提醒前缀颠簸。因为 LLMs 的自返回特征，即使是单个标识表记标帜的差别也会使该标识表记标帜及其以后的慢存生效。一个罕见毛病是正在体系提醒收尾包罗时间戳——特别是精确到秒的时间戳。固然如许可让模子报告您目前时间，但是也会年夜幅低落慢存掷中率。
使高低文仅逃减。制止改正以前的操纵或者察看。保证序列化是肯定性的。很多编程语言战库正在序列化 JSON 工具时没有包管键的挨次颠簸，那可以会悄无声气天破坏慢存。
正在需要时大白标识表记标帜慢存断面。一点儿模子供给商或者拉理框架没有撑持主动删质前缀慢存，而是需要正在高低文中脚动拔出 慢存断面。树立那些断面时，要思考慢存可以过时，最少保证断面包罗体系提醒的末端部门。

别的，假设您使用像 vLLM 如许的框架自托管模子，保证启动了前缀/提醒慢存，而且使用诸如会话 ID 之类的手艺去正在散布式事情节面之间不合天路由恳求。

2/ 屏障，而非移除

跟着您的智能体具备更多才气，其行动空间天然变患上越发庞大——简朴来讲，即是东西数目激删。近来 MCP 的流行更是推波助澜。假设您许可用户自界说东西，相信尔：总会有人将数百个奥妙东西交进您经心筹谋的行动空间。成果，模子更可以挑选毛病的行动或者走上高效的路子。简而行之，您的沉拆智能体反而变患上更愚了。

一种天然的反响是设想一个静态的行动空间——大概使用类似 RAG 的办法按需减载东西。咱们正在 Manus 中也测验考试过如许干。但是咱们的尝试表白一个大白的划定规矩：除非绝对须要，制止正在迭代过程当中静态增加或者移除东西。主要有二个启事：

正在年夜大都 LLMs 中，东西界说正在序列化后位于高低文的前部，凡是正在体系提醒以前或者以后。因而，所有变动城市使统统后绝操纵战察看的 KV 慢存生效。
当以前的操纵战察看仍然引用目前高低文中再也不界说的东西时，模子会感应猜疑。若不断行束缚解码，那凡是会招致情势背规或者假造的操纵。

为了处置那一成就，共时提拔行动挑选的结果，Manus 使用了一个高低文感知的形状机去办理东西的可用性。它没有是移除东西，而是正在解码过程当中屏障某些标识表记标帜的几率散布，以按照目前高低文避免（或者自愿）挑选一定的行动。



正在理论操纵中，年夜大都模子供给商战拉理框架皆撑持某种方法的照应预添补，那使您能够正在没有改正东西界说的情况上限造行动空间。函数挪用凡是有三种情势（咱们将以 NousResearch 的 Hermes 格局为例）：

主动 – 模子能够挑选可否挪用函数。颠末仅预挖复兴前缀去完毕：<|im_start|>assistant

必须 – 模子必需挪用一个函数，但是挑选没有受限定。颠末预添补至东西挪用标识表记标帜完毕：<|im_start|>assistant<tool_call>

指定 – 模子必需挪用一定子集合的函数。颠末预添补曲到函数称呼的收尾去完毕：<|im_start|>assistant<tool_call>{“name”: “browser_

使用那一面，咱们颠末间接屏障标识表记标帜的 logits 去限定行动挑选。比方，当用户供给新的输出时，Manus必需 立即复兴，而没有是施行某个行动。咱们借特地设想了戴有不合前缀的行动称呼——比方，统统取浏览器相干的东西皆以 browser_收尾，号令止东西则以 shell_收尾。那使咱们能够轻快天保证代办署理正在一定形状下只从某一组东西当选择，而无需使用无形态的 logits处置 器。

那些设想有帮于保证 Manus 代办署理轮回连结颠簸——即使正在模子启动架构下也是云云。

3/ 将文献体系用做高低文

现代前沿的 LLMs 现在供给 128K 令牌或者更多的高低文窗心。但是无理念天下的智能代办署理场景中，那凡是借不敷，偶然以至成为承担。有三个罕见的痛面：

察看实质可以十分宏大，特别是今世理取网页或者 PDF 等非构造化数据接互时。很简单超越高低文限定。
即使窗心手艺上撑持，模子功用正在超越某个高低文少度后常常会降落。
少输出价格昂扬，即使使用前缀慢存。您仍然需要为传输战预添补每一个令牌付费。

为了处置那个成就，很多智能系统统接纳了高低文截断或者收缩战略。但是过分保守的收缩不成制止天会招致疑息丧失。那个成就是底子性的：智能体素质上必需鉴于统统先前的形状去猜测下一步行动——而您没法可靠天猜测哪条察看疑息正在十步以后可以变患上枢纽。从逻辑角度去瞅，所有不成顺的收缩皆存留危急。

那即是为何咱们将文献体系望为 Manus 中的最终高低文：它巨细无限，具备耐久性，而且能够由代办署理自己间接操纵。模子教会按需写进战读与文献——不但将文献体系用做保存，更动作构造化的内部化影象。



咱们的收缩战略不断设想为可规复的。比方，只要保存了 URL，网页实质就能够从高低文中简略；只要沙箱中仍有文档路子，文档实质也能够简略。那使患上 Manus 能够耽误高低文少度而没有会永久丧失疑息。

正在开辟那个功用的过程当中，尔开端设想让形状空间模子（SSM）正在智能代办署理情况中有用运行需要甚么前提。取 Transformer 差别，SSM 缺少残破的留神力体制，易以处置少距离的背后依靠。但是假设它们能够把握鉴于文献的影象——将持久形状内部化，而没有是保留正在高低文中——那末它们的速率战服从可以会启开一类崭新的智能代办署理。具备代办署理才气的 SSM 大概才是真实承袭神经图灵机的下一代手艺。

4/ 颠末复述操控留神力

假设您使用过 Manus，您可以留神到一件幽默的事：正在处置庞大任务时，它偏向于创立一个 todo.md 文献，并跟着任务的平息逐步革新，勾选已经完毕的事变。

那不但仅是亲爱的举动——那是一种故意操控留神力的体制。



Manus 中的一个典范任务均匀需要约莫 50 次东西挪用。那是一个较少的轮回——因为 Manus 依靠 LLMs中止 决议计划，因而正在少高低文或者庞大任务中，简单偏偏离中心或者忘记以前的目标。

颠末不竭沉写待处事项列表，Manus 将其目标重复输出到高低文的开端。那将全部方案拉进模子的短期留神范畴，制止了“半途丧失”成就并削减了目标没有不合的情况。理论上，它使用天然语言去指导自己存眷任务目标——无需特别的架构窜改。

5/保存 毛病

智能领会出错。那没有是漏洞——那是幻想。语言模子会发生幻觉，情况会前去毛病，内部东西会呈现非常，预想没有到的边沿情况随时城市呈现。正在多步调任务中，失利没有是破例；它是轮回的一部门。

可是，一个罕见的激动是躲藏那些毛病：清理陈迹，沉试操纵，大概沉置模子形状，寄期望于奇异的“温度”参数。那瞅起去更宁静、更可控。但是那支出了价格：抹来失利便抹来了凭证。而不凭证，模子便没法适应。



按照咱们的经历，改进智能体举动的最有用办法之一瞅似十分简朴：正在高低文中保存毛病的测验考试。当模子瞅到一个失利的行动——和随之发生的察看成果或者仓库追踪时——它会隐式天革新其内部决意。那会使其先验偏偏离类似的行动，进而削减重复异常毛病的可以性。
幻想上，咱们觉得毛病规复是表示真实智能体举动的最清楚标记之一。可是，正在年夜大都教术钻研战公然基准尝试中，那一面仍然被无视，那些钻研战尝试凡是偏重于幻想前提下的任务胜利率。

6/ 别被few‑shot（少样原提醒）坑了

少样原提醒是提拔 LLM输出 结果的经常使用手艺。但是正在智能系统统中，它可以以奇妙的方法拔苗助长。

语言模子是超卓的模仿者；它们会模仿高低文中的举动情势。假设您的高低文中布满了类似的已往行动-察看对于，模子常常会依照这类情势，即使那已经再也不是最劣挑选。

正在涉及重复决议计划或者行动的任务中，那可以是危急的。比方，当使用 Manus 辅佐检查一批 20 份简用时，代办署理经常陷入一种节奏——只是因为高低文中呈现了类似的实质，便重复类似的行动。那会招致偏偏离、过分泛化，以至偶然发生幻觉。

处置办法是增加百般性。Manus 正在行动战察看中引进多量构造化的变革——差别的序列化模板、替换表示、挨次或者格局上的细微噪声。这类受控的随机性有帮于突破情势，调解模子的留神力。
换句话道，没有要让年夜唆使例把自己陷入僵局。高低文越分歧，代办署理便越懦弱。

论断

高低文工程仍然是一门新兴的科学——但是关于智能系统统来讲，它已经相当主要。模子可以变患上更强大、更快速且更便宜，但是不管多强的本初才气，皆没法替换影象、情况战反应的需要。您怎样塑制高低文，终极决定了您的智能体的举动：运行速率、规复才气和扩大范畴。

正在 Manus，咱们颠末重复沉写、走过逝世胡共和正在数百万用户中的理论尝试，教到了那些经历。咱们正在那里分享的实质并不是普适真谛——但是那些是对于咱们有用的情势。假设它们能辅佐您制止哪怕一次疾苦的重复迭代，那末那篇文章便到达了它的目标。

智能代办署理的未来，将正在一次又一次的高低文办理中被逐步拆修，请经心设想它们。