Agent 的复杂度到底在哪 && 以及Agent开发一些细碎的干货

做 Code Agent ,到底复杂度在哪里。我这里单单讲讲 code agent内核部分功能，不涉及交互以及高阶能力，大概是三个点：

1. 基础设施的构建，会话管理，token计算，规则文件，忽略文件管理等等 大概至少十几个模块。

2. 窗口长度管理，比如有朋友随便跑个300到1000次工具调用，这种级别的超长上下文你好如何应对，这几乎是个无止境的工作。

3. attention 管理，如何在越来越大的上下文情况下，保证任务能稳定的完成，比如任务聚焦的todo 的方案很好，还有工具数量的控制，system prompt里的内部流程的冲突等等，只基本上也是无止境的工作。

然后作为对比，我下面贴了 Manus 发的个内容，是比较扎实的细碎的干货，但是大部分trick 都能映射到我上面的三个部分中。

这里我再额外补充两点：

1. 我前面唯一没有提及的是 KVCache,但是如果看过我做的 RAG,就知道我去年的时候就讲KV Cache h缓存命中以及，prefill/decoding 的极致用到特别极致了。auto-coder.RAG 在 V3的kv cache缓存命中率大概可以节约2/3左右的成本。另外值得一提的是，Agentic 范式天然是有高概率的cache命中率的，但是随着 Agent 的复杂度巨大上升，尤其是上下文管理，比如做裁剪，必然会导致中间环节出现多次缓存失效，这里就需要很好的balance了。

2.还有一个小细节，Manus 能提及对工具做屏蔽而非移除这部分，大概方案是用到了decoding阶段，如果大模型输出某个工具时，强制降低他的概率，这种办法在结构化输出（比如输出json等）尝尝会用到。但是从工程角度而言，大部分人的做法是直接拿掉工具的定义，这种做法确实会造成幻觉（你的对话里已经有这个工具之前的使用了），要么你把会话里的相关的工具调用都裁剪掉，或者用我提供的办法：当一个工具不再可用，简单让工具返回一个不可用信息，表示当前阶段该工具不在可用，效果其实比前面的都会好。

-------

首先需要围绕 KV 缓存进行设计

 KV 缓存命中率是生产阶段 AI 代理中最重要的指标，它直接影响延迟和成本。

在 Agent 任务中预填充和解码之间的比例在代理中相比聊天机器人显得极为不平衡。

相同前缀的上下文可以利用 KV-cache，这大大减少了首次生成标记时间（TTFT）和推理成本，比如 Claude Sonnet 可以相差 10 倍。

简单解释一下 KV Caching：

KV Caching（Key-Value 缓存）是指在生成式 Transformer（如 GPT、T5 等模型的解码器部分）中，将每一步生成时计算得到的 Key（K）和 Value（V）矩阵保存下来。这样，在生成下一个 token 时，模型只需要计算新 token 的 Key 和 Value，并与之前缓存的内容一起用于注意力计算，而不必每次都重复计算所有历史 token 的 Key 和 Value。

提高 KV-cache 命中率涉及几个关键做法：

1️⃣保持提示前缀稳定。由于 LLMs 的自回归特性，即使是单个标记的差异也会使该标记及其之后的缓存失效。一个常见错误是在系统提示开头包含时间戳——尤其是精确到秒的时间戳。虽然这样可以让模型告诉你当前时间，但也会大幅降低缓存命中率。

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

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

屏蔽而非移除工具

随着你的 Agent 功能越来越多，他的工具数量激增。最近 MCP 的流行更是火上浇油。模型更可能选择错误的动作或采取低效的路径。简而言之，你的重装代理反而变得更笨了。

除非绝对必要，避免在迭代过程中动态添加或移除工具。主要有两个原因：

1️⃣在大多数 LLMs 中，工具定义在序列化后位于上下文的前部，通常在系统提示之前或之后。因此，任何更改都会使所有后续动作和观察的 KV 缓存失效。

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

Manus 使用了一个上下文感知的状态机来管理工具的可用性。它不是移除工具，而是在解码时屏蔽 Token 的 logits，以根据当前上下文防止（或强制）选择某些动作。

当用户提供新输入时，Manus 必须立即回复，而不是执行动作。还特意设计了带有一致前缀的动作名称——所有与浏览器相关的工具都以 browser_开头，命令行工具以 shell_开头。这使我们能够轻松地强制代理在特定状态下仅从某一组工具中选择，而无需使用有状态的 logits 处理器。

使用文件系统作为上下文

现代前沿的 LLMs 现在提供 128K 令牌或更多的上下文窗口。但在现实世界的代理场景中，这通常不够，有时甚至成为负担。

1️⃣观察数据可能非常庞大，尤其是当 Agent 与网页或 PDF 等非结构化数据交互时。很容易超出上下文限制。

2️⃣即使窗口技术上支持，模型性能在超过某个上下文长度后往往会下降。

3️⃣长输入代价高昂，即使使用前缀缓存也是如此。你仍然需要为传输和预填充的每个标记付费。

许多 Agent 系统会实施上下文截断或压缩策略。但过度激进的压缩不可避免地导致信息丢失。从逻辑角度来看，任何不可逆的压缩都存在风险。

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

Manus 的压缩策略始终设计为可恢复的。例如，只要保留网页的 URL，就可以从上下文中删除网页内容；只要沙箱中仍有文档路径，就可以省略文档内容。

通过复述操控注意力

在处理复杂任务时，它倾向于创建一个 todo .md 文件，并随着任务的推进逐步更新，勾选已完成的事项。

一个典型任务平均需要大约 50 次工具调用。这是一个很长的循环——由于 Manus 依赖 LLMs 进行决策，它容易偏离主题或忘记早期目标，尤其是在长上下文或复杂任务中。 

通过不断重写待办事项列表，Manus 将其目标念到上下文的末尾。这将全局计划推入模型的近期注意范围，避免了“中途丢失”问题并减少了目标不一致。

保留错误内容

语言模型会产生幻觉，环境会返回错误，外部工具会出现异常，意想不到的边缘情况随时都会出现。在多步骤任务中，失败不是例外；它是循环的一部分。

一个常见的冲动是隐藏这些错误：清理痕迹，重试操作，或者重置模型状态。抹去失败就抹去了证据。而没有证据，模型就无法适应。

改善智能体行为的最有效方法之一看似简单：在上下文中保留错误的路径。当模型看到失败的操作——以及由此产生的观察结果或堆栈跟踪时——它会隐式地更新其内部信念。这会使其先验远离类似的操作，减少重复同样错误的可能性。

不要被秒杀

少样本提示是提升 LLM 输出效果的常用技术。但在智能体系统中，它可能以微妙的方式适得其反。

语言模型是出色的模仿者；它们会模仿上下文中的行为模式。如果你的上下文充满了类似的过去行动-观察对，模型往往会遵循这种模式，即使这已不再是最优选择。

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