Cursor团队分享Agent Harness Token优化实战指南

这里有一个基于我们在 Cursor 学到的经验来改进你的 Agent Harness 的提示词。请享用 # 改进此 Agent Harness 的 Token 效率 你正在开发一个 LLM Agent Harness：包括系统提示词、工具定义、请求组装、上下文缓存、压缩以及工作如何在多个 Agent 之间分配。在不降低其任务表现的前提下，降低 Agent 运行的成本。- 目标：降低每个完成任务的加权 Token 成本。- 约束：任务质量没有可测量的下降。按任务而非按请求进行衡量。每一轮对话都会重新发送前缀（工具、指令、设置以及目前的对话历史），因此，虽然某种改动缩小了单个请求的大小，但如果增加了轮次，总成本可能会更高。根据计费类型对 Token 进行加权：输出、未缓存输入和已缓存输入的定价差异巨大。请按以下顺序操作：映射 Harness 并测量基线，对机会点进行排序，直接实施安全的改动，将其余改动置于功能开关后或作为提案提出，然后报告结果。以下数据来自一个团队的生产环境编码 Agent 及其多 Agent 实验。用它们来评估规模大小，而非作为目标。这一轮改动（提示词修剪、工具卸载、缓存布局、稀疏行号、子 Agent 调优）将该团队的总体 Token 成本降低了约 7%，且未造成质量损失。较大的百分比仅适用于每个改动所影响的请求部分。## 原则 1. 改变 Harness 发送的内容，而不是增加模型的难度。不要要求模型节省 Token。一个让模型“注意保留 Token，不要浪费”的 Harness 发现，模型变得不愿承担雄心勃勃的任务，有时甚至拒绝执行，理由是它不应该浪费 Token。2. 强大的模型需要的是定义，而非命令。“严禁”、“你必须”、“重要”等列表，以及针对旧模型习惯的防御措施，通常可以用对每个工具功能的 plain descriptions（普通描述）来替代。一个团队通过这种方式削减了约三分之二的系统提示词，且更短的提示词在不同模型系列中均有效。仅对模型无法知晓的内容（产品、环境、用户的流程）以及你在转录记录中看到的怪癖进行指示。3. 静态上下文用于存放大多数轮次所需的内容。其余内容应在需要时动态获取。减少前置上下文也意味着更少令人困惑或矛盾的信息。4.预期移除操作能带来收益。为较弱模型编写的护栏、成为瓶颈的协调步骤，以及现在模型能自主执行的行为提示，都会消耗 token。5. 实际使用量决定一切。评估（Evals）是一个快速的代理指标，但它们倾向于困难问题，并遗漏了请求的真实混合情况。## 1. 映射工具链并测量基线 查找： - 请求组装的位置、系统提示词以及工具模式。如果框架或 SDK 构建请求，找到其用于控制消息顺序、缓存控制和工具加载的钩子。 - 工具结果的格式如何，历史记录如何保留、截断或摘要。 - 是否生成子智能体或并行智能体，如果有，是如何生成的。 - 使用了哪些模型和提供商 API。从提供商文档中，获取提示词缓存行为（自动或显式断点、TTL、最小可缓存长度）以及输出、未缓存输入和缓存输入的价格。 - 现有的日志记录、token 核算和评估。如果工具链没有按计费类型和缓存命中记录每个请求的 token 使用情况，首先添加该功能。后续所有工作都依赖于此。然后渲染几个真实请求（来自日志，或通过运行代表性任务），并使用模型的 tokenizer 或 API 的使用字段统计每部分的 token 数量。产出： - 按来源 × 计费类型的成本份额。来源包括：系统提示词、工具定义、技能/规则/集成描述、用户消息、文件读取、搜索结果、命令及其他工具输出、历史记录、摘要、子智能体。 - 每个请求的静态 token 数、缓存命中率以及每个任务的轮次。 - 按工具划分：至少调用一次的运行比例及其错误率。阅读渲染后的请求，而不仅仅是模板。重复内容、泄漏的易变值以及顺序错误的代码块只会在那里显现。按花费份额 × 可移除比例 ÷ 质量风险对机会进行排名。## 2. 系统提示词和注入上下文 标记每条指令： - 保留：模型无法推断的产品或环境知识、针对在该模型转录本中看到的怪癖的修复方案，以及某种模式所依赖的规则。 - 重写：将命令和强调语转换为普通描述。将提醒转化为约束："不写 TODO，不做部分实现"比"记得完成实现"更有效。将模糊的数量转化为范围："生成 20–100 个任务"能激发出远比"生成许多任务"更积极的行为。- 删除：能力强大的模型默认就能处理的内容、防止该模型出现你未曾见过的行为的措施、重复工具描述的文字，以及可能与用户请求相矛盾的行。经过训练以将系统指令置于用户消息之上的模型会偏向系统提示词。- 移动：任何与特定用户或特定请求相关的内容（日期、环境、仓库状态、技能或子智能体列表、用户规则）移至缓存边界之后的用户角色设置消息中。以相同方式审计其他注入的上下文。随着模型的改进，这些数据的背后团队删除了目录树、预检索片段、附件文件的压缩副本、每次编辑后注入的 lint 错误、强制扩展短文件读取，以及每轮对话中工具调用的上限。他们保留了小而高价值的信息：操作系统、仓库状态以及打开或最近查看的文件。跳过开放式工作的检查清单。模型会优化列出的项目并降低其他所有项目的优先级。## 3. 工具定义 工具模式随每个请求一起传递。核心集合之外的大多数工具在不到 20% 的对话中被使用，将它们移出静态上下文可减少 60% 的工具描述 token。对集成工具（如 MCP 服务器）也采取同样做法，即在上下文中保留名称，并将完整模式放在每个服务器对应的一个文件夹中，供代理通过 grep 或 jq 搜索，这在使用的会话中将总 token 数减少了 46.9%。- 保留在静态上下文中：高频工具（对于编码代理而言：read、search、edit、shell）、模型即使在其不存在时仍尝试调用的工具，以及某种模式所依赖的工具。- 卸载其余部分：仅保留名称或一行指针，使完整模式可按需发现。将相关工具分组以便一起加载，并将状态（如"需要重新认证"）放置在代理能看到的地方。- 精简剩余内容：描述行为和参数，摒弃使用说明。- 通过测试几种配置并跟踪 token、成本、延迟、工具调用错误和任务成功率来选择最佳拆分方案。## 4. 缓存布局 按顺序排列每个请求，以使可复用的前缀尽可能长：`工具定义 → 系统指令 → [断点] → 设置消息（技能、子智能体、规则、环境）→ [断点] → 对话` - 确保跨轮次的前缀字节完全一致。使用确定性的工具调用顺序和序列化机制，将时间戳和 ID 置于边界之后，仅在压缩时重写之前的消息。- 如果提供商支持，请使用显式断点；否则依赖自动前缀缓存，并确保稳定部分优先缓存。遵守 TTL（生存时间）和最小长度规则。- 在对话中途切换模型会丢弃缓存（缓存是按模型和提供商隔离的），并将新模型未写入的历史记录传递给它。当需要不同模型时，将其作为具有全新上下文的子代理运行。显式断点加上将每次请求的设置移至断点之后，可减少 20% 的冷缓存未命中。## 5. 运行期间添加的工具结果及其他上下文 - 大型输出（命令、集成、日志）：将其写入文件并返回路径、大小及简短尾部。代理可执行 tail、grep 或读取指定范围以获取更多内容。截断会导致数据丢失，而内联则会膨胀后续每个请求的大小。以相同方式处理长时间运行的终端会话。- 高容量格式：查找每行或每项重复出现的开销。对文件的每第 10 行进行编号 rea

原文超出正文长度上限，此处截断——上游还有内容，完整版见上方「原文 ↗」。