企业官网建设流程全解析

前阵子 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. 架构设计思路：从聊天机器人到真正能办事的 Agent

2.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 这套参考实现最值得学习的地方，不是代码本身，而是它把事情分层、分角色、加护栏、做评测的思路。电商系统足够复杂，恰恰是检验这套方法论的好地方。建议你把仓库拉下来，先不管业务，认真跑几个完整场景，看看它在每个环节是怎么做选择的，然后再对照你的真实业务去做裁剪。这样跑一轮下来，比看十篇架构文章都管用。