1. 项目背景某电商平台日均产生 300 售后工单客服团队 25 人仍处理不过来。CTO 要求技术团队用 CrewAI 搭建智能售后处理中心目标是将 60% 的常见工单退款、换货、物流查询自动化处理。技术负责人老张接手后陷入了分析瘫痪售后流程太复杂了——退款分已发货未签收“已签收有质量问题”“7天无理由三种子场景换货涉及库存在途判断投诉又分物流投诉”“商品质量投诉”“服务态度投诉”。每个分支的处理逻辑、所需 Tool、审批节点都不一样。老张花了两周画流程图、做需求评审最后发现一个根本问题流程图 ≠ Agent 架构图。能画清先做什么后做什么只是第一步——你还需要决定哪些步骤交给 Agent 推理、哪些用确定性代码控制、哪些 Agent 参与、哪些用 Tool 辅助、异常路径怎么兜底。这就是业务建模的核心把业务需求翻译成 CrewAI 的 Agent/Task/Tool/Flow 四要素组合。本章的目标是建立一套从业务需求到 CrewAI 架构的系统建模方法——包括方案对比、边界划分和 ADR技术决策记录的写法。2. 项目设计小胖抱着一袋薯片“大师我有个疑问。售后处理这种复杂流程为什么不全部用 Flow 控制Flow 不是专门做分支路由的吗”大师“全部用 Flow 当然可以——但你会写一个几百行的 if/elif/else把 Agent 退化成了’填空题工具’。你让 Agent 在退款判断里只写一段回复文案它的大模型推理能力完全浪费了。反过来全部交给 Agent 自己判断走哪个分支它又不可靠。所以关键是找到确定性和不确定性的边界。”小白翻开笔记本“那怎么判断一个决策点该给 Flow 还是该给 Agent”大师“我总结了三个判断标准。第一决策规则是否明确可编码——比如’退款金额500元需主管审批’这种规则写在代码里比让 Agent 自己猜更可靠。第二决策是否需要领域知识——比如’这个商品问题是否属于质量缺陷’这种需要 Agent 用它的知识来判断。第三决策是否涉及多个信息源的综合——比如’综合分析订单历史、商品信息和用户反馈来决定处理方案’这是 Agent 的强项。”小胖“那四种方案——单 Agent、多 Agent、Flow、传统代码——怎么选”大师“我画个决策矩阵。单 Agent任务简单且单一视角足够——比如’判断一封邮件是不是垃圾邮件’。多 Agent需要多视角交叉验证——比如’评审一个技术方案’。Flow需要确定性分支路由——比如’工单分拣路由到不同处理流程’。传统代码纯计算任务——比如’根据公式计算退款金额’。大部分真实项目是组合——Flow 做骨架关键节点嵌入 Crew。”小白“任务边界、上下文边界和工具边界这三个边界怎么定义”大师“任务边界——一个 Task 只产出一种明确的结构化输出如果你发现 expected_output 里列了 5 种不同类型的产物就该拆。上下文边界——一个 Task 的 context 列表不要超过 3 个前序 Task否则信息过载。工具边界——一个 Agent 最多挂 5 个 Tool且 Tool 之间功能不重叠以免模型选错。”小胖“那 ADR 怎么写我们团队从没写过。”大师“ADRArchitecture Decision Record记录的是’为什么做这个架构决策’而不是’架构长什么样’。格式很简单标题决策了什么、背景当时面临什么约束、决策选了哪个方案、后果这个决策带来了什么影响——好的和坏的都要写。比如一条 ADR‘决策用 FlowSequential Crew 而非纯 Hierarchical——因为售后流程有明确分支Hierarchical 的 Manager Agent 增加了成本且不带来决策多样性’。”技术映射总结业务建模 把业务流程图翻译成 CrewAI 四要素Agent/Task/Tool/Flow 明确边界 记录决策原因。模型的好坏不取决于 Agent/Task 的数量而取决于边界的清晰度——知道什么给机器、什么给人、什么给确定性代码。3. 项目实战3.1 实战目标为电商售后中心设计一套完整的 CrewAI 架构方案——包括架构图、Agent/Task/Tool 清单、Flow 设计、ADR 文档。3.2 业务需求梳理售后工单类型及处理流程工单入口 ├── 退款(refund) │ ├── 未发货自动退款 通知用户 │ ├── 已发货未签收拦截物流 退款 │ └── 已签收有质量问题需审核凭证 → 人工审批退款 ├── 换货(exchange) │ ├── 发错货/尺码不对确认库存 → 安排换货 │ └── 质量问题需审核 → 人工审批换货 ├── 投诉(complaint) │ ├── 服务态度核实 → 道歉补偿 │ └── 商品质量升级处理 → 质检介入 └── 物流查询(logistics) └── 查询物流状态 → 返回结果3.3 架构设计步骤1方案对比目标对四种架构方案做对比分析辅助决策。维度纯 Flow单 Agent多 Agent CrewFlow Crew推荐分支确定性高低中高文本理解质量低无 LLM中高高可维护性低长 if/else高中中高异常处理需硬编码不可靠不可靠确定性兜底Token 成本无中高中开发效率低高中中推荐Flow Crew 组合——Flow 负责确定性路由和外部交互Crew 负责各分支的智能处理。步骤2Agent 设计目标定义售后中心的所有 Agent 角色。# agents/__init__.py 中的 Agent 清单AGENT_DEFINITIONS{classifier:{role:售后工单分类员,goal:阅读工单内容将工单准确分为 refund/exchange/complaint/logistics 四类,backstory:你有3年客服工单分拣经验分类准确率98%。分类依据客户核心诉求——要退钱refund要换货exchange要投诉complaint查物流logistics。,tools:[],max_iter:5},refund_assessor:{role:退款审核员,goal:根据退款类型和订单状态判断退款是否合规并计算退款金额,backstory:你熟悉平台退款政策未发货→全额退已发货未签收→全额退(拦截物流)签收后质量问题→审核凭证后退款7天无理由→商品完好可退。超过500元的退款需标记为待主管审批。,tools:[OrderQueryTool,LogisticsQueryTool],max_iter:10},exchange_coordinator:{role:换货协调员,goal:判断换货可行性、确认库存、安排换货流程,backstory:你处理过上万单换货。流程确认问题归属→查库存→生成换货单→通知用户退货。如果库存不足给出替代方案换其他款式或退款。,tools:[InventoryCheckTool,OrderQueryTool],max_iter:10},complaint_handler:{role:投诉处理专员,goal:评估投诉严重程度给出安抚方案必要时升级处理,backstory:你处理过从快递延迟到食品安全各类投诉。评估三维度严重度(一般/严重/重大)、责任归属(我方/第三方/客户)、补偿尺度(道歉/优惠券/退款/赔偿)。重大投诉立即升级。,tools:[OrderQueryTool],max_iter:8},response_writer:{role:客服回复撰稿人,goal:基于处理结果生成专业、温暖、结构清晰的客户回复,backstory:你撰写了超过10000条客服回复。你的回复公式共情开头解决方案行动指引兜底承诺。你避免很抱歉给您带来不便这种模板化表达。,tools:[],max_iter:5}}步骤3Tool 设计目标定义售后中心所需的所有 Tool。# tools/__init__.py 中的 Tool 清单TOOL_DEFINITIONS{OrderQueryTool:{name:order_query,description:根据订单号查询订单详情包括商品信息、金额、当前状态、物流单号。当需要了解订单信息时调用。,input:{order_id:str - 订单号},output:JSON: {order_id, status, amount, product_name, logistics_id, buyer_name},security:只读操作不允许修改订单},LogisticsQueryTool:{name:logistics_query,description:根据物流单号查询配送状态和轨迹。当需要了解包裹位置时调用。,input:{tracking_number:str - 物流单号},output:JSON: {tracking_number, status, current_location, estimated_delivery, history},security:只读操作},InventoryCheckTool:{name:inventory_check,description:查询指定SKU的库存状态。当需要判断是否能换货时调用。,input:{sku:str - 商品SKU,warehouse:str (optional) - 仓库编码},output:JSON: {sku, available_quantity, warehouse},security:只读操作},RefundExecuteTool:{name:refund_execute,description:执行退款操作。当退款审核通过后调用触发实际退款流程。,input:{order_id:str,amount:float,reason:str},output:JSON: {refund_id, status, estimated_arrival},security:需要人工审批确认后才能调用(500元强制审批)}}步骤4Flow 总架构目标设计售后中心的 Flow 流程。# architecture/aftersale_flow.py (架构蓝图非完整代码) 售后中心 Flow 架构 ┌─────────────────────────────────────────────────────────┐ │ start: 工单接收 │ │ (接收工单ID/内容初始化状态) │ └──────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ classify: 工单分类 (Agent) │ │ 读取工单内容 → 输出: refund/exchange/... │ └──────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ router: 路由分发 │ │ if refund → handle_refund │ │ if exchange → handle_exchange │ │ if complaint → handle_complaint │ │ if logistics → handle_logistics │ └────┬──────────────┬──────────────┬──────────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌──────────┐ ┌──────────┐ │ refund │ │ exchange │ │complaint │ ... │ Crew │ │ Crew │ │ Crew │ └────┬────┘ └────┬─────┘ └────┬─────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────────────────────────────────────────────┐ │ 审批判断 (router) │ │ if 退款金额500 or 投诉等级严重: │ │ → human_review │ │ else: │ │ → generate_response │ └──────────────────────┬──────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ generate_response: 生成客户回复 │ │ (Agent: response_writer) │ └──────────────────────┬──────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────┐ │ save_and_notify: 保存通知 │ │ 更新工单状态 推送回复给用户 │ └─────────────────────────────────────────────────────────┘ 步骤5ADR 文档目标记录关键架构决策。# ADR-001: 选择 Flow Crew 而非纯 Hierarchical Crew ## 背景 售后中心有4种工单类型处理流程各异。需要决定用哪种 CrewAI 编排模式。 ## 决策 采用 Flow 总控 各分支 Sequential Crew 的架构。 - Flow 负责工单分类路由、审批判断、异常兜底 - Crew 负责各分支内部的智能处理审核→决策→回复 ## 备选方案 1. 纯 Hierarchical CrewManager Agent 动态分配但成本高(30%)且路由不可靠 2. 纯 Sequential Crew无法处理分支路由 ## 后果 - 正面路由确定性高各分支 Crew 可独立优化和测试 - 负面Flow Crew 嵌套增加代码复杂度需维护 Flow 状态和 Crew 状态的同步 - 风险Flow 中断时需设计断点恢复机制待后续版本迭代 # ADR-002: 退款金额500元必须人工审批 ## 背景 自动化退款存在资金风险——恶意退款、误判退款都可能导致直接经济损失。 ## 决策 退款金额阈值设为500元。≤500元自动退款500元进入人工审批队列。 ## 备选方案 1. 全部自动退款风险不可接受曾发生单笔2000元误退款 2. 全部人工审批失去自动化价值 ## 后果 - 正面约80%退款可自动化大部分≤500元20%高风险退款有人工把关 - 负面人工审批延迟平均15分钟需设计超时升级机制 - 阈值后续可通过数据分析动态调整3.4 完整建模清单建模要素售后中心实例建模原则业务角色 → Agent分类员/审核员/换货员/投诉员/回复员一个业务角色一个 Agent业务流程 → Flow分类→路由→处理→审批→回复条件分支用 Flow业务动作 → Tool查订单/查物流/查库存/执行退款外部交互用 Tool决策点 → routerGuardrail金额阈值审批、投诉升级判断可编码规则用代码异常路径 → 兜底人工无法分类→转人工、审批超时→升级异常交给确定性逻辑3.5 测试验证# test_modeling.pyimportpytestdeftest_agent_count():验证 Agent 设计无重复角色fromagentsimportAGENT_DEFINITIONS roles[a[role]forainAGENT_DEFINITIONS.values()]assertlen(roles)len(set(roles)),Agent 角色不应重复deftest_tool_security():验证 Tool 权限最小化——所有读操作为主fromtoolsimportTOOL_DEFINITIONSforname,toolinTOOL_DEFINITIONS.items():ifexecuteinname.lower()orwriteinname.lower():assert人工审批intool.get(security,),\f写操作 Tool {name} 缺少人工审批安全约束deftest_branch_coverage():验证所有 4 种工单类型都有对应处理分支workflow_branches[refund,exchange,complaint,logistics]# 每个分支应有对应的 Agent 定义branch_handlers{refund:refund_assessor,exchange:exchange_coordinator,complaint:complaint_handler,logistics:classifier# 物流查询简化处理}forbranchinworkflow_branches:assertbranchinbranch_handlers,f缺少分支:{branch}deftest_adr_has_required_sections():验证 ADR 包含必要章节required_sections[背景,决策,备选方案,后果]# 在实际项目中从 ADR 文件读取# 这里验证结构定义adr_template[背景,决策,备选方案,后果]assertall(sinadr_templateforsinrequired_sections)pytest test_modeling.py-v# 4 passed4. 项目总结4.1 优点与缺点维度系统建模后开发边写边改开发效率前期慢(1-2天建模)后期快前期快后期反复重构Agent 职责清晰度高建模阶段就明确了边界低写着写着就模糊了异常覆盖全面建模时已考虑异常路径遗漏常见团队沟通成本低有架构图和 ADR高口头对齐适应需求变更中低4.2 适用场景必须建模的场景3个以上 Agent 协作的复杂流程有明确条件分支的业务退款/换货/投诉跨团队协作需要架构图统一认知有合规和审计要求的场景预计长期维护和迭代的项目可简化建模的场景2个 Agent 以内的简单流水线原型验证阶段的快速试错4.3 注意事项先画流程图再画 Agent 图流程图画的是业务发生了什么Agent 图画的是谁用什么工具做了什么。两者是不同的视角。边界判断是第一优先级建模中最有价值的产出不是架构图本身而是什么给代码、什么给 Agent、什么给人的边界决策。ADR 要及时更新架构决策会随着业务演进而变化过期的 ADR 比没有 ADR 更危险误导新人。4.4 常见踩坑经验案例1建模太细导致无法启动开发现象架构师花了 3 周画了 50 页的详细设计开发团队还没开始写代码。根因混淆了架构建模和详细设计。架构建模定义边界和职责详细设计定义每个方法签名——后者应留给开发阶段。解决建模阶段只输出 Agent 清单含 role/goal、Task 清单含 expected_output 一句话、Flow 拓扑图和 2-3 条关键 ADR。案例2完全照搬组织结构设计 Agent现象公司有客服一部、二部、三部——于是在架构中照搬了三个 Agent 对应三个部门。根因组织结构和业务流程不是一一对应的。三个客服部门处理的是同一类事务。解决Agent 按业务能力分不按组织架构分。一个退款处理 Agent可以服务所有客服部门。案例3忽略了异常路径导致生产事故现象退款流程自动化上线后某笔退款因为第三方支付通道故障一直处于处理中用户等了一周。根因建模时只画了正常路径没考虑外部依赖失败的兜底方案。解决建模标准流程中增加异常泳道——每个外部调用都必须标注失败后的处理策略。4.5 思考题售后中心上线 3 个月后业务增加了一个新需求——“仅退款不退货”针对低价商品。这个需求是加一个新的 Agent、修改现有 Agent、还是新增一个 Flow 分支你的判断依据是什么你如何向一个没有技术背景的业务方客服主管解释为什么有些工单可以自动处理有些必须人工处理用什么类比和指标能让他们理解边界设计的逻辑答案将在后续章节揭晓。延伸阅读与资源10倍开发者的 Dify 魔法书从零构建全栈 AI 应用后端工程师转型AI第一课-Ollama 与私有化大模型实战大型语言模型(LLM) vLLM 高性能推理落地实战Agent开发之LlamaIndex 实战修炼与源码进阶大语言模型Transformers 实战修炼与源码剖析