做智能体项目最容易被低估的，往往不是模型选型，而是模型外面那层系统设计。我见过不少团队，demo 里让大模型调用两三个工具跑通一个流程，感觉已经万事大吉；一进到生产环境，多轮状态、工具超时、参数解析、失败重试全都堆在一起，整个智能体根本没法稳定复现。最近把某高校 CS329Z 课程中关于框架与智能体设计的讲义又完整过了一遍，发现课程里那套拆解思路，恰好能解释我在实战中踩过的大部分坑。这篇文章把课程核心抽出来，结合自己的工程经验展开，适合正在搭智能体、纠结要不要引入框架、以及被线上智能体折磨到想重构的工程师。
1. 智能体的设计边界：模型只是底座，系统才是智能
1.1 Demo 与生产环境的真实差距
我做过一个工单分类项目，原型阶段只用一个提示词加函数调用，模型表现好得惊人——用户发一句“帮我查一下订单状态”，它就能调用查询接口，把结果整理成自然语言返回。演示很顺畅，团队气氛也很乐观。等真正接入客服系统之后，问题接踵而至：用户在对话中间临时改主意，模型还在按旧任务执行；查询接口超时，模型只能对着错误信息编答案；多轮对话累积下来，关键字段被挤出了上下文窗口。
这些问题的共同点在于，单个模型调用都是成功的，失败的却是整个任务链路。应该说，demo 验证的是模型的单点推理能力，生产环境验证的则是系统在不确定性下持续收敛的能力。这也是 CS329Z 第五讲给我的最大冲击：大模型只是智能体的推理内核，智能体对外表现出的能力上限，取决于围绕内核构建的控制系统。模型当然要选好的，但真正拉开差距的是状态管理、工具设计、规划机制和容错策略。
1.2 智能体必须自带的四个基本构件
课程把智能体的基础能力拆成四块：状态、工具、规划、记忆。我在工程里越做越觉得这四项就是智能体的“基础设施”。
- 状态。很多人把状态等同于对话历史，其实不完整。真正有用的状态要包含当前任务目标、已完成步骤、中间结果缓存、环境约束。比如一个能自己写代码并运行的智能体，它必须记住代码版本、运行日志、错误输出，而不只是用户说过什么。状态设计不清楚，后面所有逻辑都跟着乱。
- 工具。工具是模型与外部世界交互的接口，相当于智能体的手脚。工具设计的原则是窄接口、明确入参、稳定返回。一个理想的工具函数，入参不超过三四个字段，返回值格式固定，错误返回能被程序识别而不是一段自然语言。工具越“钝”，模型越容易用对。
- 规划。规划负责把目标拆成可执行步骤。这里有个关键认知：规划不能是一次性的，因为执行过程几乎总会遇到计划外的情况。更可靠的设计是“计划加阶段性重规划”，每执行几步就检查一次进度，发现偏差立即重新规划。
- 记忆。短期记忆就是上下文窗口，长期记忆则需要外部存储。记忆不是越大越好，写入与检索都要有控制。我踩过的坑就是什么历史信息都往上下文里塞，结果关键信息被无关内容淹没，模型反而答非所问。
用生活化的类比来说：大模型像一位能力很强的演员，但这台戏能不能顺利演完，还要看剧本、舞台调度和道具系统。演员可以出彩，剧本逻辑混乱照样翻车。
1.3 为什么要把“框架”单独拎出来讲
框架本质上是把上述四项固化为代码结构。没有框架时，每个项目都要重新发明状态管理和循环调度；有了框架，团队可以在同一套约定上协作。但框架也意味着约束——约束了执行顺序、状态读写方式、工具注册方式。约束在哪，自由就在哪。
课程里反复强调一个观点：先理解你要约束什么，再选或写框架，而不是反过来被框架塑造。很多人一上来先选一个看起来很全能的框架，然后把业务往框架里塞，最后发现框架的抽象和业务模型对不上，改起来比从零写还痛苦。我自己早期就犯过这个错，后面会专门讲怎么避免。
2. 框架到底在框架什么：从模型调用循环到工具编排
2.1 Agent Loop 是一切智能体的骨架
不管多复杂的框架，底层都有一个最基本的循环：让模型观察当前状态，决定下一步动作，执行动作，把结果写回状态，重复直到任务结束。用一个极简伪代码表示：
while not done: messages = state.to_messages() # 组装当前上下文 response = model.chat(messages) # 模型推理 action = parse_action(response) # 解析模型输出 if action.type == "call_tool": result = execute_tool(action) # 执行工具 state.add_tool_result(result) # 结果写回状态 elif action.type == "final_answer": done = True每一行都有它的含义。组装上下文是在确定状态视角；模型推理是利用大模型的泛化能力做决策；解析输出是在把模型自然语言转成程序可执行的结构化指令；执行工具是模型影响外部世界的唯一途径；结果写回状态则是让下一个循环回合能感知刚发生的事。
所谓框架，大多是在这个循环之上叠加了状态持久化、并发调度、人工审批、可观测性、断点恢复这些工程能力。所以看一个框架，不用急着看它宣传了多少功能，先看它把 Agent Loop 放在哪儿、怎么让你干预循环的每一步。
2.2 框架抽象的三个层次
我把智能体框架粗略分成三个层次，选型时可以对照自己的需求：
| 层次 | 典型形态 | 控制力 | 上手成本 | 调试难度 | 适合场景 |
|---|---|---|---|---|---|
| 徒手循环 | while 加本地字典 | 最高 | 低 | 低 | 单智能体、轻量流程、快速验证 |
| 图编排框架 | 状态图加节点加边 | 中高 | 中 | 中高 | 多步骤分支、人工审批、状态恢复 |
| 长时工作流 | 任务队列加异步执行 | 中 | 高 | 高 | 多智能体大规模任务、长时间运行 |
图编排框架的卖点是可视化控制流，能清楚看到节点之间的依赖。但它也把控制流搬到了图形配置里，出了问题除了看代码还要理解框架的执行引擎。长时工作流更适合把智能体任务当成一种服务：提交任务、挂起、恢复、重试，它可以做得非常稳定，但学习成本也最高。
2.3 抽象越高的框架，越容易把问题藏起来
框架替你管理状态机，也意味着状态机的异常更难暴露。我遇到过一个很典型的故障：智能体在某个分支出错后，框架基于持久化快照把它恢复到了很早之前的状态，用户以为对话丢了，其实是恢复点选错了。原因就是框架的持久化逻辑和业务事务不在同一个层级。
所以无论你用哪个层次的框架，我都强烈建议保留一个能看到“模型输入输出、工具输入输出、关键状态字段”的调试视图。这个视图比任何高级功能都重要，它决定了你排查问题是靠证据还是靠猜。
3. 五种智能体架构模式与选型逻辑
3.1 Router 模式：先分类，再走专用通道
Router 的思路很朴素：先用一次模型调用对输入分类，然后分派给多个专用子流程。客服工单分派是典型场景——用户消息进来，先判断是订单问题、售后问题还是账号问题，然后进入各自处理通道。
这种模式的好处是每条通道的逻辑最简单，便于单独优化和测试。风险也很明显：分类一旦出错，后续全盘皆错。所以在 Router 后面一定要设计兜底通道，比如“无法确定分类时进入人工处理”，而不是让模型硬选一个。
我的实践体会是，Router 是最适合起步的模式。哪怕你最终要做的是复杂智能体，也可以先把主流程切成几个路由分支，让每个分支内部只做一件事。
3.2 Tool-Caller 模式：让模型自己决定调用哪个工具
Tool-Caller 是目前大模型应用最常见的形态，本质是把工具列表交给模型，模型基于用户意图选择工具并给出参数。工具协议里最关键的是描述字段，它决定模型能不能选对。举个例子：
{ "name": "query_order_status", "description": "查询订单当前状态。当用户询问订单、物流、签收情况时使用。", "parameters": { "order_id": { "type": "string", "description": "订单号，通常以字母开头" } } }注意，这个描述写的是“什么时候用”，而不只是“这个工具是什么”。这才是工具描述的正确写法。我会在审核每个工具时专门检查这一点：如果描述里没有触发条件，模型大概率会在不该用的时候乱用。
Tool-Caller 的失败模式很常见：选错工具、参数缺字段、参数类型不对。所以不能只靠模型自觉，要在工具执行前加一个参数校验层，把模型输出的参数用 JSON Schema 校验一遍，不合法就回退给模型重新生成。
3.3 Planner 模式：先定计划，再分步执行
Planner 模式先让模型生成完整的任务计划，然后逐步执行。课程里把它和逐轮推理型方式做了区分：后者是边想边做，每一步都依赖上一步结果；Planner 是先形成整体计划，把计划当成可审计的中间产物。
适合 Planner 的任务，通常是目标明确、步骤之间依赖清晰的场景。比如生成一份市场周报，计划可以拆成：收集销售数据、收集活动数据、汇总对比、生成结论。每一步都可以独立验证。模型输出的计划通常是一个 JSON 数组，类似：
{ "goal": "生成一周市场周报", "steps": [ {"step": 1, "action": "collect_sales_data"}, {"step": 2, "action": "collect_campaign_data"}, {"step": 3, "action": "summarize_report", "depends_on": [1, 2]} ] }这个模式的风险是计划质量直接影响执行质量——计划本身可能不合理。我一般在 Planner 外加一个“计划校验”节点，让另一个模型调用或规则引擎检查计划步骤是否完整、依赖是否有环。
3.4 Reflection 模式：生成之后，自我审视一遍
Reflection 模式是让智能体在生成初稿后，以审稿人身份重新审视自己的输出，找出问题再重写。典型提示词结构是：第一轮“请生成初稿”，第二轮“你是一名挑剔的审稿人，请指出上一版答案中的事实错误、逻辑漏洞和表达冗余，逐条列出，不要修改”，第三轮“根据审稿意见重写”。
写作、翻译、代码修补场景用 Reflection，效果很直观。但我必须提醒：代价是模型调用次数翻倍甚至翻三倍，延迟和成本都上去了。Reflection 不是越大越好，很多简单任务第一轮就够用。我的做法是，先跑一遍不带 Reflection 的版本，把错误的输出积累下来，再判断哪些错误类型值得用 Reflection 去修。
3.5 Multi-Agent 协作：多个角色，各司其职
多智能体协作是把任务拆给多个角色，比如一个负责信息收集，一个负责分析，一个负责写作。协作方式常见有三种：分层式（主智能体指挥子智能体）、黑板式（共享状态池，各智能体往里面写）、流水线式（前一个输出作为后一个输入）。
关于多智能体，我的态度比较保守。只有当任务确实需要不同视角，或者可以并行执行互不依赖的子任务时，才值得引入。如果只是把串行步骤包装成多个智能体，那得到的基本就是更贵的串行调用。课程里也提到，多智能体的额外成本很大一部分来自通信协议和调试复杂度，收益不明确时不要硬上。
3.6 模式组合与选择逻辑
这几种模式不是互斥的。一个真实系统往往是 Router 打底，某个分支里用 Tool-Caller，另一些分支用 Planner，再配合局部的 Reflection。选择逻辑应该回到任务本身：输入变化大不大、步骤依赖强不强、错误容忍度多高。
| 模式 | 核心优势 | 主要风险 | 首选场景 |
|---|---|---|---|
| Router | 简单可控、通道隔离 | 分类错误难挽回 | 意图分派、入口兜底 |
| Tool-Caller | 灵活、贴近自然交互 | 选错工具、参数不齐 | 查询类、操作类任务 |
| Planner | 步骤清晰、可审计 | 计划质量难保证 | 多阶段报告、流程类任务 |
| Reflection | 输出质量明显提升 | 成本高、延迟翻倍 | 写作、翻译、代码修正 |
| Multi-Agent | 并行、视角多样 | 通信和调试成本高 | 大任务并行拆解 |
4. 可靠性工程：把智能体从“能跑”变成“能上线”
4.1 评估体系才是智能体工程的门槛
很多团队对智能体没有评估体系，只靠“看起来效果不错”的感觉。这在 demo 阶段没问题，在迭代阶段就是灾难——你改了一个提示词，根本不知道是变好了还是变坏了。
课程里推荐的思路是分层评估。底层是模块级测试：检查工具是否在正确时机被调用、参数是否正确；上层是端到端任务测试：构造一个黄金测试集，比如几十条覆盖典型任务和错误模式的案例，每次改动都跑一遍。指标至少包括任务完成率、平均步数、工具调用准确率、token 消耗。
我自己的经验是，黄金测试集不用很多，三五十条就够用，但必须包含容易出错的边界情况，比如用户短时间内频繁改需求、工具返回超时、模型输出不合法 JSON。没有这些边界样本，评估结果会很失真。
4.2 可观测性：完整的 trace 是排查故障的唯一证据
智能体系统的故障链路长，传统后端日志根本不够。你需要记录每一个循环回合的完整信息：发送给模型的 messages、模型返回内容、解析后的动作、工具入参、工具出参、状态变化前后快照，并且用同一个 trace id 串起来。
真出问题时，第一条建议永远是“先看 trace，不要猜”。我之前排查过一个问题：模型在同一轮里连续调用同一个工具造成了副作用重复执行。单看日志几乎无解，但把完整的 trace 拉出来，立刻看到是解析器把模型输出中的同一条工具调用解析成了两次。如果没有 trace，这种问题可能要排查两天。
4.3 防御式设计：把模型当作能力很强但纪律很差的实习生
对模型输出的信任要分级。凡是外部可见的操作，比如发消息、改配置、扣款，都应默认不可信，执行前校验参数、确认权限、必要时加人工审批。模型输出 JSON 不合法是家常便饭，处理办法有两个方向：一是在提示词里强制输出 JSON，并用解析器做容错；二是在工具调用层做 schema 校验，不通过就要求模型重新生成。
工具执行也不总是成功的。要给每个工具定义超时时间和错误返回格式。工具失败时，应该让智能体收到结构化错误信息，然后决定是重试、换工具还是直接告知用户，而不是把一段堆栈文本丢回模型让它“自由发挥”。
4.4 成本与延迟：调用次数才是隐形杀手
一次看起来流畅的智能体任务，背后可能是五到十次模型调用。延迟和成本是线性累加的，所以设计上要时刻数着调用次数。课程里提到几个优化方向：用更短的上下文减少输入 token，把历史信息压缩成滚动摘要；做任务分级，简单请求走廉价小模型，复杂任务才上大模型；缓存重复的子任务结果，避免同一工具反复调用。
我补充一个细节：工具返回结果写入上下文前要做裁剪。一个查询接口可能返回几百行原始数据，但模型只需要其中三个字段。我会在后处理阶段把工具结果压缩成摘要再放回上下文，这既能省 token，也能降低模型注意力被无关信息分散的概率。
5. 从零搭建一个半结构化智能体的实操路线
5.1 先徒手实现一个最小可运行循环
在决定用任何框架之前，我建议先徒手写一个最小循环。这是理解智能体原理最有效的路径，也方便后续判断框架到底帮你做了哪些事。一个极简实现大概长这样：
import json class Agent: def __init__(self, model): self.model = model self.state = {"messages": [], "tool_results": {}} self.tools = {} def register_tool(self, name, fn, schema): self.tools[name] = {"fn": fn, "schema": schema} def run(self, user_input): self.state["messages"].append({"role": "user", "content": user_input}) while True: response = self.model.chat(self.state["messages"]) action = json.loads(response) if action["type"] == "final_answer": return action["content"] elif action["type"] == "call_tool": tool = self.tools[action["name"]] result = tool["fn"](**action["args"]) self.state["messages"].append( {"role": "tool", "content": json.dumps(result)} )这个版本当然很粗糙，但它的价值在于透明。每一步都看得见，状态就在眼前。跑通这个之后，你会自然意识到缺什么：没有参数校验、没有重试、没有持久化、没有人工审批。这些缺口恰好就是对照取用框架功能的清单。
5.2 什么情况下真的值得引入框架
按我的判断标准，出现以下条件之一，就可以认真评估框架了：需要把智能体状态持久化到数据库并在进程重启后恢复；需要支持人工审核节点，任务执行到某一步要停下来等人确认；需要多个智能体并发协作，且要统一管理生命周期；团队里有多个人同时开发不同智能体，需要公共的约定层。
反过来，如果只是一个内部工具型智能体，流程固定，输入输出简单，用徒手循环完全够。框架不是越多越好，引入框架带进来的概念和配置都是你需要维护的负担。
5.3 轻量框架设计中的关键决策点
即使决定自己搭一个轻量框架，也有几个关键决策需要提前定：
- 状态存储。简单的用 JSON 文件，正式的用数据库。要考虑版本迁移，因为状态结构一定会随着迭代变化。
- 工具注册。每个工具需要有名字、描述、入参 schema、执行函数、超时时间、错误处理策略。把工具元数据和实现绑定，便于模型调用时自动生成协议。
- 模型调用封装。所有模型请求走同一个封装层，统一处理超时、重试、限流、日志。这个封装层是加 tracing 的最佳位置。
- 人工审批。设计一个审批事件，智能体执行到高风险的 action 时，不是直接执行，而是生成一个 pending 事件挂起，等外部确认后继续。
这些决策点其实就是框架形态的雏形。你每解决一个问题，就是在往框架里加一块能力。
5.4 选型检查清单与团队落地建议
如果决定用现成框架，我建议按这个清单去评估：
- 状态持久化和断点恢复是否原生支持，还是需要自己实现。
- 是否提供可插入的评估钩子，能不能在每一步拿到完整 trace。
- 工具 schema 校验机制是否完善，参数校验是框架做还是工具自己负责。
- 是否支持人工审批节点，是否支持挂起和恢复。
- 团队技术栈是否匹配，遇到问题时社区能否提供有效参考。
团队落地最稳妥的路径，是先定评估标准，再选框架，先做一个最小闭环上线。不要一上来追求复杂架构，把最小可用的智能体跑通、埋好 trace、建立回归测试，再逐步加 Router、Planner、Reflection 这些模式。
我在实际项目里越来越体会到，框架与智能体设计的本质，是回答“可控性和智能之间的平衡怎么打”。越复杂的框架，约束能力越强，但也要求你对执行细节理解得越深。最可靠的设计不一定是最智能的，而是循环更小、观察点更多、每一步都能被验证的方案。
最后分享一个个人习惯：无论用什么框架，我都会在项目里保留一个“裸循环”版本的脚本，用来验证新思路。很多看起来像框架问题的问题，最后都证明是我对底层循环理解不够。先把循环吃透，再去谈框架，这条路不会错。
