一文讲清AI Agent上下文工程：ManusAI实战经验与最佳实践，零基础小白收藏这一篇就够了！！

ManusAI基于上下文学习能力而非从头训练构建AI Agent，通过围绕KV-Cache设计、遮蔽而非移除工具、将文件系统用作上下文、通过复述操纵注意力、保留错误信息以及避免少样本陷阱等六方面经验，解决了Agent构建中的上下文工程挑战。文章强调上下文工程是AI Agent成功的关键，塑造上下文的方式决定了Agent的行为、运行速度、恢复能力和扩展性。

小涂Ss

872人浏览 · 2025-09-15 16:09:36

小涂Ss · 2025-09-15 16:09:36 发布

前言

ManusAI 在构建其 AI Agent 的过程中，选择了基于前沿模型的上下文学习能力，而非从头训练端到端模型。这一决策使得他们能够快速迭代和部署改进，并使产品与底层模型解耦。然而，上下文工程并非易事，ManusAI 团队通过反复试验和架构探索，总结出了一系列宝贵的经验教训。

1 围绕 KV-Cache 进行设计

KV-Cache 命中率是生产阶段 AI Agent 最重要的指标，直接影响延迟和成本。在 Agent 操作中，上下文会随着每次迭代而增长，而输出通常较短，导致预填充和解码的比例高度倾斜。利用 KV-Cache 可以显著降低首次生成时间（TTFT）和推理成本。

实践要点：

保持提示前缀稳定： LLM 的自回归特性意味着即使是单个 token 的差异也会使缓存失效。避免在系统提示开头包含时间戳等动态信息。
使上下文仅追加： 避免修改先前的动作或观察结果，并确保序列化是确定性的，以防止静默地破坏缓存。
在需要时明确标记缓存断点： 对于不支持自动增量前缀缓存的模型，需要手动插入缓存断点，并确保断点包含系统提示的末尾。
启用前缀/提示缓存： 如果自托管模型，确保启用前缀/提示缓存，并使用会话 ID 在分布式工作器之间一致地路由请求。

2.遮蔽而非移除

随着 Agent 能力的增强，其动作空间会变得越来越复杂。动态添加或移除工具会带来问题，因为这会使 KV-Cache 失效，并可能导致模型混淆或幻觉。ManusAI 采用上下文感知的状态机来管理工具可用性，通过遮蔽 token logits 来限制或强制选择某些动作，而不是移除工具定义。

实践要点：

避免动态增删工具： 除非绝对必要，否则不要在迭代过程中动态添加或移除工具。
利用响应预填充： 大多数模型提供商和推理框架支持响应预填充，这允许在不修改工具定义的情况下约束动作空间。
设计一致的动作名称前缀： 例如，所有浏览器相关工具以 browser_ 开头，命令行工具以 shell_ 开头，这有助于在特定状态下轻松限制 Agent 只能选择特定组的工具。

3.将文件系统用作上下文

尽管现代 LLM 提供了巨大的上下文窗口，但在实际 Agent 场景中仍然可能不足。观察结果可能非常庞大，模型性能会下降，并且长输入成本高昂。ManusAI 将文件系统视为终极上下文，模型可以按需读写文件，将文件系统不仅用作存储，还用作结构化的外部化记忆。

实践要点：

利用文件系统进行上下文管理： 将文件系统作为无限大小、持久且可由 Agent 直接操作的上下文。
可恢复的压缩策略： 确保压缩策略是可恢复的，例如，网页内容可以从上下文中删除，只要其 URL 保持不变，并且文档内容可以省略，只要其路径在沙盒中保留。

4.通过复述操纵注意力

Agent 在处理复杂任务时，会创建 todo.md 文件并逐步更新。ManusAI 通过不断将待办事项列表重写到上下文的末尾，将全局计划推入模型的注意力范围，从而避免“中间遗失”问题并减少目标错位。

实践要点：

将目标复述到上下文末尾： 通过自然语言将任务目标和待办事项列表不断重写到上下文的末尾，以保持模型的注意力集中。

5.保留错误信息

Agent 会犯错误，隐藏这些错误会阻止模型学习和适应。ManusAI 的经验表明，将错误信息保留在上下文中是改进 Agent 行为的最有效方法之一。当模型看到失败的动作和结果观察或堆栈跟踪时，它会隐式更新其内部信念，从而减少重复相同错误的可能性。

实践要点：

保留错误信息： 不要隐藏错误，而是将其保留在上下文中，以便模型能够从失败中学习并改进。
错误恢复是 Agent 行为的关键指标： 错误恢复能力是真正 Agent 行为的最清晰指标之一。

6.避免少样本陷阱

少样本提示是一种常见的改进 LLM 输出的技术，但在 Agent 系统中可能会适得其反。语言模型是优秀的模仿者，如果上下文充满了相似的动作-观察对，模型就会倾向于遵循这种模式，即使它不再是最优的。ManusAI 通过引入少量结构化变体来增加多样性，例如不同的序列化模板、替代措辞、微小的噪声或格式化，从而打破这种模式并调整模型的注意力。

实践要点：

增加多样性： 在动作和观察中引入少量结构化变体，以避免模型陷入重复模式。
避免少样本陷阱： 不要让 Agent 陷入“少样本陷阱”，即过度模仿上下文中的模式。

结论

上下文工程对于 AI Agent 来说仍然是一个新兴但至关重要的领域。模型能力再强，也无法取代对记忆、环境和反馈的需求。

塑造上下文的方式决定了 Agent 的行为方式、运行速度、恢复能力以及扩展性。ManusAI 通过在数百万用户中进行真实世界测试，总结出了这些经验教训，希望能帮助其他构建 AI Agent 的团队更快地收敛并避免痛苦的迭代。

最后

为什么要学AI大模型

当下，⼈⼯智能市场迎来了爆发期，并逐渐进⼊以⼈⼯通⽤智能（AGI）为主导的新时代。企业纷纷官宣“ AI+ ”战略，为新兴技术⼈才创造丰富的就业机会，⼈才缺⼝将达 400 万！

DeepSeek问世以来，生成式AI和大模型技术爆发式增长，让很多岗位重新成了炙手可热的新星，岗位薪资远超很多后端岗位，在程序员中稳居前列。

在这里插入图片描述

与此同时AI与各行各业深度融合，飞速发展，成为炙手可热的新风口，企业非常需要了解AI、懂AI、会用AI的员工，纷纷开出高薪招聘AI大模型相关岗位。
在这里插入图片描述
最近很多程序员朋友都已经学习或者准备学习 AI 大模型，后台也经常会有小伙伴咨询学习路线和学习资料，我特别拜托北京清华大学学士和美国加州理工学院博士学位的鲁为民老师给大家这里给大家准备了一份涵盖了AI大模型入门学习思维导图、精品AI大模型学习书籍手册、视频教程、实战学习等录播视频 全系列的学习资料，这些学习资料不仅深入浅出，而且非常实用，让大家系统而高效地掌握AI大模型的各个知识点。