搭建 Agent：从一次性任务助手到稳定可迁移的虚拟员工
状态：持续整理中。当前是完整草稿版，后续会继续补充真实案例、图示和 skill 化的方法。
1. 我对 Agent 的理解
我现在对 Agent 的理解是：
Agent 不是一个简单的 skill，也不是一个只在当前对话里临时完成任务的提示词。
一个真正有价值的 Agent，更像公司里的一个员工。它应该有明确的身份、职责和工作边界；它接收相对固定的输入，经过相对稳定的处理流程，最后产出相对固定、可验收的输出。
也就是说，Agent 的重点不是“它能不能做某件事”，而是：
- 它是否知道自己是谁；
- 它是否知道自己负责什么；
- 它是否知道不负责什么；
- 它是否知道接收什么输入；
- 它是否知道应该交付什么输出；
- 它是否能在不同 session、不同上下文，甚至不同使用者手里保持稳定。
比如，一个视频生产 Agent。我们可以提前给它设定好视频风格、内容模板、分镜结构和输出规范。之后它接收一份文案，产出视频脚本、分镜方案，甚至进一步产出可执行的视频内容。
但这里真正困难的地方，不只是“让它生成一次视频方案”，而是要和 Agent 不断协作，把它内部的处理过程逐渐确定下来。哪些步骤必须做，哪些格式必须固定，哪些质量标准必须遵守，这些都需要在实践中慢慢沉淀。
2. 一次性任务助手和稳定 Agent 的区别
我现在会把 Agent 分成两类：
一种是处理当前任务的一次性助手。它可以在一个 session 里理解上下文，完成当前任务，甚至效果很好。但它的能力很大程度依赖当前对话里的临时上下文。
另一种是稳定、可迁移的 Agent。它不是只在某一次对话里能工作，而是换一个 session、换一个使用者，甚至放进多 Agent 协作流里，依然能保持相对稳定的输入、处理流程和输出质量。
前者搭建起来很快，后者才是真正难的地方。
我想要的 Agent，应该是可迁移的、可跨 session 的，也可以作为多 Agent 协作中的一个稳定节点。它不是一次性完成任务，而是能作为一个长期可复用的工作单元存在。
3. 搭建 Agent 的第一步：定义身份
真的去搭建 Agent 时，我觉得第一步不是让它马上干活，而是先设置好 CLAUDE.md、AGENT.md，或者其他记忆文件。
这些文件的核心作用，是明确 Agent 的身份。
需要提前说明：
- 它是谁；
- 它负责什么；
- 它不负责什么；
- 它应该用什么方式和用户沟通；
- 它应该如何判断任务是否完成；
- 它遇到不确定问题时应该怎么处理；
- 它在整个工作流里处于哪个位置。
这一步非常重要。因为如果一开始身份没有定义清楚，Agent 后续很容易混淆自己的角色。
比如它本来应该是一个“视频生产 Agent”，但它可能一会儿像策划，一会儿像剪辑，一会儿又像普通聊天助手。角色混乱后，后续再修会非常麻烦。
一个实际踩坑案例
我之前做过一个关于数据分析的多 Agent 协作流，里面包括数据爬取 Agent、综合分析 Agent、产品 PRD Agent。
它们在各自对应的对话 session 里表现都比较稳定，因为当时的上下文还在，每个 Agent 大致知道自己要做什么。
但问题出现在我新开了一个中控 Agent，准备把这些 Agent 串起来的时候。
我使用 Codex CLI 去调用对应 Agent 时，因为这是一个新的 session，之前调出来的上下文没有被继承下来。结果就是：这些 Agent 完全忘记了原来的工作流程，不清楚自己的输入输出，也没有按照我预定的流程执行。最终表现出来就是质量下降很严重，完成度也很低。
这个问题的本质，是我没有提前把规则文件固定好。每个 Agent 在单独 session 里看起来能工作，但它们的身份、输入、输出、协作关系，并没有被沉淀成可迁移的协议。一旦换到新的 session，Agent 就只能重新猜。
还有一种更隐蔽的问题，是定义本身的混淆。
有时候我前面定义的、后面实际想要的、以及 Agent 自己理解的，并不是同一件事。这样就会导致双方一直对不齐，花很多时间反复调整。后来我做了一个 Term Keeper skill，就是为了解决这类概念不一致的问题。这个点后续可以单独展开。
这个案例后面还可以继续补充三点：
- 当时中控 Agent 原本应该怎么调度这几个 Agent；
- 实际输出和预期输出差在哪里；
- 最后是怎么修的，或者现在认为应该怎么修。
4. 第二步：固定输入和输出
确定 Agent 的身份后，下一步是明确它的输入和输出。
一个 Agent 如果没有固定输入输出，就很难稳定复用。
比如视频生产 Agent 的输入可能是：
- 文案；
- 目标平台；
- 视频时长；
- 目标受众；
- 风格要求；
- 是否需要口播稿；
- 是否需要分镜；
- 是否需要素材建议。
它的输出可能是：
- 标题；
- 视频结构；
- 分镜脚本；
- 口播稿；
- 画面建议；
- 字幕节奏；
- 素材清单；
- 发布文案。
输入输出一开始可以不完美，但最好在新开 session、准备构建 Agent 的时候，就尽量先想清楚、说明白。
因为 Agent 的完成度很大程度上取决于它是否理解整个工作流。如果一开始输入输出说得很模糊，Agent 就会把精力花在猜测需求上；如果一开始就把输入、输出、格式和验收标准讲清楚，它完成整个流程的稳定性会高很多。
等到输入输出经过几轮使用后变得比较稳定，就应该写进记忆文件里，变成 Agent 的固定工作协议。
否则每次新开 session，Agent 都要重新猜“用户到底想要什么格式”，这会浪费大量时间，也会让输出质量变得不稳定。
5. 第三步：先跑完，再复盘，再固化
确定身份、输入和输出之后，不要急着一开始就把 Agent 的所有规则写死。
我现在更倾向的做法是：先让 Agent 完整跑一遍。
因为很多问题不是靠提前想就能想完整的。只有当 Agent 真正开始处理任务时，才会暴露出它哪里理解错了、哪里流程缺失、哪里输出不稳定、哪里没有达到我的质量标准。
所以我的最佳实践是：
- 先让 Agent 跑完整个任务；
- 看它的输出哪里不符合预期；
- 明确指出问题，不只说“不好”，而是说明哪里不好；
- 让 Agent 自己分析为什么会出问题；
- 让 Agent 提出改进方案；
- 验证改进后的效果；
- 如果这次改进确实有效，就把它固化下来。
这里最重要的是最后一步：固化。
如果只是当前 session 里改好了，但没有写进记忆文件、reference 或固定规则里，那么这次改进很容易随着上下文压缩、新开 session 或换一个使用者而丢失。
这也是我现在觉得搭建 Agent 最核心的一点：不是调一次就结束，而是要把调出来的最佳实践沉淀下来。
一次有效的调教，应该留下可复用的东西。比如：
- 一个更明确的身份定义；
- 一组更稳定的输入字段；
- 一个固定的输出模板；
- 一个质量检查清单；
- 一个失败案例；
- 一个 reference 示例；
- 一条必须遵守的强约束。
这些东西沉淀下来之后，Agent 才会从“这次能跑”慢慢变成“以后也能稳定跑”。
6. 为什么记忆文件最浪费时间，也最关键
我之前很容易低估记忆文件的重要性。
在一个连续对话里，Agent 好像很聪明，因为它有当前上下文。你前面说过什么，它还能记住；你刚刚纠正过什么，它也能接着改。
但这其实会造成一种错觉：我以为 Agent 已经学会了。
实际上，很多时候它只是暂时被当前上下文约束住了。只要新开 session，或者上下文被压缩，或者把这个 Agent 交给另一个人使用，它就很可能重新回到一个不稳定状态。
这时候就会出现几个典型问题：
- 它不知道自己到底负责什么；
- 它不知道上游会给什么输入；
- 它不知道下游需要什么输出；
- 它不知道哪些步骤必须执行；
- 它不知道什么样的结果才算合格；
- 它不知道遇到不确定情况时应该追问，还是应该自己假设。
所以，CLAUDE.md、AGENT.md 或其他记忆文件，本质上不是普通说明文档，而是 Agent 的岗位说明书、工作协议和质量标准。
如果这份文件写得不好，后面就会不断返工。
尤其是在多 Agent 协作里，这个问题会被放大。单个 Agent 在自己的 session 里表现稳定，不代表它能被中控 Agent 稳定调用。因为一旦进入新的调用链，每个 Agent 都必须依赖规则文件重新理解自己的职责、输入和输出。
这就是我之前数据分析多 Agent 协作流踩坑的地方。
数据爬取 Agent、综合分析 Agent、产品 PRD Agent 单独跑时都还可以。但当我想用中控 Agent 把它们串起来时，质量下降非常明显。原因不是这些 Agent 完全不会做事，而是它们的协作协议没有被固定下来。
每个 Agent 都缺少一份足够清晰的、跨 session 也能生效的工作说明。
7. 约束越多，Agent 越需要工程化
这里还有一个我最近越来越明显的感受：搭建 Agent 的难点，不只是写提示词，而是在给一个概率模型加约束。
大模型本质上是概率模型。
当约束很少时，它的回答空间很大，所以很容易生成一个“看起来还不错”的答案。比如让它自由写一个视频脚本、自由做一个分析、自由生成一份方案，它通常都能给出一个可用结果。
但当约束越来越多，问题就会变复杂。
比如你不仅要求它生成视频脚本，还要求：
- 符合某个平台的内容风格；
- 控制在固定时长内；
- 使用固定分镜结构；
- 适配固定人设；
- 口播不能太书面；
- 每一段都要对应素材建议；
- 输出格式必须方便后续 Agent 继续处理。
这时候，Agent 不是简单地“写得好”就够了。它必须同时满足很多约束。
约束越多，大模型越容易偏离你的真实偏好。不是它完全做不到，而是如果没有明确的规则、示例、检查清单和反馈机制，它很难稳定落在你想要的那个范围里。
这也是为什么我觉得：搭建一个处理当前任务的 Agent 很快，但搭建一个稳定、可迁移、可交付给别人使用的 Agent 很难。
前者更像 prompt engineering，后者更像工程化。
它需要：
- 身份定义；
- 输入输出协议；
- 处理流程；
- reference 示例；
- 质量标准；
- 异常处理规则；
- 版本迭代；
- 真实任务验证。
只有这些东西逐渐完善后，Agent 才不只是“能回答问题”，而是真的能承担一个稳定岗位。
8. 我目前总结的搭建流程
如果现在让我重新搭建一个 Agent，我会按这个流程来：
8.1 先定义岗位
先不要让 Agent 直接干活，而是先明确它的岗位。
我要先写清楚：
- 这个 Agent 是谁；
- 它在整个系统里的位置是什么；
- 它负责什么；
- 它不负责什么；
- 它面向谁交付；
- 它和其他 Agent 的边界在哪里。
如果这一步没写清楚，后面很容易出现角色混乱。
8.2 再定义输入和输出
接着要明确它接收什么，交付什么。
输入输出最好不要只写一句话，而是尽量结构化。
比如：
- 输入字段有哪些；
- 哪些字段是必填；
- 哪些字段可以为空；
- 输入不完整时应该如何追问；
- 输出必须包含哪些部分；
- 输出格式是否固定；
- 输出给人看，还是给下游 Agent 继续处理。
这一层越清楚，Agent 后续越稳定。
8.3 让 Agent 跑真实任务
定义完之后，不要只停留在理论上，要让它跑真实任务。
真实任务会暴露很多隐藏问题：
- 它是否理解错了职责；
- 它是否漏掉关键步骤；
- 它是否输出了不适合下游处理的格式；
- 它是否在不确定时胡乱补全；
- 它是否没有达到质量标准。
这些问题只有跑起来才知道。
8.4 复盘失败点
Agent 跑完之后，重点不是马上重写，而是复盘。
要把问题讲具体：
- 哪一段输出不符合预期；
- 为什么不符合；
- 它违反了哪个规则；
- 如果没有规则，说明应该新增什么规则；
- 这个问题是一次性失误，还是规则缺失。
这里不要只给情绪化反馈，比如“写得不行”“质量太差”。这种反馈对 Agent 的规则沉淀帮助不大。
更有效的反馈是：指出具体问题，再让 Agent 分析原因和修复方式。
8.5 把有效改进写进记忆文件
如果某次复盘产生了有效改进，就要立刻固化。
可以写进：
CLAUDE.md；AGENT.md；- skill 的
SKILL.md； - reference 示例；
- 输入输出模板；
- 质量检查清单；
- 术语表。
不要相信“这次已经说过了，它下次应该记得”。
只要目标是可迁移、可跨 session、可多人使用，就必须把有效经验写进稳定文件。
8.6 用新 session 验证
最后，最好用一个新 session 验证。
因为只有新 session 才能测试：这个 Agent 是否真的脱离了临时上下文，仍然能按规则工作。
如果新 session 里表现明显下降，说明规则文件还不够清楚。
这一步很关键。因为我们真正要的不是“当前对话里调好了”，而是“换一个上下文还能稳定工作”。
9. 后续准备整理成 skill
这篇笔记后续可以继续整理成一个辅助构建 Agent 的 skill。
但我现在不想急着直接做 skill。因为 skill 应该是从稳定经验里提炼出来的，而不是一开始就为了形式去写。
比较合理的顺序应该是：
- 先把我对 Agent 的理解写清楚；
- 再补充真实踩坑案例；
- 再总结稳定搭建流程；
- 再抽象成可复用的 checklist；
- 最后再把 checklist 写成 skill。
这个 skill 未来可以辅助做几件事：
- 帮我定义一个 Agent 的身份；
- 帮我检查输入输出是否清楚；
- 帮我发现职责边界是否混乱；
- 帮我把一次调试经验固化成规则；
- 帮我判断一个 Agent 是否具备跨 session 迁移能力；
- 帮我把多个 Agent 组织成可协作的节点。
也就是说，这个 skill 的目标不是“生成一个提示词”，而是辅助我构建一个真正稳定的 Agent。
10. 当前还需要继续补充的内容
这篇笔记后面还需要补几个部分：
- 数据分析多 Agent 协作流的完整案例；
- 中控 Agent 调用失败时的具体表现；
- 一个好的
AGENT.md应该长什么样； - 输入输出协议的示例模板；
- reference 示例如何保存；
- 新 session 验证应该怎么做；
Term Keeper如何解决概念对齐问题；- 如何把这套经验整理成 skill。
这些补完之后，这篇笔记会更完整，也更适合继续沉淀成方法论。