1. 为什么要在电商系统里引入 AI Native 思路电商系统这个赛道过去十年基本是堆功能的逻辑商品、订单、库存、营销、履约、售后每个模块独立开发、独立部署靠一张张接口把数据串起来。这套架构能跑但问题也很明显——业务规则一旦复杂起来代码里全是 if-else运营想改个促销策略得提需求排期客服想查个订单状态得在五六个后台之间来回切。我做过几个中大型电商项目最深的体会就是系统越完整响应业务的速度反而越慢。AI Native 这个词这两年很热但很多人理解偏了以为就是接个大模型 API 做客服机器人。真正的 AI Native 不是给现有系统贴一层 AI 皮肤而是从架构设计的第一天起就把 Agent 当作系统的一等公民。换句话说电商系统里那些原本靠硬编码实现的业务逻辑现在应该由 Agent 来动态决策和执行。我这次实践的核心目标很明确用 Claude Code 这类 Agent 开发工具链搭一套能真正跑起来的电商业务系统让商品管理、订单处理、营销推荐、售后客服这几个核心环节都由 Agent 驱动而不是写死的流程。选 Anthropic 这套技术栈原因有三点一是 Claude 在长上下文和工具调用上的稳定性确实好处理订单这种多步骤任务不容易断片二是 Claude Code 作为开发工具能直接把自然语言需求转成可执行的代码和操作开发效率提升明显三是 Agent Skills 这套机制让能力扩展变得很轻不用每次都改核心代码。这套东西适合谁看如果你是有一定后端基础、想了解 Agent 怎么落地到真实业务系统的开发者或者你是技术负责人、在评估 AI Native 架构到底能不能扛住生产环境那这篇内容应该能给你一些直接能抄的作业。我会把架构设计、核心实现、踩过的坑都摊开讲不玩虚的。2. 整体架构设计与技术选型拆解2.1 从功能模块到Agent 编排的思维转变传统电商系统的架构是分层的接入层、业务层、数据层业务层里再按领域拆成一个个 Service。这种架构的好处是职责清晰坏处是跨领域的业务逻辑没有归属。比如用户下单后如果库存不足自动触发补货并通知用户预计到货时间——这个逻辑横跨订单、库存、通知三个模块放哪儿都别扭最后往往塞进一个流程编排层越堆越厚。AI Native 的思路是把这类跨领域逻辑交给 Agent。Agent 不关心数据存在哪张表、接口怎么调它只关心目标是什么和有哪些工具可用。我设计的架构里底层还是保留传统的商品、订单、库存服务但上面加了一层Agent 编排层由它来调度这些服务。具体来说整个系统分成四层数据与服务层商品库、订单库、库存库、用户库以及对应的 CRUD 接口。这部分保持传统实现用 PostgreSQL 加 Redis 就够了不搞花活。工具层Tool Layer把服务层的接口封装成 Agent 能调用的工具每个工具都有清晰的描述、参数定义和返回格式。这是整个架构的关键工具设计得好不好直接决定 Agent 能不能用。Agent 层按业务域划分的多个 Agent比如商品 Agent、订单 Agent、营销 Agent、客服 Agent。每个 Agent 有自己的系统提示词、可用工具集和记忆。编排层一个主控 Agent 负责理解用户意图把任务分发给对应的子 Agent并汇总结果。这个分层的好处是每层都能独立演进。工具层加个新工具Agent 立刻就能用Agent 的提示词改了不用动底层服务编排逻辑调整也不影响具体业务。2.2 为什么选 Claude Code 作为开发主力开发这套系统的过程中我大量使用了 Claude Code。这里得说清楚Claude Code 不只是个代码补全工具它更像一个能直接操作终端、读写文件、执行命令的 Agent。我实际用下来几个场景特别顺手第一个是快速搭骨架。我直接跟它说帮我建一个 FastAPI 项目包含商品、订单、库存三个模块每个模块有基础的 CRUD 接口用 SQLAlchemy 做 ORM它能把目录结构、依赖文件、基础代码一次性生成出来。这比我自己一个个建文件快太多了。第二个是工具层封装。把 REST 接口封装成 Agent 工具这个活儿很机械但容易出错参数类型、描述文本、错误处理都得写对。我让 Claude Code 读一遍接口文档然后批量生成工具定义准确率相当高。第三个是调试。Agent 跑起来之后行为不符合预期我会把日志贴给它让它分析可能的原因。它经常能指出我没想到的边界情况比如某个工具在参数为空时的处理逻辑。提示Claude Code 在 Windows 和 Ubuntu 上都能装我两个环境都试过。Windows 下建议用 WSL2原生 PowerShell 偶尔会有路径和编码问题。安装完记得配好 API 相关的环境变量不然连不上服务。2.3 Agent 框架的选型考量市面上 Agent 框架不少我最后没有用那些全家桶式的重框架而是基于 Anthropic 的 SDK 自己搭了一套轻量编排。原因很简单电商业务的确定性要求高框架越重出问题时越难排查。重框架通常会把 Agent 的思考过程、工具调用、记忆管理都封装起来看起来省事但一旦某个环节出问题你根本不知道是框架的锅还是自己的锅。我踩过这个坑用某个流行框架做订单处理结果 Agent 偶尔会跳过库存检查直接下单查了半天发现是框架的工具调用顺序有问题。自己搭的话核心就三件事定义工具、管理对话历史、控制循环。工具定义用 JSON Schema对话历史用一个列表存循环就是模型返回工具调用就执行、执行完把结果塞回去继续问直到模型返回最终答案。这套逻辑不到两百行代码就能写清楚可控性拉满。3. 核心细节解析与实操要点3.1 工具层设计Agent 能不能干活全看这里工具层是整个系统里我最花心思的地方。一个工具设计得好不好有几个硬标准描述要像写给新人看的说明书。模型的工具选择完全依赖描述文本描述写得含糊模型就会乱调。比如查询订单这个工具如果描述只写查询订单信息模型可能在你问这个用户最近买了啥的时候也去调它。正确的写法是根据订单号查询单个订单的详细信息包括商品、金额、状态、物流。如果只有用户 ID 没有订单号请使用 list_user_orders 工具。参数要少而精。我见过有人把工具参数设计得跟数据库字段一样多十几个可选参数模型根本记不住。我的原则是必填参数不超过三个可选参数能砍就砍复杂查询拆成多个工具。返回结果要结构化且带上下文。工具返回的不只是数据还要告诉模型这个结果意味着什么。比如库存查询工具返回的不只是数字还要带上库存充足/库存紧张/已售罄的判断这样模型不用自己算。下面是我实际用的一个工具定义示例{ name: check_inventory, description: 查询指定商品在指定仓库的库存数量。返回库存数量以及库存状态判断。当用户询问商品是否有货、能否下单时使用此工具。, input_schema: { type: object, properties: { product_id: { type: string, description: 商品唯一标识格式为 SKU 开头的字符串 }, warehouse_id: { type: string, description: 仓库标识不传则查询所有仓库的总库存 } }, required: [product_id] } }对应的执行函数里我会做几件事查数据库、计算总库存、根据阈值判断状态、组装返回文本。返回文本大概长这样商品 SKU12345 当前总库存 47 件其中华东仓 30 件、华南仓 17 件。库存状态充足阈值 20 件。注意工具执行一定要做超时和异常处理。Agent 调用工具时如果卡住整个对话就挂了。我给每个工具都设了 5 秒超时超时返回明确的错误信息让模型知道这个工具暂时不可用而不是一直等。3.2 Agent 的记忆管理别让上下文爆掉电商场景的对话往往很长用户可能先问商品、再问订单、再问售后一轮下来几十条消息。如果无脑把所有历史都塞给模型上下文很快就爆了而且成本也扛不住。我的做法是分层记忆短期记忆最近 10 轮对话完整保留保证当前任务的连贯性。摘要记忆超过 10 轮的部分用模型压缩成一段摘要保留关键信息用户 ID、涉及的商品和订单、已确认的结论。长期记忆用户画像、历史偏好这类信息存在数据库里需要时通过工具查询不占上下文。这里有个细节很关键摘要不能丢关键 ID。我一开始让模型自由摘要结果它把订单号给概括没了后面用户说就那个订单Agent 完全不知道是哪个。后来我改成结构化摘要强制保留所有出现的实体 ID问题就解决了。3.3 多 Agent 协作的边界划分我一开始想搞一个大而全的 Agent什么都能干。实测下来不行工具一多模型选择困难经常调错工具。后来改成按业务域拆分每个 Agent 只负责一块Agent 名称职责范围可用工具数商品 Agent商品查询、库存检查、价格咨询6订单 Agent下单、查单、改单、取消8营销 Agent优惠券、促销活动、推荐5客服 Agent售后、退换货、投诉7每个 Agent 的工具数控制在 10 个以内实测这个数量下模型的选择准确率最高。超过 15 个工具错误率明显上升。Agent 之间的协作通过编排层完成。用户说我想买那个昨天看的鞋用我的优惠券编排层先识别出这涉及商品和营销两个域先调商品 Agent 确认商品和库存再调营销 Agent 算优惠最后调订单 Agent 下单。整个过程对用户是透明的他只管说需求。4. 实操过程与核心环节实现4.1 环境搭建与项目初始化先把环境搭起来。我用的是 Ubuntu 22.04Python 3.11。Claude Code 的安装按官方文档走就行装完之后在项目目录里初始化。项目结构我设计成这样ecommerce-ai-native/ ├── app/ │ ├── services/ # 传统业务服务 │ │ ├── product.py │ │ ├── order.py │ │ └── inventory.py │ ├── tools/ # Agent 工具层 │ │ ├── product_tools.py │ │ ├── order_tools.py │ │ └── registry.py │ ├── agents/ # Agent 定义 │ │ ├── base.py │ │ ├── product_agent.py │ │ └── order_agent.py │ ├── orchestrator/ # 编排层 │ │ └── main.py │ └── memory/ # 记忆管理 │ └── manager.py ├── config/ │ └── settings.py └── requirements.txt初始化的时候我直接用 Claude Code 生成了基础骨架然后手动调整。这里有个经验别让工具生成太多代码生成个骨架就行核心逻辑自己写。生成太多你根本看不懂后面出问题排查起来更痛苦。4.2 工具注册机制的实现工具注册我用了一个装饰器模式写起来清爽# tools/registry.py TOOL_REGISTRY {} def register_tool(name, description, input_schema): def decorator(func): TOOL_REGISTRY[name] { definition: { name: name, description: description, input_schema: input_schema }, handler: func } return func return decorator def get_tools_for_agent(tool_names): return [TOOL_REGISTRY[n][definition] for n in tool_names] def execute_tool(name, params): handler TOOL_REGISTRY[name][handler] try: return handler(**params) except Exception as e: return f工具执行失败{str(e)}用的时候register_tool( namecheck_inventory, description查询商品库存..., input_schema{...} ) def check_inventory(product_id, warehouse_idNone): # 实际查询逻辑 ...这个设计的好处是工具的定义和执行绑在一起加新工具只要写一个函数加装饰器不用改其他地方。而且execute_tool统一做了异常捕获任何工具报错都不会让整个 Agent 崩掉。4.3 Agent 主循环的实现Agent 的核心就是一个循环把对话历史发给模型模型要么返回文本结束要么返回工具调用执行后继续。我实现的主循环大概是这样def run_agent(agent, user_input, max_iterations10): agent.memory.add_user_message(user_input) for i in range(max_iterations): response call_model( systemagent.system_prompt, messagesagent.memory.get_messages(), toolsagent.tools ) if response.stop_reason end_turn: agent.memory.add_assistant_message(response.content) return response.text if response.stop_reason tool_use: agent.memory.add_assistant_message(response.content) for tool_call in response.tool_calls: result execute_tool(tool_call.name, tool_call.input) agent.memory.add_tool_result(tool_call.id, result) continue return 抱歉处理超时请重新描述您的需求。max_iterations这个参数很重要。我设的是 10意思是 Agent 最多调 10 轮工具。实测下来正常的电商任务 3 到 5 轮就够了设 10 是留余量。如果不设上限遇到模型钻牛角尖的情况会无限循环烧钱还不出结果。4.4 一个完整的下单流程实录拿帮我下单那个 SKU12345 的鞋用我账户里的优惠券这个需求走一遍完整流程。第一步编排层识别意图。主控 Agent 收到请求判断涉及商品确认、优惠计算、下单三个动作分发给对应子 Agent。第二步商品 Agent 确认商品。调用get_product_detail拿到商品信息调用check_inventory确认有货。返回商品 SKU12345 为轻跑鞋 42 码单价 399 元库存充足。第三步营销 Agent 算优惠。调用get_user_coupons查用户可用券发现有一张满 300 减 50的券。调用calculate_discount算出实付 349 元。返回可用优惠券满 300 减 50实付 349 元。第四步订单 Agent 下单。调用create_order参数是商品 ID、数量、用户 ID、优惠券 ID。工具内部会做库存扣减、订单落库、优惠券核销。返回订单号。第五步编排层汇总。把结果整理成一句话返回给用户已为您下单订单号 ORD20250115001商品轻跑鞋 42 码原价 399 元优惠 50 元实付 349 元预计 3 天内发货。整个过程用户只说了一句话背后跑了 6 次工具调用。这就是 AI Native 的价值——用户表达意图系统负责执行。提示下单这类有副作用的操作一定要做幂等。我遇到过模型因为超时重试结果下了两单的情况。解决办法是给每个下单请求生成唯一 ID工具内部先查这个 ID 是否已处理过。5. 常见问题与排查技巧实录5.1 模型不调用工具直接瞎编答案这是最常见的问题。用户问SKU12345 有货吗模型不调check_inventory直接回应该有货。原因通常是系统提示词没写清楚或者工具描述不够有吸引力。我的解决办法是在系统提示词里加一条硬规则涉及任何商品、订单、库存的具体数据必须通过工具查询禁止凭记忆或推测回答。另外把工具描述写得更具体明确说当用户询问库存时使用此工具。5.2 工具调用参数格式错误模型有时候会把参数类型搞错比如该传字符串的传了数字或者该传数组的传了单个值。这个问题的根源是 JSON Schema 定义不够严格。我的做法是在工具执行函数里做参数校验和转换容错处理。比如product_id期望字符串如果收到数字就自动转成字符串。同时在 Schema 里把type写死别用any。5.3 多轮对话中丢失上下文用户先说我要买鞋Agent 问哪双用户说就那双Agent 懵了。这是记忆管理的问题。解决办法是在摘要里强制保留实体。我改进了摘要逻辑让模型摘要时必须输出一个结构化的实体列表包含所有提到的商品 ID、订单号、用户 ID。下一轮对话时这个实体列表会作为上下文注入Agent 就知道那双指的是什么了。5.4 并发场景下的状态混乱电商系统天然是高并发的。多个用户同时下单库存扣减如果没做好锁会超卖。这个问题在传统系统里也存在但 Agent 场景下更隐蔽因为 Agent 的决策和执行是分离的。我的方案是把并发控制下沉到工具层。库存扣减工具内部用数据库的行锁或者 Redis 的原子操作保证同一商品的扣减是串行的。Agent 层不用关心并发它只管调工具工具保证正确性。问题现象可能原因排查方向解决方案模型不调工具提示词不明确检查系统提示词加硬规则明确工具使用场景参数格式错误Schema 不严格检查 input_schema严格定义类型执行层做容错上下文丢失摘要丢实体检查摘要逻辑结构化摘要强制保留 ID超卖并发无控制检查库存扣减工具层加锁保证原子性无限循环无迭代上限检查主循环设 max_iterations重复下单无幂等检查下单工具请求 ID 去重5.5 成本控制的实操经验Agent 跑起来之后token 消耗是个现实问题。我实测下来一个完整的下单流程大概消耗 8000 到 12000 个 token按 Claude 的定价单次成本在几毛钱。如果日订单量上万这个成本不能忽略。几个降本手段一是缓存工具结果同一个商品在短时间内被多次查询直接返回缓存二是精简系统提示词别写一堆废话提示词每多 1000 token每次调用都多花这个钱三是用小模型做意图识别把请求路由到对应 Agent 这一步不需要用最强的模型用便宜的小模型就够了。5.6 安全边界Agent 不能什么都干Agent 能调工具就意味着它能改数据。这很危险。我的原则是读操作放开写操作收紧。具体来说查询类工具随便调但涉及金额变动、库存扣减、订单创建的工具必须满足几个条件一是要有明确的用户确认二是要有金额上限超过阈值转人工三是要有完整的操作日志每一步都能追溯。我还给 Agent 加了一个敏感操作标记遇到这类工具调用时会先返回给用户确认即将为您下单实付 349 元确认吗用户确认后才真正执行。这个确认环节看起来多余但能避免大量误操作。6. 这套架构后续还能怎么扩展跑通基础流程之后我陆续加了一些扩展能力效果不错这里分享两个方向。一个是主动式 Agent。现在的 Agent 都是被动响应用户问才答。我加了一个定时任务让营销 Agent 每天扫描用户行为发现加购未下单浏览多次未购买这类情况主动推送优惠券。这个功能上线后转化率有肉眼可见的提升。另一个是Agent 之间的协商机制。现在编排层是命令式的主控 Agent 直接指派任务。更高级的做法是让子 Agent 之间能协商比如订单 Agent 发现库存不足可以直接跟商品 Agent 沟通补货时间而不是把问题抛回给用户。这个我还在实验阶段但方向是对的。最后说个我踩过的坑别指望 Agent 一次就完美。我一开始追求全自动结果各种边界情况处理不过来。后来改成Agent 处理 80% 的常规情况20% 的异常转人工系统反而稳定多了。AI Native 不是要取代人而是把人从重复劳动里解放出来去处理真正需要判断力的事情。这个心态摆正了落地会顺利很多。
