很多 Agent 项目一开始都很令人兴奋：给模型一段系统提示词，接几个工具，让它自己规划、调用、总结，十分钟就像拥有了一个“数字同事”。但真正要把它做成可交付的产品，难点往往不在“让模型回答一次”，而在让它稳定地完成一类任务。
所以我更愿意把 Agent 项目理解成一种工作流工程：模型负责理解、推理和生成，工具负责确定性的行动，记忆负责上下文延续，编排负责把复杂任务拆成可恢复的步骤，评估和观测负责告诉我们它什么时候做对了、什么时候开始跑偏。
阅读提示：本文比「AI / Vibe Coding 新手系列」更偏工程化，适合已经跑通过一个 demo、想把它做成可交付项目的人。如果你还没做过第一个 Agent，建议先从新手系列的实战篇：用 Vibe Coding 做一个最小 Agent开始，跑通之后再回来看这篇。
先定义任务，不要先定义 Agent
做 Agent 最容易踩的坑，是一上来就问“我要用哪个框架”。更好的起点是问：它到底替用户完成哪件事？
一个好的 Agent 场景通常有几个特征：
- 输入不是单轮问答，而是一个需要拆解的目标。
- 过程中需要读取资料、调用工具或修改外部系统。
- 中间步骤可能失败，需要重试、回滚或让人确认。
- 输出有明确的验收标准，而不只是“看起来挺聪明”。
比如“帮我写日报”更像普通生成任务；“读取今天的提交、筛选我参与的任务、归类为进展/风险/明日计划、发到指定群组”就更接近 Agent 项目。后者包含数据获取、规则判断、结构化输出和外部动作，必须被工程化。
在写第一行代码前，可以先把任务写成一条可执行链路：
用户目标 -> 意图识别 -> 收集上下文 -> 规划步骤 -> 调用工具 -> 校验结果 -> 输出/执行动作 -> 记录反馈
这条链路越清楚，后面选模型、选框架、设计数据库才越有方向。
Agent 的核心 contract
一个可维护的 Agent，应该先有 contract，而不是只有 prompt。这个 contract 至少包含五件事：
- 角色：它负责什么，不负责什么。
- 输入：用户会给什么信息，系统会补充什么上下文。
- 工具：它能调用哪些能力，每个工具的参数和副作用是什么。
- 状态：哪些信息只在本轮有效，哪些要跨会话保存。
- 输出：最终结果的结构、质量标准和失败时的表达方式。
Prompt 是 contract 的一部分，但不是全部。很多项目失败，是因为把权限、数据格式、业务规则、错误处理都塞进 prompt，结果模型每次都要重新“想起”系统边界。更稳的方式是：能用代码固定的就用代码固定，能用 schema 约束的就用 schema 约束，prompt 只处理真正需要语言推理的部分。
技术栈可以这样拆
Agent 技术栈看起来很热闹，但落到项目里，大致可以拆成七层。
1. 模型层
模型层负责理解、推理、生成和工具调用。这里要关注的不只是模型能力，还包括上下文窗口、结构化输出、延迟、成本、并发限制和是否支持多模态输入。
如果项目很轻，可以直接用模型 API 自己写循环：构造消息、让模型选择工具、执行工具、把结果塞回上下文、再让模型继续。这样灵活、透明，也便于调试。
如果项目已经出现多轮工具调用、handoff、会话、追踪、审批或 guardrails，使用成熟 SDK 会更舒服。比如 OpenAI Agents SDK 把 agent loop、工具、handoff、session、tracing 等能力组织在一起，适合需要快速搭出工程骨架的场景。
2. 工具层
工具是 Agent 接触真实世界的手。一个工具应该像 API 一样被设计，而不是像“给模型开的后门”。
好的工具有几个特点：
- 名字清楚，描述能帮助模型判断何时使用。
- 参数 schema 明确，尽量避免自由文本大杂烩。
- 返回值结构稳定，包含成功、失败和可恢复错误。
- 对有副作用的动作设置确认、权限和审计。
- 工具内部保持确定性，不把业务规则再交给模型猜。
如果一个 Agent 能发邮件、改数据库、创建订单，那这些工具就必须有权限边界。越靠近真实资产，越不能只靠“请谨慎操作”这种提示词。
3. 编排层
简单 Agent 可以是一段 while loop；复杂 Agent 更像一个状态机。
当任务包含分支、重试、人工确认、暂停恢复、多角色协作时，就需要编排。LangGraph 这类图式编排框架的价值在于：把“下一步做什么”从一团隐形对话历史中抽出来，变成节点、边、状态和 checkpoint。这样系统可以恢复，可以回放，也可以在关键点插入人工审批。
一个实用判断是：如果你的 Agent 失败后很难回答“它刚刚执行到哪一步”，就该认真考虑编排层了。
4. 记忆与知识层
Agent 的记忆不要混成一个概念。至少要分三类：
- 工作记忆：本次任务中正在处理的上下文。
- 会话记忆：同一用户或同一线程内的偏好、历史和中间状态。
- 长期知识：文档、FAQ、代码库、业务规则、历史案例。
RAG 适合解决“模型不知道某些外部知识”的问题，但它不是万能记忆。向量检索可以帮你召回相似内容，数据库和对象存储则更适合保存明确事实、用户偏好、任务状态和审计记录。
不要把所有历史对话无脑塞进上下文。更好的做法是：把可结构化的信息结构化保存，把可检索的知识建索引，把真正影响当前决策的内容再放回 prompt。
5. 协议与集成层
当工具越来越多，直接给每个客户端写一套私有集成会变得很重。MCP 的价值在于提供一种统一方式，让 AI 应用发现和调用外部系统里的 tools、resources、prompts 等能力。
在真实项目里，MCP 不只是“接工具”的协议，也会逼你把工具描述、输入输出、错误、权限、确认流程想清楚。哪怕暂时不使用 MCP，也可以借鉴它的思路：工具应该可发现、可描述、可约束、可审计。
6. 评估层
没有评估的 Agent 项目，很容易陷入“今天感觉不错，明天突然不行”。评估不一定一开始就复杂，但必须尽早出现。
可以先准备三类测试集：
- 黄金路径：最常见、最应该成功的任务。
- 边界路径：缺参数、歧义输入、权限不足、工具失败。
- 回归路径：线上曾经失败过的真实案例。
评估指标也不只看最终文本。Agent 项目还要看工具是否选对、参数是否正确、是否越权、是否多花了不必要的步骤、是否在不确定时请求确认。
7. 观测与运营层
Agent 的日志不能只记录“用户问了什么，模型答了什么”。你还需要知道：
- 每一步调用了哪个模型和工具。
- 输入输出 token、延迟和成本是多少。
- 工具参数是什么，返回了什么错误。
- 哪些步骤被重试、跳过或交给人工确认。
- 最终结果有没有被用户接受或修改。
OpenTelemetry 的 GenAI 语义约定正在把这类追踪变得更标准化。即使项目暂时不用完整的 tracing 平台，也应该从第一天开始保留结构化事件。Agent 越复杂，trace 越像产品的黑匣子。
一个从 0 到 1 的路线
如果我要做一个新的 Agent 项目，我会按这个顺序推进。
第一步，选一个窄场景。不要做“万能助手”，做“能稳定完成一种工作流的助手”。比如只处理报销单、只分析 PR、只整理会议纪要。
第二步，写验收用例。先写 10 到 30 个真实样例，包括应该成功的、应该拒绝的、应该追问的。样例越具体，prompt 和工具设计越不容易飘。
第三步，做最小工具集。只开放 Agent 必须使用的工具，每个工具都写清 schema、权限和错误返回。工具少一点，系统更容易稳定。
第四步，搭一条可观测链路。记录模型输入输出、工具调用、状态变化和用户反馈。没有 trace 的 Agent 调试起来会非常痛苦。
第五步，加人工确认。凡是会修改外部系统、花钱、发送消息、删除数据、影响他人的动作，都应该先经过确认。等系统足够稳定，再逐步放开自动执行。
第六步，持续收集失败案例。把每次失败沉淀成测试集、工具约束或流程改进，而不是只改一句 prompt。Prompt 调整是最快的修复，也是最容易反复退化的修复。
常见误区
第一个误区是把 Agent 当成“大 prompt”。Prompt 很重要，但项目真正的可靠性来自工具边界、流程控制、状态管理和评估。
第二个误区是过早多 Agent 化。多个 Agent 之间互相聊天很酷，但也会增加不可预测性。除非角色边界真的清楚，否则先用一个 Agent 加明确步骤，通常更稳。
第三个误区是把 RAG 当记忆。RAG 负责召回知识，不负责保存事实。用户偏好、任务状态、审批记录、执行结果应该进入数据库或事件日志。
第四个误区是只看成功案例。Agent 最值钱的工程资产不是 demo，而是失败样例库。失败样例越多，系统越接近产品。
第五个误区是忽视权限。一个能调用工具的 Agent，本质上就是一个自动化执行者。它的权限、审计和回滚机制，应该像后台服务一样严肃。
判断一个 Agent 项目是否成熟
可以用这几个问题自查：
- 它的目标是不是足够窄，能用真实用例验收？
- 每个工具的输入输出和副作用是否清楚？
- 失败时能不能定位到具体步骤，而不是只看到“模型答错了”？
- 是否有黄金路径、边界路径和回归路径评估？
- 是否知道每次执行的成本、耗时和工具调用链？
- 对高风险动作是否有人类确认或权限控制？
- 新增一个工具或场景时，系统会不会立刻变得不可预测？
如果这些问题都能回答，Agent 就不再只是一个漂亮 demo，而是一个可以被维护、调试和逐步扩展的工程系统。
结尾
做 Agent 项目，最重要的不是追逐某个框架，而是建立一种工程视角：让模型做它擅长的理解和推理，让工具做确定性的动作，让状态和日志记录过程，让评估持续约束质量。
Agent 的魅力在于它像是在“自己做事”；Agent 的工程难点也正是在这里。我们要给它自由度，也要给它轨道。只有这样，它才会从一个会演示的智能体，变成一个能交付的产品。