声明：本文基于对开源 Agent 框架的实际部署调试与二次开发经验（脱敏），框架本身不构成推荐，重点在拆解方法与共性问题。
拆解对象与拆解方法
AI 专题的项目拆解，我坚持一个固定结构：项目背景 → 架构拆解 → 优点与短板 → 适用/不适用场景 → 部署踩坑 → 如果我重构。方法上只选实际跑过、部署过的项目；本文框架我部署过并做过企业场景的 POC。
架构拆解：一个 Agent 框架在做什么
剥开任何 Agent 框架，核心只有四件事：
- 编排模型（Orchestration）：ReAct 循环、Plan-and-Execute、多 Agent 协作图。这是框架的灵魂，决定了智能体的「思考方式」。
- 工具层（Tools）：把外部能力（搜索、代码执行、API）包装成 LLM 可调用的函数。工具的描述质量直接决定调用准确率。
- 状态管理：多轮对话的记忆、上下文窗口管理、中间步骤的持久化。
- 执行沙箱：代码生成后的执行环境、超时与权限隔离。
拆出来的三个真实短板
短板一：编排框架「全知全能」的错觉 框架宣传里的多 Agent 协作（规划者 + 执行者 + 审查者）看起来很酷，实际跑下来：多数任务单 Agent + 强工具描述就够了。多 Agent 的 token 开销成倍增长，协调失败率反而上升。拆解结论：编排复杂度要配得上任务复杂度，否则就是给演示稿交税。
短板二：上下文管理是隐藏的吞金兽 框架默认把对话历史全部塞进上下文，长会话 token 成本线性爆炸。拆解发现多数框架的「记忆」就是粗暴拼接——没有做摘要压缩与关键信息抽取。生产改造的第一优先级往往在这里，而不是模型。
短板三：Web 化部署的经典坑（CORS 与鉴权） 把 Agent 服务套一层 Web UI 给企业用，会遇到一套「教科书里没有」的问题：前端直连后端时的 CORS 配置、SSE 流式响应的代理超时、WebSocket 与长轮询的选型。很多 demo 死在「浏览器能跑但一上生产代理就断流」。
部署踩坑实录：一次 POC 中，SSE 流式输出经 Nginx 反向代理后 60 秒准时断开——默认 proxy_read_timeout 只有 60s，流式响应必须单独调大并关闭缓冲（proxy_buffering off）。这类坑与 AI 无关，但决定 AI 应用能不能上线。
适用 / 不适用场景（边界要说清）
适合：任务边界清晰、工具调用明确（查库存、生成报表、操作工单）的企业内流程自动化。
不适合：
- 需要高可靠长链路推理的严肃决策（如医疗建议、风控判定）——目前任何框架都给不了保证。
- 纯知识问答——RAG 比 Agent 便宜且稳定十倍，别为了「智能」上 Agent。
- 无工具、纯聊天——直接调 API 就行，框架是负资产。
如果我重构，我会怎么改
- 默认单 Agent，只在任务确实可分解、子任务可并行时启用多 Agent。
- 上下文做三层治理：最近轮次全量 + 历史摘要 + 关键事实抽取（存结构化记忆）。
- 工具层加 schema 校验与权限分级：不是所有工具对所有角色开放。
- 可观测性内建：每一步的 token、工具调用、延迟全记录——没有日志的 Agent 等于没有仪表盘的飞机。
- 成本护栏：每任务 token 预算 + 熔断。
拆解给你的建议（结论）
中小团队用 Agent 框架的正确姿势：不要部署框架全家桶，先画自己的任务流程图，再选最小可用的编排。框架是脚手架，业务是建筑——反过来就错了。
延伸阅读：AI 项目 POC 评估清单 · 续篇《Agent 应用开发：编排、提示工程、边界与降级》见 成长体系 AI 系列