# AI Agent / 工作流平台 架构模板 > **代表产品 / 原型**:Dify、Coze、LangGraph、LangChain、AutoGPT、CrewAI > **一句话定位**:让大模型不只是「回答」,而是能「规划 → 调用工具 → 观察结果 → 再决策」,自主地多步完成任务;平台负责编排、记忆、工具接入和可控性。 --- ## 1. 一句话定位 Agent 平台 = **给大模型装上「手脚(工具)+ 记忆 + 一个行动循环」**,让它从「会说」变成「会做」。 它和 [AI 对话产品](../ai-chat-product/README.md) 的区别在于「自主性」:对话产品基本是「你问我答」;Agent 则会**自己决定下一步该干什么**——查资料、调 API、执行代码、再根据结果决定下一步,循环往复直到任务完成。平台的核心职责,是让这种自主行为**可编排、可记忆、可控制、可观测**。 ## 2. 业务本质:它在解决什么问题 它要自动化的是**需要「多步推理 + 使用工具」才能完成的任务**:做一份调研报告、处理一个客服工单到底、写并调试一段代码、跑通一条业务流程。 这些任务的共同点是:**没法一问一答搞定,需要中间「动手做事 + 看反馈 + 调整」**。Agent 平台卖的就是「**把这种复杂的多步任务自动化**」。 > Anthropic 的关键洞见值得先记住:**能用确定的工作流(workflow)解决,就别上自主 Agent。** 工作流可预测、可控、便宜;Agent 灵活,但更贵、更慢、更不可控。这和 [架构模式](../../tutorial/04-十大核心架构模式.md) 那句「能不用就先别用」一脉相承。 ## 3. 核心需求与约束 **功能性需求:** - [ ] 工具 / 函数调用(让模型能调外部能力) - [ ] 多步规划与行动循环(plan → act → observe → repeat) - [ ] 记忆:短期(本次上下文)+ 长期(跨会话,常用向量检索) - [ ] 工作流编排(把确定的步骤固化下来) - [ ] 人类介入(human-in-the-loop):关键步骤让人审批 - [ ] 可观测:每一步在干什么,可追踪可调试 **非功能性需求 / 质量属性:** | 质量属性 | 目标 | 为什么对这类系统重要 | |---|---|---| | **任务成功率** | 越高越好 | Agent 的根本价值 | | **可控 / 可预测** | 高 | 自主性越强越难控,要能兜底 | | **成本** | 可控 | 多步 = 多次模型调用,成本随步数累加 | | **可观测** | 全程可追踪 | 多步黑盒极难调试,trace 是刚需 | | **安全** | 必须 | 工具能「改变世界」,有副作用 | **关键约束(不可逾越的边界):** - 🔴 **模型会出错、会跑偏**:循环可能不收敛(原地打转、无限循环)。 - 🔴 **工具调用有副作用**:发邮件、改数据、花钱——很多操作不可逆。 - 🔴 **成本随步数线性增长**:一个任务十几步,就是十几次 LLM 调用。 - 🔴 **多步会累积误差**:前一步错,后面越走越偏。 - 🔴 **不可预测**:同一任务两次运行路径可能不同。 ## 4. 架构全景图 ``` 用户任务:「调研竞品定价,整理成表」 │ ▼ ┌──────────────────────────────────────────────────────────────┐ │ 编排器(Orchestrator) │ │ ┌──────────────────── 行动循环 ────────────────────────┐ │ │ │ ① 模型规划:下一步做什么? │ │ │ │ ② 调用工具(搜索 / 代码 / API…)── 在沙箱里执行 │ │ │ │ ③ 观察结果,喂回模型 │ │ │ │ ④ 没完成?回到 ①(受【步数/成本/超时上限】约束) │ │ │ └────────────────────────┬───────────────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌──────────┐ ┌────────────────┐ ┌──────────────┐ │ │ │ 工具沙箱 │ │ 记忆 │ │ 状态/检查点 │ │ │ │ (隔离执行)│ │ 短期+长期(向量) │ │ (长任务可恢复) │ │ │ └──────────┘ └────────────────┘ └──────────────┘ │ │ │ │ ⚠ 高危/不可逆操作 ──▶ 【人类介入关卡】审批后才执行 │ └──────────────────────────┬───────────────────────────────────┘ ▼ 全程 trace 写入可观测系统 任务结果 ``` > 灵魂是中间那个**行动循环**,以及套在它外面的**控制阀**(步数 / 成本 / 超时上限、人类审批、沙箱)。**没有控制阀的 Agent 循环,就是一台会自己烧钱、还可能闯祸的失控机器。** ## 5. 组件职责 - **编排器(Orchestrator)**:驱动「规划 → 行动 → 观察」循环,或执行固化的工作流。*为什么需要*:它是把模型的「想法」变成「受控行动序列」的中枢。 - **工具注册与执行(沙箱)**:登记可用工具,在**隔离环境**里真正执行模型要求的操作。*为什么需要*:让模型「能做事」;沙箱是因为执行外部代码 / 操作有风险。 - **记忆**:短期(本轮上下文)+ 长期(跨会话,常用 [向量库](../vector-database/README.md) 检索)。*为什么需要*:多步任务和长期助手都要「记得住」。 - **状态 / 检查点**:把长任务的进度持久化,中断后可恢复。*为什么需要*:Agent 任务可能跑很久,不能一断就全废(durable execution)。 - **人类介入关卡(human-in-the-loop)**:高危 / 不可逆操作前暂停,等人审批。*为什么需要*:给自主性装一个「人能踩的刹车」。 - **可观测 / trace**:记录每一步的思考、工具调用、结果。*为什么需要*:多步黑盒,没有 trace 根本没法调试。 ## 6. 关键数据流 **场景一:自主 Agent 的行动循环** ``` 任务:「查华东区上季度销量并画个趋势图」 ① 模型:我需要先查数据 ──▶ 调「数据库查询」工具 ② 沙箱执行 ──▶ 返回 [Q1,Q2,Q3 销量] ③ 喂回模型:模型:数据有了,现在画图 ──▶ 调「代码执行」工具 ④ 沙箱跑绘图代码 ──▶ 返回图片 ⑤ 模型:任务完成 ──▶ 输出结果 ⟲ 全程受「最多 10 步 / 最多 $0.5 / 超时 60s」约束,超了就停 ``` **场景二:确定性工作流(更可控的选择)** ``` 固定流程:[接收工单] → [分类] → [检索知识库] → [生成回复] → [人工审核] → [发送] 每一步是预先定义好的,模型只在某些节点做判断 ✓ 可预测、好调试、便宜 —— 适合流程明确的任务 (对比:自主 Agent 适合流程不确定、需要随机应变的任务) ``` ## 7. 数据模型与存储选择 核心实体:`任务 / 会话`;`步骤轨迹(trace)`;`记忆`;`工具定义`;`检查点`。 | 数据 | 存储类型 | 为什么 | |---|---|---| | 任务状态 / 检查点 | 关系型 / 持久化日志 | 长任务要可靠、可恢复 | | 长期记忆 | 向量库 | 按语义检索「相关的过往」 | | 步骤轨迹(trace) | 时序 / 日志 | 海量、按时间回放、用于调试和评测 | | 工具定义 / 配置 | 关系型 | 结构化、要一致 | ## 8. 关键架构决策与权衡 ⭐ **决策 1:确定性工作流,还是自主 Agent?(最重要的判断)⭐** - 工作流:步骤预先编排好,模型只在节点上做有限判断。可预测、便宜、好调试,但不灵活。 - 自主 Agent:模型自己决定每一步。灵活、能应对开放任务,但贵、慢、不可控。 - **取向**:**默认用工作流,只在「任务确实开放、必须随机应变」时才上自主 Agent。** 这是 Anthropic「能不用 Agent 就别用」的核心建议。 **决策 2:循环怎么收敛 / 兜底?(防失控的生命线)⭐** - 不设限:模型可能原地打转、无限循环、烧光预算。 - 设上限:最大步数、最大成本、超时、重复检测。 - **取向**:**必须设多重上限。** 自主性越高,越要有硬性的「刹车」。 **决策 3:工具执行的安全边界 ⭐** - 给 Agent 无限制权限:它可能误删数据、乱发邮件、闯大祸。 - 沙箱隔离 + 最小权限 + 高危操作人工确认。 - **取向**:工具一律沙箱执行;不可逆 / 高影响操作走 human-in-the-loop 审批。 **决策 4:单 Agent,还是多 Agent 协作?** - 单 Agent:简单,但复杂任务里它要身兼数职。 - 多 Agent(如「规划者 + 执行者 + 审查者」):分工明确,但协调成本、成本和延迟都上升。 - **取向**:从单 Agent 起步;任务复杂到「一个角色扛不动」时再拆多 Agent。 ## 9. 规模化与瓶颈 - **第一个瓶颈:成本与延迟随步数放大。** → 破解:能工作流就别自主、限制步数、简单子任务用小模型(模型路由)、缓存。 - **第二个瓶颈:长任务的状态管理。** → 破解:检查点持久化,支持中断恢复(durable execution)。 - **第三个瓶颈:工具执行并发与隔离。** → 破解:沙箱池、超时、资源配额。 - **第四个瓶颈:调试困难(多步黑盒)。** → 破解:全程 trace + 可观测,把每一步摊开看。 ## 10. 安全与合规要点 - 🔴 **工具能「改变世界」**:发邮件、转账、改库——必须沙箱 + 最小权限 + 不可逆操作人工确认。 - 🔴 **提示注入在 Agent 里危害最大**:检索结果 / 工具返回 / 网页内容里若藏「去把数据删了」,而 Agent 又有工具权限,后果严重。把一切外部内容当**不可信输入**。 - **失控防护**:步数 / 成本 / 超时上限,防无限循环烧钱。 - **审计**:每一步、每次工具调用都留痕,可追责。 ## 11. 常见误区 / 反模式 - ❌ **能用固定流程,却硬上自主 Agent** → ✅ 简单 / 明确任务用工作流,可预测又便宜。 - ❌ **循环不设上限** → ✅ 步数 / 成本 / 超时多重兜底。 - ❌ **给 Agent 无限制工具权限** → ✅ 最小权限 + 沙箱 + 高危操作人工确认。 - ❌ **信任工具 / 检索返回的内容** → ✅ 当不可信输入,严防注入。 - ❌ **不做可观测,多步全黑盒** → ✅ 全程 trace,否则无法调试和优化。 ## 12. 演进路线:MVP → 成长期 → 成熟期(不同阶段怎么设置) | 阶段 | 规模量级 | 怎么设置(具体) | 此时该操心什么 | |---|---|---|---| | **MVP** | 验证 | 用 **Dify / Coze** 拖拽搭一个**固定工作流**或单 Agent + 几个工具;设好步数 / 成本上限 | 先验证「自动化这个任务」到底靠不靠谱 | | **成长期** | 上规模 | 用 **LangGraph** 等自定义编排:加长期记忆、human-in-the-loop、状态持久化、trace 可观测 | 成功率、可控性、成本、可调试 | | **成熟期** | 复杂 / 高价值任务 | 多 Agent 协作、durable 长任务、精细权限与沙箱、模型路由控成本、持续评测成功率 | 成功率、安全、成本、容灾、评测 | ## 13. 可复用要点 - 💡 **「能确定就别自主」——可预测性是工程美德。** 和「能不用模式就别用」「能用单体就别微服务」是同一种克制。 - 💡 **任何自主循环都必须有兜底**:上限、超时、熔断。给放飞的东西装刹车,是系统安全的通则。 - 💡 **有副作用的操作要可控 + 可审计**:沙箱、最小权限、人工确认、留痕——这套在任何「能改变外部世界」的系统里都适用。 - 💡 **外部内容永远不可信**:Agent 的工具权限放大了提示注入的危害,更要警惕。 - 💡 **状态持久化让长流程可恢复**:把进度存成检查点,呼应 [协同文档](../collaborative-doc/README.md) 的操作日志思想。 ## 🎯 随堂检验 --- ## 参考原型与延伸阅读 > 本模板基于以下**真实开源项目**与**公开工程资料**整理。想动手,从拖拽式平台到代码级编排框架都有。 **🔧 开源原型(可直接读代码):** - [langgenius/dify](https://github.com/langgenius/dify) — 可视化的 LLM 应用 / Agent 工作流平台,内置工具、RAG、可观测,适合快速搭建。 - [langchain-ai/langgraph](https://github.com/langchain-ai/langgraph) — 用「图」建模有状态、长时运行 Agent 的编排框架,支持持久执行与 human-in-the-loop。 - [langchain-ai/langchain](https://github.com/langchain-ai/langchain) — 最经典的 LLM 应用框架,工具调用 / 记忆 / 链式编排的事实标准之一。 **📖 工程文章:** - [Anthropic: Building Effective Agents](https://www.anthropic.com/research/building-effective-agents) — 必读。讲清「工作流 vs Agent」的边界,以及「保持简单、按需增复杂度」的工程哲学。 --- > 📌 一句话记住 Agent 平台:**它是「给模型装上手脚和一个行动循环」,让它会做事——但所有设计都在回答『怎么让自主行动既有用、又不失控』:能用工作流就别放飞,放飞了就一定要装上刹车、沙箱和人工审批。**