下面顺着一个真实项目的开发顺序，把一整套 Agent 工程怎么搭，从头到尾盘一遍。整体分成 10 个部分：从最开始定边界、分目录，到中间怎么管上下文、怎么做评测，一直到最后的部署和监控，按照真实项目节奏来。
第一步不是写代码，而是搞清楚你的 Agent 到底要解决什么问题。
现在很多团队做 Agent，容易一开始把目标定得太宽，想让它查资料、洗数据，最好还会做 PPT。但这种没有清晰边界的设计，在工程实现上是不可交付的。
它到底要解决什么具体问题？用户给它什么输入？最终必须产出什么格式的结果？哪些操作它可以自己决定？在什么判定条件下任务才算成功？
比如做一个 AI 科普视频 Agent，用户给一个选题，它自己去查资料、梳理观点，最后排分镜。要加一条限制：它可以自己去翻网页查数据，但是一旦涉及对外发布，或者调用高费用接口，必须停下来等待人工确认。
目标如果一开始就是模糊的，后面写着写着就会发现各种工具和存储模块越加越多，到最后系统变得非常臃肿。所以第一条原则就是：先把边界划清楚。
像 README、Git 和环境变量这些基础规定，我们都很熟悉。
如果你平时在用 Codex 或 Claude Code 这些编码工具辅助开发，可以在根目录直接加一个 AGENTS.md，把它当成一份专门给 AI 工具看的项目说明书：代码往哪放，哪些底层文件不能随便改动，加了新功能之后必须跑哪些测试，以及代码提交之前要做什么检查，全部提前写清楚。这样它就不需要去猜测你的工程习惯。
还有一个细节：千万不要把 API key 直接写进源码里。真实密钥要统一放在本地的 .env，给外部只保留一个包含必要变量名的 .env.example，并且把 .env 写进 .gitignore 里过滤掉。
这些工作看起来跟核心业务逻辑没有什么关系，但能大幅降低后续的维护成本。先把规则定下来，再开始写业务代码。项目如果准备长期维护，目录的分工就要切得比较清楚。
像 agents、tools、skills、workflows、prompts、context、memory、tests、evals 这些该拆分的模块，都要独立出来。
很多人搞不清楚的是 Workflow 和 Agent 的职责边界：
· Workflow 是一条固定的流水线，第一步执行什么，失败了走哪个重试分支，这属于确定性的流程编排。
· Agent 负责的是流程走到某个节点、遇到开放式问题时，利用模型去做推理和判断。
还是拿视频项目来说，比如查资料与文案排分镜，各自是一个独立的 Agent。如果查资料发现信源不够，是继续检索还是直接往下走；文案连续两次没有达到标准，是先补充资料还是继续修改，这些流程调度必须归 Workflow 管，不要把所有事情都塞给一个超级 Agent 去处理。
流程一旦拉长，中间只要某一步执行异常，你很难排查它到底是因为什么原因跳转过去的。确定性的流程交给 Workflow，把需要理性判断的部分交给 Agent，那么以后换模型或者增减步骤，都不会影响到整条链路的稳定性。
这里要把这 5 样东西定下来：
· Role： 角色定位。比如明确它是一个科普视频撰稿人。
· Goal： 要达成的目标。比如根据前面核实好的材料，写出一篇结构清晰、可以直接口播的初稿。
· Instructions： 行为规则。比如口语化、有临场感，不得引入未经确认的信息，观点需对应来源。
· Tools： 可用工具。比如资料读取、稿件读写、版本保存。
· Output Schema： 固定输出结构。要求必须按 JSON 输出，里面哪部分是标题、正文、引用，哪部分是待确认项，定义得清清楚楚。
Output Schema 固定了，下游 Agent 才能稳定解析，任务才可维护。很多时候系统表现出问题，不是模块之间的逻辑有问题，而是数据协议没有规范好。
搜索、网页读写、文件查询、数据库计算、调用接口，都属于 Tools。
写 Tools 最关键的原则就是一个：一个 Tool 只做一件明确的事。
搜索就只负责搜索，读取网页就只负责提取，保存文件就只管写入。不要写一个把查询、抓取和写库全混在一起的大工具。模型在决定调用哪个工具的时候，依赖的是你给工具写的一个描述文本。工具的职责越复杂，描述越难写，Agent 调用错误的概率就越高。
而且工具的输入输出一定要规范。比如一个 search_web，输入查询词，返回的就应该是标准的字典，包含标题、摘要和 URL，不要返回格式不统一的纯文本。
另外，每个 Tool 都应该能够单独跑单元测试。系统出问题的时候，到底是工具本身的逻辑挂了，还是模型给的参数不对，工具越简单，定位越快。
这两个概念特别容易被混在一起。记住一句话就够了：Tool 解决“我能不能做这件事”，Skill 解决“这件事应该怎么做能更稳定”。
搜索网页是一个 Tool，保存本地也是一个 Tool。但如果你要完成“针对一个新产品做技术调研”，这就是一个完整的 Skill，因为在这个 Skill 里面，固化了一套成熟的执行步骤：先检索官方网站，再去查开发文档和代码仓库，同时把社区里面的讨论抓取回来，清洗去重，最后整理成一份标准的调研报告。
总结而言，Tool 解决的是能不能做这件事，而 Skill 解决的是怎么把这件事稳定地做下来。
以后换了一个新的调研题目，不需要模型每次重新摸索怎么查资料，直接复用这一套验证过的 Skill 就可以了。一个项目长期积累下来，真正有复用价值的资产，其实是这些封装好的 Skills。
很多人习惯一上来就必须长期记忆、向量数据库、RAG，其实不是这样的。
建议把 Context 和 Memory 明确分开：
· Context： 负责当前单次任务需要知道的信息，包括当前输入的题目、刚刚检索回来的几条数据、工具返回的结果，以及流程当前执行到的位置。生命周期就跟着任务结束。
· Memory： 负责任务结束之后真正需要长期沉淀的数据，比如用户长期喜欢什么文案风格、哪些选题已经做过、项目有哪些固定规则。
不必长期保存：临时网页、失效的中间结果、一次性错误信息。
落地建议：项目早期用 JSON、SQLite 或普通文件就够了；真的出现大量任务检索需求后，再考虑向量数据库。
不是记得越多 Agent 越聪明，记住了错误的东西反而更难纠正。
不建议把所有的业务逻辑全推进一个巨大的 System Prompt 里面。更合理的做法是给它做拆分，层次分明一点：
· System： 先把底层的角色和全局原则定下来。
· Task： 交代清楚这次调用具体要做什么。
· Constraints： 明确哪些事情坚决不能干。
· Examples： 什么样的数据才算合格。
· Output Schema： 用 Output Schema 把输出的格式固定下来。
这样分层最大的好处就是改动成本特别低。比如哪天你发现输出的内容里面，它总喜欢把推测当成事实来写，那你直接去改 Constraints 这一层就好了，完全没有必要冒着风险把整个 Prompt 全部重写一遍。
而且 Prompt 本身就是代码逻辑的一部分，一定要老老实实放进 Git 里，这样每一次改动都有据可查，心里也踏实。
平时我们做传统软件，基本看测试：函数有没有抛异常，参数对不对。这些底层的单元测试当然要跑。
但是在 Agent 的系统里面，代码完全没有报错，业务交付的结果可能根本没法用。
比如说文本模块顺畅，函数执行一路绿灯，接口一点都没有报错，但你仔细一看，里面引用的全是 2 年前的旧数据，甚至把别人推测的事情写成了既定事实。从程序运行的角度来看，是成功的；但是从业务交付的角度看，这其实是一个彻底的失败。
所以除了代码级的测试之外，还必须搭一套评估体系。你可以挑几十个典型的真实任务，当成基准测试集，专门去量化它的事实准确率、幻觉率、工具选择准确率、任务完成率、输出结构、成本、速度。
固定 50 个真实选题做基准：Prompt A 成功率 82%，Prompt B 91% 且成本下降，才算真的变好了。“我感觉聪明了一点”没有工程意义。
以后每次改了 Prompt，或者换了底层模型，就回过头来把这一批固定的题目重新跑一遍。实打实地从 80% 多涨到 90% 多，而且花销还没有超标，这个时候你才能确定，这次修改是真的改好了。千万不要靠“我感觉它好像变聪明了”，这种主观感觉没有任何参考价值。
一句话：代码能不能跑通看测试，但交付质量到底好不好，必须靠评估的数据说话。
本地 Docker、云环境都可以，但 Observability 必须有。
服务一旦上线，一条清晰的 Trace 链路是关键：用户给了什么需求，流程当前走到了哪一步，Agent 做了什么选择，调用了哪个 Tool，工具的输入和返回是什么，最终输出是什么。
顺带把调用耗时、Token 消耗、错误率这些指标全都记下来。
为什么这个链路追踪这么重要？因为模型本身是有一点随机性的。线上偶尔会有用户跑来反馈说有问题，这个时候你顺着链路点进去，往往会发现模型本身的逻辑其实完全没有毛病，纯粹是搜索工具从网上抓回了一篇过时的文章。
遇到这种情况，你该做的是去修工具、修数据源，而不是回过头去调 Prompt。要是手里没有这些 Trace 和日志，你是根本定位不到根本原因的，最后也只能碰运气到处改，越改越乱。
所以一套成熟系统的开发闭环一定是：上线运行，通过记录发现问题，针对性地去修复，然后再验证上线。
整个 Agent 的搭建，最后快速回顾一下：
动手之前，先要把任务边界划清楚，别把东西混在一起。确定性的流程交给 Workflow，需要灵活判断的部分就交给 Agent。具体的接口能力是 Tools，靠 Skills 一步一步沉淀下来。当前任务需要的数据放在 Context 里，只有真正长期有价值的才沉淀到 Memory 里面。Prompts 要拆开分层写，老老实实写进 Git 里。代码能不能跑看测试，做得好不好看评估。最后配上 Trace 和监控，让系统在生产环境里能看得清清楚楚。
当你把这一整套体系搭完之后，你的 Agent 才算真正从一个随时可能出状况的演示 Demo，变成了一个可维护、可扩展、能放心跑在生产环境里的工程。
说到底，做 Agent 的工程，最核心的事从来都不是怎么让模型调用一次工具，而是怎么通过工程手段上的确定性，把 AI 本身的不确定性给收敛起来，让它能长期稳定地把业务跑完。