前阵子 Anthropic 把电商 Agent 的架构思路和生产实践整理成了一份指南顺手还开源了 commerce-agents 这套参考实现。我第一时间把仓库拉下来跑了一遍又对着指南把架构文档啃了好几轮。说实话做 Agent 应用这么久市面上讲概念的多能真正把怎么设计、怎么落地、踩了哪些坑讲清楚的太少这份材料和代码值得电商技术团队、做 AI 客服/导购/运营自动化的同学以及所有准备把大模型 Agent 推向生产环境的人认真看一遍。这篇就按我自己的理解把架构思路、核心模块、参考实现的链路和生产化改造这几个部分拆开讲透。1. 项目背景电商 Agent 为什么需要一套专门架构1.1 电商场景的独特难点电商应该是 Agent 落地最难、也最值得做的场景之一。难点不在聊天而在办事。用户问这件衣服有 M 码吗看起来只是一个查询但背后要检索商品、核对库存、确认尺码表甚至要结合用户的尺码偏好和历史订单来判断用户说我要退掉昨天买的那个耳机这个操作会动到订单状态、触发退款流程、还要判断是否符合退货政策。每一步都牵涉真实业务系统和资金流转出错的代价比普通问答高得多。另一个难点是状态链特别长。一个完整的购物流程要从浏览、咨询、加购、下单、支付走到售后、退换、复购中间还可能插入优惠券、物流查询、发票申请这类分支。如果只是把 Prompt 写长一点、把所有工具塞给同一个 Agent上下文很容易被撑爆模型也容易在多个任务之间精神分裂——上一句还在查物流下一句就开始推优惠券了。还有一关是信任问题。电商 Agent 要代表商家直接面对消费者说错一句可以退货可能就带来实际赔付。所以在架构层面必须有护栏把 Agent 能做的事、不能做的事用系统方式框住而不是指望模型自己懂事。1.2 指南与开源仓库里到底有什么Anthropic 这次发布的电商 Agent 架构指南核心是把电商场景拆成了几个关键设计维度如何划定 Agent 的职责边界、如何设计工具层与业务系统对接、如何管理多轮对话的状态与记忆、如何在任务执行过程中加入人与系统的审批点以及如何用评测驱动 Agent 持续迭代。这套思路不是凭空想出来的更像是对过去一年大量 Agent 生产实践的提炼。commerce-agents 这个仓库就是把上述设计落到代码里的参考实现。它不是一个能直接上线的商城机器人而是一套可运行的骨架里面有按角色拆分的子 Agent、预置好的工具函数、模拟电商后端的内存数据层、以及完整的对话运行循环。你可以把它的目录结构当成教科书来读也可以直接 fork 掉把后端的 mock 接口换成你们公司真实的商品、订单、库存服务。2. 架构设计思路从聊天机器人到真正能办事的 Agent2.1 多 Agent 编排 vs 单 Agent 硬扛早期很多团队做 Agent 就是一个大模型 一堆函数调用认为只要工具定义得足够多模型就会自己选对。实际跑起来会发现当工具数量超过二三十个、业务规则互相交叉的时候单 Agent 的选择准确率会明显下降而且每轮都要把所有工具的 schema 塞进上下文token 消耗非常可观。commerce-agents 的参考实现采用的是多 Agent 编排先把电商业务拆成几个角色比如前台接待、售前导购、售后服务、订单顾问每个子 Agent 只负责自己的那摊事使用来自超时的小范围工具集。用户进来先经过一个轻量的入口调度层判断当前意图属于哪个角色再把对话转交给对应的子 Agent。这样做有三个明显的好处。第一是职责隔离售后 Agent 根本拿不到修改订单价格的工具即使模型被恶意提示词诱导也没有越权的路径。第二是上下文精简每个子 Agent 只需要关注自己领域内的系统提示词不需要背全站的业务规则。第三是独立演进导购 Agent 的 Prompt 改了售后 Agent 不受影响评测和灰度范围都能缩小。2.2 核心模块路由、工具、状态、护栏不管 Agent 拆得多细落到实现层面核心就四块。路由层解决这个用户到底要找谁。实现上可以采用快速分类模型、关键词规则或小模型的意图识别。参考实现里一般会用一次轻量的模型调用来完成分流把当前用户消息和一段简短的路由说明交给模型让它输出应该转交的子 Agent 名称。对于大多数电商场景这一步不需要用最强的模型用低成本模型就能达到很高的准确率成本控制就看这里。工具层是 Agent 的手脚。每个子 Agent 内部维护一组工具描述遵循 Anthropic 推荐的 tool calling 格式把 name、description、input_schema 写清楚。工具层之上还要包一层执行器负责把模型返回的工具调用请求真正发到业务系统然后把结构化结果回填给模型。这一步最容易忽略的是超时和错误信息的表达工具返回查询失败这种模糊文案模型很难判断下一步该做什么更好的做法是把异常结构化告诉模型失败原因和可用的替代路径。状态层管的是多轮记忆。电商对话是典型的长流程用户可能隔了几天回来继续问同一个订单。参考实现里会用消息历史加关键信息的持久化来维护状态比如一个会话对象里保存当前用户 ID、待处理的订单号、购物车 id。必要的时候做上下文压缩或摘要避免 token 无限膨胀。护栏层是电商 Agent 的底线。包括输入侧的敏感信息过滤、输出侧的合规检查、以及动作侧的审批机制。凡是对订单状态有修改、涉及退款、需要发券的操作都不能让模型直接执行而是通过一个require_confirmation之类的机制把决定权交还给用户或人工客服。这套设计在参考实现里有很清楚的演示。2.3 电商特有环节的抽象与建模电商的业务对象说白了就是商品、库存、购物车、订单、售后、优惠这几类。参考实现把这些对象封装成语义化工具模型的思维方式更接近人的工作方式先查商品再查库存然后加购最后 checkout。这一步抽象的价值在于它让模型面对的是业务动作而不是数据库字段准确率完全不一样。一个典型的例子是优惠计算。直接给模型一个计算优惠的工具里面传一堆 order_amount、discount_rate 参数模型很容易用错。参考实现更推荐的方式是提供获取当前用户可用优惠和应用优惠到购物车这类高内聚工具把复杂的业务规则藏在函数内部模型只需要做选择和确认。生产系统里的库存占用、价格锁定、支付单创建这类事务性操作也差不多是这个逻辑能封装成原子动作的就不要让模型去组合多个底层接口。3. 参考实现拆解commerce-agents 的核心链路3.1 代码库结构与启动流程把仓库克隆下来之后先看 README 和目录结构能明显感觉到它是按可运行 可替换的思路组织的。核心模块基本分为三块一是 subagents 定义每个子 Agent 有自己的系统提示词、工具列表和状态说明二是工具实现每个工具是一个 async 函数输入参数做严格校验返回结构化的 JSON三是运行时循环负责调用模型、解析 tool_use、执行工具、继续循环。启动流程值得说一下。项目不是简单地起一个聊天服务而是带着一套模拟数据启动的。仓库内置了 mock 的商品库、库存表、订单库和购物车存储目的就是让你在不依赖真实电商后端的情况下把整条 Agent 链路完整跑通。这个设计对学习非常友好你可以像本地调试普通后端服务一样给 Agent 喂消息看它一步步选择了什么工具、传了什么参数、拿到了什么结果。我实测跑下来最直观的感受是整个交互过程完全透明。日志里能看到每一轮模型返回的 tool_use 块、每个工具的执行耗时和返回结果。对于想理解 Agent 运行机制的人来说这种可观测性比任何架构图都管用。3.2 工具层商品检索、库存、购物车、订单参考实现里的工具设计可以当模板抄。以商品检索为例它提供的是search_products(query, category, page)这样的语义化接口模型不需要理解 SQL只要表达找一双黑色运动鞋即可。库存查询单独拆成check_stock(productId, skuId)避免模型把商品信息和库存信息混在一次调用里完成。购物车工具是我建议重点研究的部分。代码里把add_to_cart、remove_from_cart、view_cart拆成独立工具每个工具都要求明确指定商品和 SKU。这里有个细节值得注意工具参数里通常会要求模型的回复中包含确认性描述比如已经帮你把黑色 M 码加入购物车这样用户能感知到动作已完成体验上更踏实。订单类工具涉及的状态更多get_order_status要返回当前订单的物流轨迹、商品明细、售后入口create_return_request这类高风险操作在工具内部就嵌入了校验逻辑比如订单是否已签收、是否在退货期内、是否已申请过。这种把业务规则下沉到工具层的做法比在提示词里反复强调只有满足条件才能退货要可靠得多。3.3 关键实现细节与配置我读代码时注意到几处容易被忽略、但对生产很重要的实现细节。第一是工具描述的写法。参考实现里的工具 description 不是一句话带过而是写清楚了使用场景、参数限制、返回结构。比如库存工具会说明当用户询问多个商品时请逐个查询这种约束能明显减少模型在一次调用里塞入过多参数导致报错的情况。第二是错误信息的组织形式。工具执行失败时返回的不是一条英文报错而是结构化提示失败原因、当前已知信息、建议的替代操作。比如库存查询失败时回复里会带上该商品可能有货但当前无法确认建议稍后重试或联系人工。这是模型能否优雅应对异常的关键。第三是配置管理。参考实现把模型名称、温度、最大 token、工具执行超时、最大迭代轮数等参数集中放在配置里没有散落在代码各处。生产环境中这些参数都需要调拆出来是必须的。尤其是最大迭代轮数这个参数很多 Agent 陷入死循环的根因就是没有对它做限制一个 while 循环跑几十轮既费钱又卡体验。4. 生产化落地从 Demo 到线上要解决的事4.1 延迟与成本的取舍参考实现跑通很容易但上线最现实的问题就是延迟和成本。电商对话的黄金响应时间在 2 到 3 秒以内而多 Agent 编排天然会带来多次模型调用——路由一次、子 Agent 主循环里可能还有工具调用后的一次续跑每增加一次往返就增加几百毫秒到一两秒。我常用的优化套路是这样第一路由层或意图分类用最小模型Haiku 这类低成本模型完全够用第二商品检索、库存查询这些高频工具提前与模型无关地并行执行比如用户在输入框还在打字时系统已经把热门商品信息拉好了Agent 直接拿现成数据回答第三给工具执行结果做缓存同一天内相同 query 多次出现的概率不低把热数据缓存到 Redis 能省下一大笔 token第四对子 Agent 的提示词和工具描述做精简去掉不必要的长指令这能直接降低每次调用的输出长度和延迟。4.2 错误恢复与一致性代码可以跑一万遍不出错但只要有一次工具调用的参数格式不符合业务系统要求整轮对话就可能崩。生产环境必须把错误恢复当成一等公民对待。第一步是参数层面的兜底工具函数内部要写严格的参数校验模型传进来的字段缺失或类型不对时不要直接抛异常而是返回一个必填参数缺失的结构化错误让模型自己补全后重试。第二步是流程层面的兜底比如下单动作涉及创建订单、锁定库存、生成支付链接三个步骤其中任何一步失败都要有对应的回滚或补偿逻辑。参考实现里的 mock 把每步都做成独立函数就是提醒你按真实事务的标准来设计。第三步是对 Agent 的臆想做校验。模型在工具调用时可能会出现幻觉参数比如填入一个根本不存在的商品 ID。更稳的做法是在工具内部先把 ID 拿去做一次存在性校验如果不存在直接返回商品不存在的错误而不是把脏数据沿着链路往下传。实测下来这个校验能拦掉很多看起来莫名其妙的线上问题。4.3 安全、隐私与用户体验电商 Agent 的权限边界必须从架构上卡死。一句话总结就是Agent 能看的可以宽一点能改的一定要收敛。查询类工具可以开放给所有子 Agent但修改订单、退款、发放优惠、变更收货地址这类写操作要走统一的高风险动作通道先让模型生成一个待确认的操作摘要以卡片形式展示给用户用户明确确认后才真正执行。参考实现里的确认机制虽然演示的是用户确认但在企业场景里完全可以加一层人工客服审批。隐私方面要特别小心。电商对话里会大量出现用户姓名、电话、详细收货地址、支付信息。日志和模型上下文里尽量不要出现明文敏感字段可以用脱敏ID代替如果需要模型理解订单归属把用户身份放在会话上下文中由工具层鉴权后返回该用户是否有权访问这个订单而不是直接把所有订单数据一股脑塞给模型。还有一个经常被忽略的点是免责与兜底。Agent 回复中如果涉及退货政策、赔付标准最好让它基于最新政策文档回答而不是靠模型记忆。可以把政策条款作为检索增强内容放入上下文或者把政策判断做成一个独立的工具由业务系统返回标准口径最大程度减少政策解读偏差。5. 常见问题排查实录5.1 连接与鉴权问题跑 commerce-agents 或接入 Claude API 时最常见的报错集中在 API 连接和鉴权现场反馈基本都是调用失败但根因五花八门。我建议排查顺序是先确认 API Key 是否有效、是否有对应模型的访问权限再确认请求的模型名称是否与账号开通的模型一致最后确认网络策略很多公司内网会对出站请求做白名单限制生产环境的防火墙要提前把官方 API 域名加白否则线上突然大面积失败时再排查会很被动。这类问题的排查建议直接看接口返回的状态码和错误体通常一眼就能定位是 key 的问题、权限的问题还是配额的问题。官方 SDK 都有比较完整的错误处理逻辑建议在封装层把错误分类映射到用户可读的提示避免用户在对话中直接看到原始报错。5.2 工具调用与上下文问题Agent 表现不稳定的原因绝大多数不在模型而在工具定义和上下文管理。如果你的 Agent 经常选错工具先检查工具描述是否互相混淆比如查询订单和查询物流如果都写成获取订单信息模型很容易选错应该把描述改得更区分化并明确仅当用户询问物流轨迹时才使用这类条件。如果 Agent 出现循环调用先看是不是两个工具互为前置条件比如 A 工具的输出被要求作为 B 工具的输入但模型始终无法得到正确参数。解决方式是合并工具或者增加上下文摘要让模型在一次调用里拿到足够信息。如果 Agent 回答内容对但动作总是出错十有八九是提示词和工具层对同一事物的叫法不一致统一术语能大幅改善稳定性。5.3 评测、回归与灰度上线 Agent 项目最怕的是这周调好了下周又变笨了。模型更新、Prompt 调整、业务系统接口变化任何一个环节变动都可能引入回归。参考实现里没有把评测当成附加项而是作为开发流程的一部分这点对生产极其重要。建议每个 Agent 维护一套自己的评测集包含三类用例一是用户的高频对话场景验证正常路径不走偏二是边界和异常场景比如用户问的问题超出 Agent 能力范围、工具返回报错、用户情绪激烈三是安全红线场景比如诱导 Agent 透露系统提示词、试图越权操作。每次改动代码或提示词都把这套评测跑一遍用通过率和关键指标的变化来决定是否上线。灰度发布同样重要。新版本 Agent 不要全量切可以先放 5% 到 10% 的流量对比人工抽检满意度、任务完成率、平均轮数这些指标。指标不过就回滚到上一版这是 Agent 项目比较少被提及、但实际最能救命的方法论。最后分享一个我自己的体会Agent 不是把模型接上工具就能交付的系统它更像一个需要持续维护的业务应用。Anthropic 这套参考实现最值得学习的地方不是代码本身而是它把事情分层、分角色、加护栏、做评测的思路。电商系统足够复杂恰恰是检验这套方法论的好地方。建议你把仓库拉下来先不管业务认真跑几个完整场景看看它在每个环节是怎么做选择的然后再对照你的真实业务去做裁剪。这样跑一轮下来比看十篇架构文章都管用。
