本文是「Agent 开发实践与思考」系列第 20 篇。系列目录：
- 2024
- 2025
- 01-28 长任务不失忆：上下文压缩、交接文档与子任务隔离
- 02-25 MCP 用了三个月：工具标准化之后 Agent 设计变了什么
- 03-25 拆解 Coding Agent：为什么”写代码 + 文件系统”是通用 Agent 的内核
- 05-13 Agent 如何用代码完成推理、校验、适配与展示
- 06-03 能看会说的 Agent：语音交互与 Computer Use 这半年
- 06-24 从同步问答到事件驱动：异步 Agent 的架构改造笔记
- 07-08 没有评估就没有迭代：我的 Agent 评估落地记
- 09-09 后训练扫盲：SFT 记知识、RL 学长处，和 Agent 有什么关系
- 10-01 AI Coding 的上下文摘要：几家产品到底在压缩什么
- 10-14 让 Agent 从经验里长本事：失败复盘、经验库与提示词自动优化
- 11-04 能力按需加载：从动态提示词到 Agent Skills
- [11-25 多 Agent 协作的真实收益与代价](../11-25-多 Agent 协作的真实收益与代价/)
- 12-23 两年搭 Agent 的复盘：工程约束下的取舍（本篇）
两年 Agent 实践复盘：工程条件与取舍
2024 年 7 月，我写了第一个 Agent，核心是一百来行的 ReAct 循环（我手写了一个 Agent：从一问一答到”思考-行动-观察”循环）。它要解决内部工具里单轮问答做不完的任务，当时没有打算写成系列。后来每碰到一个实际问题就记一篇，21 个月后有了这 20 篇核心文章。2025 年 12 月的 AICoding 概念综述 和 RAG 知识库调优 是系列外的补充，不计入其中。
回头看，这些文章里写的提示词、上下文压缩、单 Agent、文件系统工作流和多 Agent，都有明确的前提：当时的模型能做什么，系统能接到什么程度，哪些操作不能冒险，团队有多少时间把它做完。前提变了，方案的收益和维护成本也会变。把其中某个做法当作长期原则，很容易忘记它最初是在解决什么问题。
当时手里的条件
这个系列跨了两年。早期模型填工具参数、处理长上下文、连续执行多步任务时都不够稳定；内部系统的接口说明、权限和反馈也有缺口；团队没有现成的评估基建，许多需求还要在较短周期内上线。那时先要做到的是：用能接受的成本，把任务安全地做完。
排查问题时，我一般先看三件事：模型对当前任务到底能判断到什么程度，运行时给了它哪些信息，它调用工具后又拿到了什么反馈。这不是给能力分层。同一个错误常常同时牵涉几处。
有一次 Agent 执行出错，我先怀疑是模型能力问题，花了两天调提示词。后来翻调用日志，发现工具的 date 参数没有说明格式，模型既可能传“上周”，也可能传“2024年4月”。参数约定不完整，模型没有可据以选择格式的信息。补上说明后，问题就没再出现。此后我会先看执行轨迹，再决定该改提示词、工具还是上下文。
按这个视角回看，提示工程、记忆、RAG、压缩和 Skills 负责提供任务需要的信息；function calling、MCP、CLI 和代码执行把 Agent 接到可操作的系统上；评估、测试和后训练让行为能够被观察或调整。它们并不总有清晰的边界。schema 既是工具接口，也会进入上下文；评估也要覆盖整条链路。
当时为什么这样做
提示词曾经承担接口说明
2024 年初，模型处理隐含流程、业务术语和工具边界时经常出错，工具描述本身也不完整。我把操作步骤、异常处理和限制都塞进系统提示词，后来一度写到几千行（系统提示词写到几千行之后：提示工程的整理术）。在那时，这是把信息交给模型最快的办法，尽管难以验证和维护。
模型升级后，原来为某个失误加上的补丁会过时，有时还会妨碍新模型完成任务。现在，稳定的业务规则放进工具契约、权限校验和测试；任务事实按需提供；提示词只留下角色、目标和能明确判断的约束。接口语义、运行环境和模型对齐能力继续改善，提示词还能再短一些。
长上下文仍要筛选
200K 窗口出现后，我试过保留大量历史。对当时那组模型和任务来说，上下文接近 150K 时，模型开始漏用早期指令和关键信息（长任务不失忆：上下文压缩、交接文档与子任务隔离）。后来用压缩、交接文档和子任务隔离，只把当前决策要用的信息交给下一步，也顺带压低了推理成本。
150K 不是通用阈值，更不能据此判断长上下文是否有效。它只描述当时的模型、任务和内容组合。窗口变大、检索变可靠、状态管理变好，具体做法都可以调整；只要无关历史还会混进任务，调用成本还要算，信息筛选就仍然值得做。
单 Agent 链路的评估与追踪
2024 年中试多 Agent 时，Coordinator 负责拆分和汇总，其余 Agent 分头执行子任务。那时连单 Agent 的输入、工具调用和结果都没有稳定的评估与追踪。一个 Agent 的错误被下游当成事实使用后，很难分清问题出在拆分、上下文传递、工具调用，还是某一步判断。这部分代价直到今年 11 月才完整写进[多 Agent 协作的真实收益与代价](../11-25-多 Agent 协作的真实收益与代价/)。
后来我先补 trace、失败样本和回归评估，再考虑并行和角色分工。这样更容易定位问题。子任务相互独立、接口清楚、验证能自动化时，协作可能缩短周期；否则，交接和协调只会增加新的不确定性。
权限控制、评估与执行环境
工具层的权限与副作用约束
模型曾给出看上去合理、实际却危险的 rm、force push 等命令。提示词里的禁止语句会受上下文和任务影响，不能充当权限边界。所以目录白名单、参数校验、危险操作审批和可回滚设计都放在工具层（拆解 Coding Agent：为什么”写代码 + 文件系统”是通用 Agent 的内核）。修改外部状态的权限应由系统控制，不能指望模型每次都遵守说明。
权限模型和工具能力会继续变化，但只要 Agent 能改动外部状态，运行环境就要负责执行前后的校验。模型变强可以减少误调用，授权、审计和回滚仍然少不了。
用评估集检查改动
写完没有评估就没有迭代：我的 Agent 评估落地记后，团队开始把主要改动放进评估集比较。此前改提示词主要靠使用感受判断，回归往往上线后才暴露。评估集、trace 和失败 case 能比较不同版本，也能定位失败发生在检索、工具选择、参数构造还是结果处理。
要不要投入评估，取决于任务目标能否定义、样本能否维护、运行成本是否可接受。一次性脚本或需求变化很快的任务，人工验收可能够用；需要持续迭代、切换模型或扩大覆盖面的任务，评估基建能少走一些重复试错的路。
文件系统作为执行环境
在 拆解 Coding Agent 和 Agent 如何用代码完成推理、校验、适配与展示 中，我把文件系统和代码当作执行环境。今年做基建收敛时又用了这条路径：团队把多套 Vue2、Vue3、React 基建收敛成一套，AI 编写约十万行代码，不到五天完成，我负责架构和验收标准（AI Agent First 驱动大型项目开发的经验复盘）。
这个项目运行时间长，要反复验证，也要允许人随时介入。文件系统能留下任务状态和中间产物，便于检查和恢复；测试能及时反馈修改结果。这样的任务适合把文件系统作为执行环境。结构化 API 流程、短事务或约束很强的工作流，则可能更适合状态机、数据库和专用编排系统。
系列外还有两篇补充文章：AI Coding 概念综述梳理了 Prompt、Context、MCP、Skills 的发展脉络；RAG 知识库调优整理了知识库调优的工程细节，接着写 2024 年的 RAG 补记。
方案取舍会随模型和系统变化
两年间模型迭代了五六代，许多补偿措施已经没那么必要。工具调用更稳定后，可以删掉提示词里的格式补丁；长上下文利用得更可靠、状态管理更完善后，压缩策略可以调整；自动验证覆盖得更多后，任务可以拆得更细、并行得更多。这些文章记录的是当时能力还不具备，或成本还没降下来时的做法。
模型升级后，仍有几件事要处理。模型不了解私有系统和实时业务状态，外部信息要以合适的形式提供；修改外部状态要受到权限和审计约束；复杂任务的结果要经过反馈验证。这些要求分别落在输入、执行和验证上。以后实现它们的东西可能不再叫 RAG、提示词工程或 Agent，但责任仍然要有人承担。
每次条件变化后，都要重新看当前瓶颈是什么，补偿手段还值不值得维护，以及模型和系统各自该负责什么。
系列索引
循环与工具调用：
上下文与知识：
- 系统提示词写到几千行之后：提示工程的整理术
- 给 Agent 做记忆：会话历史、用户画像与遗忘
- RAG 实战两年后再补记：混合检索、重排与”不知道就说不知道”
- 上下文窗口的成本课：KV Cache、Prompt Caching 与消息顺序
- 长任务不失忆：上下文压缩、交接文档与子任务隔离
- 能力按需加载：从动态提示词到 Agent Skills
工具与执行：
- MCP 用了三个月：工具标准化之后 Agent 设计变了什么
- 拆解 Coding Agent：为什么”写代码 + 文件系统”是通用 Agent 的内核
- Agent 如何用代码完成推理、校验、适配与展示
- 能看会说的 Agent：语音交互与 Computer Use 这半年
评估、学习与协作：
- 从同步问答到事件驱动：异步 Agent 的架构改造笔记
- 没有评估就没有迭代：我的 Agent 评估落地记
- 后训练扫盲：SFT 记知识、RL 学长处，和 Agent 有什么关系
- 让 Agent 从经验里长本事：失败复盘、经验库与提示词自动优化
- [多 Agent 协作的真实收益与代价](../11-25-多 Agent 协作的真实收益与代价/)
2026 年继续关注的问题
agentic RL 可能让环境和反馈设计更值得投入。模型在环境中反复执行时，任务定义、奖励信号、验证器和成本约束都会直接影响训练或优化结果。评估基建也可能从发布前检查延伸到运行环境里，投入多少仍取决于任务是否需要持续优化。
Agent 间协议，例如 A2A，是否值得引入还要看实际场景。多数项目的任务复杂度和系统边界，目前还不足以支持专门协议的投入。跨系统协作、身份传递、状态恢复和责任划分成为稳定需求后，再来判断更合适。
评估基建中可复用的部分可以从项目里整理出来，能否继续推进仍取决于团队目标和实际需求。这个系列先写到这里；以后有新的约束、方案和结果，再单独记录。
