电商 Agent 架构设计：分层编排、工具调用与稳定性实战

1. 电商 Agent 架构设计的核心思路拆解

1.1 为什么电商场景对 Agent 架构有特殊要求

电商购物助手这个场景，和通用的对话机器人有本质区别。通用聊天机器人回答错了，用户笑一笑就过去了；但购物助手如果推荐错了商品、算错了优惠、报错了库存，用户直接下单失败或者买贵了，这是实打实的体验事故。所以电商 Agent 的第一性要求不是“能聊”，而是“又快又稳”。

“快”体现在响应延迟上。用户问“帮我找一款三百块以内的蓝牙耳机”，从意图识别、商品检索、库存校验到最终生成推荐话术，整条链路必须在秒级完成。一旦超过三秒，用户大概率就切走了。“稳”体现在准确性上，价格、库存、优惠规则这些数据不能靠模型“记忆”或“猜测”，必须走实时接口校验。

我在实际搭建类似系统时踩过最大的坑，就是早期让模型直接根据上下文里的商品信息生成回答，结果模型会“脑补”出不存在的优惠券和库存状态。后来改成所有关键数据必须经过工具调用实时获取，模型只负责编排和话术生成，准确率才稳定下来。这个教训直接决定了整个架构的设计方向：模型负责理解和表达，数据负责事实和约束。

1.2 分层架构：把“聪明”和“可靠”拆开

一个成熟的电商 Agent 架构，我倾向于拆成四层：

• 接入层：处理用户输入，做初步的意图分类和路由。这一层要尽量轻，不要在这里做重逻辑。
• 编排层：这是 Agent 的“大脑”，负责决定调用哪些工具、按什么顺序调用、如何处理中间结果。通常由一个规划器加一个执行器组成。
• 工具层：封装所有外部能力，比如商品搜索、价格查询、库存校验、优惠计算、订单创建。每个工具都是独立的、可测试的、有明确输入输出的函数。
• 数据层：商品库、用户画像、会话状态、日志。这一层是事实的唯一来源。

这样拆的好处是，编排层可以灵活调整策略而不影响工具实现，工具层可以独立优化性能而不影响上层逻辑。我见过不少团队把工具调用逻辑直接写死在提示词里，结果改一个接口就要重新调提示词，维护成本极高。

1.3 编排层的两种主流模式：ReAct 与 Plan-and-Execute

编排层目前有两种主流实现方式。一种是 ReAct 模式，即“思考-行动-观察”循环，模型每一步都根据当前状态决定下一步做什么。这种模式灵活，适合探索性任务，但延迟高，因为每一步都要等模型输出。

另一种是 Plan-and-Execute 模式，先让模型生成一个完整的执行计划，然后按计划依次调用工具，中间只在必要时才让模型介入调整。这种模式延迟低、可控性强，适合电商这种流程相对固定的场景。

我的建议是混合使用：对于“找商品”这类开放式任务用 ReAct，对于“下单”这类流程化任务用 Plan-and-Execute。实际落地时，可以在编排层做一个任务分类器，根据用户意图自动选择模式。这样既保证了灵活性，又保证了关键路径的稳定性。

2. 核心细节解析与实操要点

2.1 工具调用的参数设计：别让模型自由发挥

工具调用的参数设计是整个架构里最容易被忽视、但影响最大的环节。很多团队让模型自己生成工具调用的参数，比如搜索关键词、价格区间、排序方式，结果模型经常生成一些奇怪的参数组合，导致检索结果为空或者偏离用户意图。

我的做法是：对每个工具的参数做严格约束。比如商品搜索工具，参数只允许是结构化的 JSON，包含category、price_min、price_max、keywords、sort_by这几个字段，每个字段都有明确的类型和取值范围。模型的任务是从用户话语中抽取这些字段，而不是自由生成查询语句。

具体实现上，可以用函数调用（Function Calling）或者结构化输出（Structured Output）来约束模型输出。以函数调用为例，定义一个search_products函数，参数 schema 里明确写清楚每个字段的类型、描述和枚举值。模型输出后，先做一层参数校验，不合法的参数直接拒绝并让模型重新生成，而不是带着错误参数去查数据库。

注意：参数校验一定要在工具层做，不要依赖模型自觉。我见过模型把price_max填成负数的情况，如果不校验，数据库查询直接报错。

2.2 会话状态管理：别把历史全塞进上下文

电商购物助手通常需要多轮对话，比如用户先问“有没有降噪耳机”，再问“刚才那个第二个多少钱”。这就要求 Agent 能记住之前的交互。但把全部历史对话塞进上下文有两个问题：一是 token 消耗大、延迟高；二是模型容易被无关历史干扰。

我的方案是维护一个结构化的会话状态对象，包含current_intent、last_search_results、selected_product、user_preferences等字段。每轮对话结束后，用一个轻量的抽取模型更新这个状态对象，而不是把原始对话全部保留。下一轮对话时，只把状态对象和最近一两轮对话传给模型。

这样做的另一个好处是，状态对象可以持久化到数据库，支持跨会话恢复。用户今天没买完，明天回来还能接着上次的进度。这个体验在电商场景里很重要，但很多团队一开始没考虑到。

2.3 缓存策略：哪些能缓存，哪些绝对不能

电商 Agent 的性能优化，缓存是绕不开的。但缓存用错了地方，会导致用户看到过期的价格或库存，这是致命的。

我的原则是：静态数据可以缓存，动态数据必须实时。商品标题、描述、图片这些不常变的数据，可以缓存几分钟到几小时。但价格、库存、优惠券状态这些必须实时查询，或者至少设置很短的缓存时间（比如 10 秒），并且在下单前做最终校验。

具体实现上，可以在工具层加一个缓存装饰器，对不同的工具设置不同的 TTL。比如get_product_detail缓存 300 秒，check_inventory缓存 5 秒，calculate_discount不缓存。同时，在下单工具里强制重新校验价格和库存，确保用户看到的价格和实际支付价格一致。

提示：缓存 key 的设计要包含所有影响结果的参数。我见过有人用商品 ID 做 key，结果不同用户看到不同价格（因为会员等级不同）时缓存串了，导致普通用户看到了会员价。

3. 实操过程与核心环节实现

3.1 从零搭建一个最小可用的电商 Agent

假设我们要从零搭建一个电商购物助手，支持“搜索商品-查看详情-下单”这条主流程。下面是我实际落地时的步骤和关键代码结构。

第一步，定义工具集。每个工具都是一个独立的函数，有明确的输入输出。以商品搜索为例：

def search_products( category: str, price_min: float = 0, price_max: float = 999999, keywords: list[str] = None, sort_by: str = "relevance", limit: int = 10 ) -> list[dict]: """ 搜索商品，返回商品列表。 每个商品包含 id, title, price, image_url, rating 等字段。 """ # 实际实现会查询商品数据库或搜索服务 ...

第二步，定义编排逻辑。用一个状态机来管理对话流程，每个状态对应一个处理函数。比如IDLE状态下等待用户输入，SEARCHING状态下调用搜索工具，CONFIRMING状态下等待用户确认下单。

class ShoppingAgent: def __init__(self): self.state = "IDLE" self.context = {} def handle(self, user_input: str) -> str: if self.state == "IDLE": return self._handle_idle(user_input) elif self.state == "SEARCHING": return self._handle_searching(user_input) ...

第三步，接入模型做意图识别和话术生成。模型只负责两件事：把用户输入转成结构化的意图和参数，以及把工具返回的结构化数据转成自然语言回复。中间的所有逻辑流转由状态机控制，不经过模型。

这样做的结果是，整个系统的行为是可预测的、可测试的。你可以写单元测试来验证每个状态转换是否正确，而不需要每次都跑一遍模型。

3.2 关键参数的计算与选择

在电商 Agent 里，有几个参数需要仔细计算和选择。

超时时间：每个工具调用都要设置超时。商品搜索建议 2 秒，库存查询建议 1 秒，下单建议 5 秒。超时后要有降级策略，比如返回缓存数据或者提示用户稍后重试。我一般会在工具层统一设置超时，并在编排层处理超时异常。

重试次数：对于幂等的查询类工具，可以重试 1-2 次。对于下单这类非幂等操作，绝对不能自动重试，必须让用户确认。我见过因为自动重试导致用户被重复下单的案例，这是严重的事故。

上下文窗口：传给模型的上下文要控制大小。我的经验是，系统提示词加状态对象加最近两轮对话，控制在 2000 token 以内。超过这个数，延迟会明显上升，而且模型注意力会被稀释。

并发度：如果一次要查多个商品的价格和库存，可以并发调用。但并发度不要超过 5，否则容易触发下游服务的限流。可以用异步 IO 来实现并发，比如 Python 的asyncio.gather。

3.3 一个完整的下单流程拆解

以“用户下单”为例，拆解一下完整的工具调用链：

1. 确认商品：调用get_product_detail获取最新商品信息，确认商品仍在售。
2. 校验库存：调用check_inventory确认库存充足。
3. 计算价格：调用calculate_discount计算最终价格，包括优惠券、会员折扣、满减等。
4. 生成订单预览：把商品信息、价格、收货地址等汇总，展示给用户确认。
5. 用户确认：等待用户明确确认。
6. 创建订单：调用create_order创建订单，这一步要带幂等键，防止重复下单。
7. 返回结果：把订单号、支付链接等返回给用户。

每一步都要有明确的成功和失败处理。比如库存不足时，要返回“该商品暂时缺货”并推荐相似商品；价格计算失败时，要提示用户稍后重试而不是直接下单。

注意：第 5 步的用户确认不能省。我见过为了追求“自动化”而跳过确认直接下单的设计，结果用户只是问“这个多少钱”就被下单了，这是灾难性的体验。

4. 常见问题与排查技巧实录

4.1 模型“幻觉”导致推荐不存在的商品

这是最常见的问题。模型在生成推荐话术时，可能会编造出商品库里没有的商品，或者把商品属性说错。排查方法是：在工具层返回结果后，加一层校验，确保模型输出的商品 ID 都在工具返回的列表里。如果不在，直接拦截并重新生成。

更彻底的做法是，不让模型自由生成商品信息，而是用模板填充。模型只负责选择推荐哪个商品和生成推荐理由，商品标题、价格、图片这些从工具返回的数据里直接取。

4.2 多轮对话中意图丢失

用户说“第一个太贵了，有没有便宜点的”，模型需要知道“第一个”指的是上一轮搜索结果里的第一个商品。如果上下文管理没做好，模型就不知道“第一个”是什么。

解决方法是在会话状态里显式记录last_search_results，并在提示词里明确告诉模型“上一轮搜索结果是这些”。同时，在意图识别时，把指代词解析成具体的商品 ID，而不是让模型自己去猜。

4.3 工具调用超时导致整体响应慢

如果某个工具调用超时，整个链路都会被拖慢。排查时先看日志，确认是哪个工具慢。常见原因有：数据库查询没加索引、下游服务限流、网络抖动。

优化手段包括：给工具加缓存、设置合理的超时和重试、对非关键路径的工具做异步化。比如商品推荐可以异步加载，不阻塞主流程。

4.4 常见问题速查表

4.5 几个我踩过的坑

第一个坑是过度依赖模型做决策。早期我把“是否推荐某个商品”的判断也交给模型，结果模型经常推荐一些明显不合适的商品（比如用户要买耳机，推荐了耳机套）。后来改成用规则引擎做初筛，模型只负责在候选集里排序和生成话术，效果好很多。

第二个坑是忽略了下游服务的稳定性。有一次商品搜索服务挂了，整个 Agent 直接不可用。后来加了降级策略，搜索服务不可用时返回热门商品列表，至少保证用户还能逛。

第三个坑是日志打得太少。出问题时根本不知道是哪一步错了。后来在每个工具调用前后都打日志，记录输入参数、输出结果、耗时，排查效率提升了很多。

5. 性能优化与稳定性保障

5.1 延迟优化的几个关键手段

电商 Agent 的延迟主要来自三部分：模型推理、工具调用、网络传输。模型推理的优化空间有限，主要是选更小的模型或者用流式输出。工具调用的优化空间最大，可以通过缓存、并发、预计算来降低延迟。

我常用的一个技巧是预取。比如用户搜索了“蓝牙耳机”，在展示搜索结果的同时，后台异步预取前几个商品的详情和库存。等用户点击某个商品时，数据已经准备好了，响应几乎是瞬时的。

另一个技巧是流式输出。模型生成回复时，不要等全部生成完再返回，而是边生成边返回。用户看到第一个字的时间从 2 秒降到 500 毫秒，体感快很多。

5.2 稳定性保障：降级、熔断、限流

稳定性保障的核心是“假设一切都会失败”。每个工具调用都要有降级方案，每个下游服务都要有熔断机制，每个入口都要有限流。

降级方案举例：商品搜索失败时返回热门商品；价格计算失败时提示用户稍后重试；推荐服务失败时返回默认推荐列表。关键是不要让一个环节的失败导致整个系统不可用。

熔断机制可以用现成的库来实现，比如设置一个失败率阈值，超过阈值就暂时切断对该服务的调用，过一段时间再试探性恢复。

限流主要是防止恶意请求或者突发流量打垮系统。可以在接入层做，按用户 ID 或 IP 限流。

5.3 监控与告警：哪些指标必须盯

必须监控的指标包括：端到端响应时间（P50、P95、P99）、各工具调用成功率、模型调用成功率、缓存命中率、下单转化率。告警阈值根据业务情况设定，比如 P99 响应时间超过 5 秒就告警，工具调用成功率低于 99% 就告警。

日志要记录每个请求的完整链路，包括用户输入、意图识别结果、工具调用参数和结果、模型输出、最终回复。这样出问题时可以快速定位。

提示：监控指标要按维度拆分，比如按商品类目、按用户等级、按时间段。这样能发现一些隐藏的问题，比如某个类目的搜索特别慢，或者某个时间段下单失败率特别高。

6. 扩展方向与个人经验

这套架构不只适用于电商购物助手，稍作调整就可以用在其他需要“又快又稳”的场景，比如客服机器人、订票助手、酒店预订等。核心思想是一样的：模型负责理解和表达，工具负责事实和约束，编排层负责流程控制。

我个人在实际操作中的体会是，不要追求一步到位。先搭一个最小可用的版本，跑通主流程，然后再逐步优化。我见过不少团队一开始就想做得很完美，结果几个月都上不了线。反而是那些先上线再迭代的团队，最终效果更好。

另外，测试非常重要。每个工具都要有单元测试，每个状态转换都要有集成测试，整个链路要有端到端测试。电商场景的错误成本很高，测试是保证稳定性的最后一道防线。

最后分享一个小技巧：在提示词里明确告诉模型“如果不确定，就说不知道，不要编造”。这句话看起来简单，但能减少很多幻觉问题。配合工具返回的结构化数据，模型的输出质量会稳定很多。