AI Agent（人工智能代理）的概念火爆，但将 Agent 投入生产环境并确保其稳定、高效、低成本运行，是无数团队面临的挑战。

本文将带来一份来自 Manus 团队的实战宝典，总结了他们在构建生产级 AI Agent 过程中踩过的无数坑，提炼出 7 条关于 **上下文工程（Context Engineering）**的宝贵经验。这些是真金白银、无数次迭代换来的实践智慧，希望能帮助你避免痛苦的迭代！

对于多步、工具调用密集的 Agent 流程来说，KV-Cache（键值缓存）的命中率几乎是最重要的指标，它直接影响着 Agent 的延迟和成本。

Agent 的工作流程是“上下文长，输出短”（长预填充/短解码），每一次动作和观察都会被添加到上下文。一旦缓存失效，模型需要重新计算整个长上下文，导致成本爆炸。

• Prompt 前缀稳定： 绝不要在系统 Prompt 开头添加精确到秒的时间戳或任何动态变量，哪怕只改动一个 Token，都会使缓存失效。
• 上下文只增不减： 避免修改之前的动作或观察。确保你的序列化（如 JSON 对象的键值顺序）是确定性的，否则缓存会“悄悄”失效。
• 明确标记缓存断点： 如果模型提供商不支持自动增量前缀缓存，你需要手动设置断点来管理缓存。

随着 Agent 能力增强，它能调用的工具会爆炸式增长。

动态添加或移除工具会带来巨大的成本和稳定性问题：

• KV-Cache 失效： 工具定义通常在上下文开头，任何改动都会使后续所有动作和观察的 KV-Cache 失效。
• 模型“懵圈”： 如果之前的动作引用了现在不存在的工具，模型会陷入混乱。

Manus 团队不是移除工具，而是在解码时通过**“遮蔽”Token Logit来限制（或强制）选择特定的动作。这叫上下文感知的 Logit Masking**，它在不改变上下文的情况下，动态调整 Agent 的动作空间。

即使现代 LLM 的上下文窗口达到 128K，对于真实世界的 Agent 场景来说往往仍不够，且长输入非常昂贵，模型性能也可能下降。

将文件系统视为终极上下文！它大小无限、天生持久化，并且可以直接由 Agent 操作。

• 作用： 模型学会了按需读写文件，将文件系统不仅用作存储，还作为结构化、外部化的内存。
• 压缩策略： 总是可恢复的。例如，网页内容可以从上下文移除，只要 URL 还在，Agent 就能随时“回忆”起来。

在多步复杂任务中，Agent 很容易在长上下文或工具调用循环中**“跑偏”或忘记早期目标**（即“迷失在中间”问题）。

Manus 团队刻意设计了一个机制：Agent 在处理复杂任务时，会创建一个 todo.md 文件，并随着任务的进展一步步更新，完成一项就勾掉一项。

目的： 通过不断重写待办事项列表，将**“全球计划”不断推入模型的最新注意力范围**，有效避免目标错位和“迷失在中间”的问题。

失败不是例外，而是多步任务循环的一部分。 隐藏错误（清理轨迹、重试动作）的代价是：抹去证据，模型无法适应。

当模型看到一个失败的动作，以及相应的观察或堆栈跟踪时，它会隐式地更新其内部信念。 这会使其在未来减少类似动作的尝试，从而降低重复相同错误的可能性。

Few-shot（少量样本学习）是提高 LLM 输出的常用技术，但在 Agent 系统中，它可能会以微妙的方式适得其反。

语言模型是非常优秀的模仿者。如果上下文充满了类似的过去动作-观察对，模型就会倾向于遵循这种模式，即使它不再是最优的，导致漂移、过度泛化或幻觉。

Manus 在动作和观察中引入少量结构化变体——不同的序列化模板、不同的措辞、顺序或格式上的微小噪音。 这种受控的随机性有助于打破模式，调整模型的注意力。

核心思想： 不要让 Few-shot 把自己“困死”。你的上下文越统一，你的 Agent 就越脆弱。

上下文工程仍然是一门新兴的科学，但对于 Agent 系统来说，它已经至关重要。

再多的原始能力也无法取代对内存、环境和反馈的需求。你如何塑造上下文，最终决定了你的 Agent 的行为：它运行得有多快，恢复得有多好，以及能扩展到多远。

寄语： Agent 的未来，将一点一滴地由上下文构建。希望这些“血泪教训”能帮助你避免痛苦的迭代。

你有没有在构建 Agent 过程中踩过类似的“上下文工程”的坑？欢迎分享你的经验！