从 Pi Agent 到电商智能客服：工具调用、人工接管与微信接入实践

我在做这个项目时，最初的问题很简单：如果用户问“北京还有这款耳机吗”，Agent 不仅要会回答，还得从真实库存中查到答案；如果用户说“帮我下单”，系统又不能让模型凭一句话直接扣库存。

于是我在 Pi Agent Core 上做了一个电商智能客服示例。它有客户聊天页、坐席工作台、Agent API、Commerce API 和 MySQL；后来又接入了微信文字通道。这个项目最重要的收获，不是把模型接进聊天框，而是把模型能做什么、不能做什么划清楚。

一、让模型理解意图，让业务系统掌握事实

整体请求链路可以概括为：

用户消息 → Agent API → Pi Agent Core → 受控工具 → Commerce API / 知识库 → 回复用户

例如用户问某地区是否有货，模型选择 get_inventory 工具，传入 SKU 和地区；工具向业务接口查询，而业务接口从 inventory 表按 SKU + region 读取可售数量。模型不直接连数据库，也不负责“猜”库存。商品价格、订单归属和退款资格同样由服务端判定。

我把工具按职责拆开：search_products 搜商品，get_inventory 查库存，list_orders / get_order 查当前用户订单，search_knowledge_base 检索售后政策。工具描述负责告诉模型何时使用；参数校验和权限控制则留在程序里。这样，即使模型选错了工具或给出不合法参数，业务边界仍然存在。

二、下单与退款采用“两段式确认”

查库存是只读操作，下单和退款则会改变真实业务状态。我没有给模型“直接下单”或“审批退款”的工具。

下单时，模型只能创建订单草稿。客户看到商品、数量、地区和金额后，在聊天卡片上主动确认；服务端再读取价格和库存，在 MySQL 事务中锁定库存、扣减并创建订单，同时用幂等键避免重复提交。

退款也是类似流程：模型可以创建申请草稿，但正式提交要由客户确认。是否在退款窗口内由 Commerce API 根据订单时间判定；提交后仅进入待审核状态，模型不能批准退款，更不能承诺到账时间。客户可撤销尚未开始打款的申请。这种设计把“语言上的意愿”和“具有副作用的业务动作”分开了。

三、转人工不是一句提示，而是会话控制权切换

用户投诉或明确要求人工时，Agent 会创建关联当前会话的工单。同一会话的未关闭工单会复用，避免坐席队列里出现重复单。

工单有待认领、处理中、已关闭三个状态。坐席在独立工作台认领后，当前会话进入人工接管：客户的新消息保留在原会话，模型停止回复；坐席能看到上下文并直接回复。关单后，控制权交还模型，模型也能看到此前的人工对话。坐席认领、回复和关单都有审计记录，重复认领由服务端拒绝。

这里还有一个容易忽略的体验问题：如果转人工后每条客户消息都自动回复“已转交人工”，用户会被重复提示打断。正确的交互是接管状态变化时提示一次，后续消息安静地进入坐席队列。

四、把微信当作渠道，不把业务逻辑复制一遍

微信接入采用独立桥接进程：它接收私聊文字消息，转给受内部令牌保护的 Agent API，再把回复发回微信。微信身份映射到业务用户和 Pi 会话；消息去重、同步游标和待发送回复保存在 MySQL。桥接进程不直接操作订单，也不开放终端或文件系统能力。

微信没有 Web 确认卡片，因此下单和退款使用短时有效的一次性确认码。只有用户明确回复确认指令，才执行真正的写操作。人工坐席的回复也进入同一会话，并经待发送队列返回微信。

从这个实践我体会到：多渠道接入最好共享同一个业务核心，渠道层只处理消息格式、身份映射与投递。否则每接一个入口，就会复制一套安全规则。

五、知识库与前端的当前取舍

目前售后知识库是 Markdown 文档入库后由 MySQL LIKE 检索，适合少量固定政策。检索能力被封装在 KnowledgeGateway 接口后面，后续文档量增大时可以替换为 Milvus，而不改 Agent 工具契约。客户页面通过 SSE 展示模型回复和工具状态；项目还加入了滚动驱动的星球过渡页，作为进入客服窗口前的视觉引导。

这些选择服务于当前的演示目标，并不等于已经达到生产级。现在仍使用演示用户登录和共享坐席内部令牌；微信只覆盖私聊文字消息；没有真实支付、物流签收时间、退款审批界面。多实例会话锁、外部调用超时与重试也还需要补齐。

六、这次开发最值得复用的经验

做 Agent 应用，先定义业务动作的边界，再设计提示词和工具。只读查询可以由模型发起；涉及资金、库存或账户权益的动作，应由服务端校验、用户确认或人工审批。这样做出来的客服，才不仅“会聊天”，也能在真实业务约束下可靠地工作。