【基于 ReAct 框架的电商智能客服 AI Agent 设计与实现】

目录

一、引言

二、系统整体架构

三、核心模块设计与实现

[3.1 环境依赖与项目目录结构](#3.1 环境依赖与项目目录结构)

[3.2 模型配置文件 config.json](#3.2 模型配置文件 config.json)

[3.3 店铺优惠数据源 store_promotions.txt](#3.3 店铺优惠数据源 store_promotions.txt)

[3.4 本地模型测试脚本 test.py](#3.4 本地模型测试脚本 test.py)

[3.5 大模型客户端 op_llm_client.py](#3.5 大模型客户端 op_llm_client.py)

[3.6 Agent 核心逻辑 agent.py](#3.6 Agent 核心逻辑 agent.py)

[3.7 全局调度入口 main.py](#3.7 全局调度入口 main.py)

[3.8 业务工具模块](#3.8 业务工具模块)

四、系统业务运行实例

五、系统创新点与项目优势

六、项目部署与运行教程

[6.1 虚拟环境创建](#6.1 虚拟环境创建)

[6.2 项目依赖安装](#6.2 项目依赖安装)

[6.3 私密密钥配置](#6.3 私密密钥配置)

[6.4 本地模型连通测试](#6.4 本地模型连通测试)

[6.5 启动智能客服系统](#6.5 启动智能客服系统)

七、总结与未来优化方向

---

摘要：随着大语言模型技术快速迭代，智能 Agent 自主交互方案成为行业落地主流方向。本文依托ReAct 推理行动协同框架，搭建电商场景专属智能客服系统。项目兼容阿里云通义千问在线大模型、Ollama 本地开源模型双运行模式，具备自主逻辑推理、外部工具调用、多轮会话推演能力，能够自动化完成商品检索、优惠政策读取、交易价格核算等客服核心业务，有效降低人工客服压力，提升用户咨询交互体验。

一、引言

传统电商客服普遍采用人工值守 + 固定话术应答模式，面对商品溯源咨询、叠加优惠核算、多品类比价等复杂问题时，存在响应滞后、人力成本偏高、业务拓展性不足等短板。常规大语言模型仅具备文本理解与生成能力，无法联动本地文件、计算组件、商品数据库等外部业务资源，难以满足实际客服业务需求。

ReAct 框架将 ** 逻辑推理（Reasoning）与业务行动（Acting）** 深度融合，模拟人类思考办事逻辑，先分析问题解决思路，再按需调用外部工具获取数据，整合信息后输出完整答复。本文基于该框架开发轻量化 AI 客服 Agent，实现以下核心能力：

1.自主拆解用户问题，规划分步解决流程

2.封装商品查询、优惠读取、数值计算三类实用工具

3.支持在线云端模型、本地离线模型一键切换部署

4.增设迭代次数限制与全局异常捕获，规避程序死循环

系统采用模块化解耦设计，部署门槛低、功能拓展性强，可直接应用于线上店铺咨询、智能问答机器人、自动化售后助手等业务场景。

二、系统整体架构

整体采用面向对象模块化开发思路，划分五大核心功能模块，模块间低耦合独立运行，调用逻辑清晰。

1.配置模块：管控模型启停、推理参数、接口访问地址

2.LLM 客户端模块：统一封装在线 API、本地模型调用接口

3.Agent 核心模块：承载 ReAct 推理逻辑，维护会话上下文

4.主调度模块：统筹推理循环、解析模型指令、执行工具函数

5.业务工具模块：提供商品检索、优惠读取、价格计算业务能力

系统运行流程

用户提交咨询问题 → Agent 解析需求推理思路 → 判断是否调用外部工具 → 执行工具获取观测数据 → 整合数据二次推演 → 生成标准客服答复

三、核心模块设计与实现

3.1 环境依赖与项目目录结构

项目基于 Python 语言开发，依赖第三方库版本固定，环境搭建简单高效。

# pyproject.toml 依赖配置
dependencies = [
    "ollama==0.3.3",
    "openai==1.45.0",
    "python-dotenv>=1.2.2",
    "requests==2.32.3",
]

完整项目文件目录

ai-agent/
├── agent.py            # Agent核心推理逻辑文件
├── op_llm_client.py    # 大模型通用客户端封装
├── main.py             # 程序入口与全局调度文件
├── config.json         # 模型参数配置文件
├── .env                # 密钥私密存储文件
├── tools/              # 业务工具函数文件夹
│   ├── query_product_data.py  # 商品查询工具
│   ├── read_promotions.py     # 优惠读取工具
│   └── calc.py                # 价格计算工具
├── store_promotions.txt # 店铺优惠政策数据源
├── test.py             # Ollama本地模型连通性测试脚本
└── README.md           # 项目部署说明文档

3.2 模型配置文件 config.json

支持双模型灵活切换，可根据服务器性能、数据隐私要求选择运行模式，同时限定最大迭代次数防止卡死。

{
    "ollama": {
        "use_model": false,
        "model_name": "llama3.1:8b",
        "temperature": 1.0,
        "max_iterations": 20
    },
    "openai": {
        "use_model": true,
        "model_name": "qwen-plus",
        "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "temperature": 1.0,
        "max_iterations": 20
    }
}

3.3 店铺优惠数据源 store_promotions.txt

系统业务数据载体，工具可读取文本内优惠规则，支撑价格核算业务。

店铺优惠政策：
1. 足球 - 购买足球即可享受9折优惠。
2. 羽毛球拍 - 任意购买羽毛球拍两支以上，享8折优惠。
3. 篮球 - 单笔订单满300元，篮球半价。
4. 跑步鞋 - 第一次购买跑步鞋的顾客可享受满500元减100元优惠。
5. 瑜伽垫 - 每购买一张瑜伽垫，赠送价值50元的瑜伽教程视频一套。
6. 速干运动衫 - 买三送一，赠送的为最低价商品。
7. 电子计步器 - 购买任意电子计步器，赠送配套手机APP永久会员资格。
8. 乒乓球拍套装 - 乒乓球拍套装每套95折。
9. 健身手套 - 满200元包邮。
10. 膝盖护具 - 每件商品配赠运动护膝一个。

注意：
- 所有优惠活动不可与其他优惠同享。
- 优惠详情以实际到店或下单时为准。

3.4 本地模型测试脚本 test.py

独立测试脚本，校验 Ollama 本地模型服务是否正常启动、接口能否正常收发数据。

import ollama
import requests
import json

base_url = 'http://localhost:11434/api/generate'

headers = {'Content-Type': 'application/json'}

payload = {
    "model": "llama3.1:8b",
    "prompt": "你好",
    "stream": False,
    "temperature": 0.8
}

response = requests.post(url=base_url, headers=headers, data=json.dumps(payload))

if response.status_code == 200:
    response_text = response.text
    data = json.loads(response_text)
    print("Raw response from Ollama API:", data)
    actual_response = data['response']
    print(actual_response)
else:
    print("Error:", response.status_code, response.text)

3.5 大模型客户端 op_llm_client.py

统一封装两类模型调用接口，上层业务无需区分模型类型，实现调用逻辑解耦，附带网络异常捕获机制。

import json
import requests

class OllamaClient:
    def __init__(self, base_url="http://127.0.0.1:11434"):
        self.base_url = base_url

    def chat_completions_create(self, model, messages, temperature=0.7):
        url = f"{self.base_url}/api/generate"
        headers = {'Content-Type': 'application/json'}
        payload = {
            "model": model,
            "prompt": self._format_messages(messages),
            "stream": False,
            "temperature": temperature
        }
        try:
            response = requests.post(url=url, headers=headers, data=json.dumps(payload))
            if response.status_code == 200:
                data = json.loads(response.text)
                return data['response']
        except requests.exceptions.ConnectionError:
            raise ConnectionError("本地Ollama服务连接失败，请检查服务状态")

    def _format_messages(self, messages):
        formatted_prompt = ""
        for message in messages:
            if message["role"] == "system":
                formatted_prompt += f"System: {message['content']}\n"
            elif message["role"] == "user":
                formatted_prompt += f"Human: {message['content']}\n"
            elif message["role"] == "assistant":
                formatted_prompt += f"Assistant: {message['content']}\n"
        return formatted_prompt.strip()

3.6 Agent 核心逻辑 agent.py

项目核心推理模块，通过系统提示词约束 ReAct 固定输出格式，维护会话上下文，自动适配双模型执行逻辑。

from op_llm_client import OllamaClient

class CustomerServiceAgent:
    def __init__(self, client, config):
        self.client = client
        self.config = config
        self.messages = []
        self.system_prompt = """
        You are a Intelligent customer service assistant for e-commerce platform. It is necessary to answer the user's consultation about the product in a timely manner. If it has nothing to do with the specific product, you can answer it directly.
        output it as Answer: [Your answer here].
        遵循Thought、Action、Observation推理流程，调用工具后根据返回数据整合最终答案
        """
        self.messages.append({"role": "system", "content": self.system_prompt})

    def __call__(self, message):
        self.messages.append({"role": "user", "content": message})
        response = self.execute()
        self.messages.append({"role": "assistant", "content": response})
        return response

    def execute(self):
        if isinstance(self.client, OllamaClient):
            completion = self.client.chat_completions_create(
                model=self.config["ollama"]['model_name'],
                messages=self.messages,
                temperature=self.config["ollama"]['temperature']
            )
            return completion
        else:
            completion = self.client.chat.completions.create(
                model=self.config['openai']['model_name'],
                messages=self.messages,
            )
            return completion.choices[0].message.content

3.7 全局调度入口 main.py

import json
import re
import os
from agent import CustomerServiceAgent
from op_llm_client import OllamaClient
from tools.query_product_data import query_by_product_name
from tools.calc import calculate
from tools.read_promotions import read_store_promotions
from openai import OpenAI
from dotenv import load_dotenv

load_dotenv()

def load_config():
    with open('config.json', 'r') as f:
        return json.load(f)

def get_client(config):
    if config['openai'].get('use_model', True):
        return OpenAI(api_key=os.environ.get("API_KEY"), base_url=config['openai']['base_url'])
    else:
        return OllamaClient()

def get_max_iterations(config):
    if config['ollama']['use_model']:
        return config['ollama']['max_iterations']
    elif config['openai']['use_model']:
        return config['openai']['max_iterations']
    return 10

def main():
    config = load_config()
    try:
        client = get_client(config)
        agent = CustomerServiceAgent(client, config)
    except Exception as e:
        print(f"模型初始化失败：{str(e)}")
        return

    tools = {
        "query_by_product_name": query_by_product_name,
        "read_store_promotions": read_store_promotions,
        "calculate": calculate,
    }

    while True:
        query = input("输入您的问题或输入 '退出' 来结束: ")
        if query.lower() in ['退出', 'exit']:
            break
        if not query.strip() or query.startswith('('):
            continue
        iteration = 0
        max_iterations = get_max_iterations(config)
        while iteration < max_iterations:
            try:
                result = agent(query)
                action_re = re.compile(r'^Action: (\w+): (.*)$')
                actions = [action_re.match(a) for a in result.split('\n') if action_re.match(a)]
                if actions:
                    action_parts = result.split("Action:", 1)[1].strip().split(": ", 1)
                    tool_name = action_parts[0]
                    tool_args = action_parts[1] if len(action_parts) > 1 else ""
                    if tool_name in tools:
                        try:
                            observation = tools[tool_name](tool_args)
                            query = f"Observation: {observation}"
                        except Exception as e:
                            query = f"Observation: 工具执行出错 {str(e)}"
                    else:
                        query = "Observation: 未查询到可用工具"
                elif "Answer:" in result:
                    print(f"客服回复：{result.split('Answer:', 1)[1].strip()}")
                    break
                else:
                    query = "Observation: 请输出规范指令或答复"
            except Exception as e:
                print(f"问题处理异常：{str(e)}")
                break
            iteration += 1
        if iteration == max_iterations:
            print("已达到最大推理次数，未能生成最终答复")

if __name__ == "__main__":
    main()

程序启动入口，负责加载配置、初始化实例、解析模型指令、循环调用工具，控制推理轮数避免程序异常。

3.8 业务工具模块

封装三类高频客服工具，与 Agent 推理逻辑分离，后续可直接新增工具拓展业务场景。

query_by_product_name：根据商品名称检索商品售价、库存信息

read_store_promotions：读取本地优惠文本，匹配对应商品优惠规则

calculate：结合商品原价与优惠比例，核算最终成交价格

四、系统业务运行实例

以用户实际咨询场景演示完整 ReAct 推理流程用户提问：店铺售卖足球吗？当前有什么优惠，下单最终需要花费多少钱？

1. Agent 推理思考：首先需要查询店铺内足球商品基础信息
2. 执行动作：Action: query_by_product_name: 足球
3. 观测数据：店铺在售足球，商品标价 120 元
4. Agent 推理思考：需要调取店铺优惠政策，查询足球专属折扣
5. 执行动作：Action: read_store_promotions: 足球
6. 观测数据：足球购买享受全场 9 折优惠
7. Agent 推理思考：结合原价与折扣，计算实际成交金额
8. 执行动作：Action: calculate: 120 * 0.9
9. 观测数据：核算后最终价格为 108 元
10. 生成答复：整合全部信息，输出标准化中文客服回复

全程无需人工干预，Agent 自动完成多轮推理与工具调用。

五、系统创新点与项目优势

1. ReAct 框架落地实践复刻人类思考办事逻辑，推理与行动相互配合，摆脱固定话术限制，适配多样化咨询问题。

2. 双模型兼容部署通义千问在线模型推理精度高，适配复杂咨询；Ollama 本地模型无网络依赖，保障业务数据隐私，按需切换灵活度高。

3. 真实业务数据支撑内置完整店铺优惠规则文件，贴合真实电商运营场景，项目落地实用性强。

4. 低耦合模块化架构配置、模型、Agent、工具各司其职，修改参数、新增业务功能不会影响原有程序运行。

5. 程序运行稳定性强添加多层异常捕获、最大推理次数限制，规避网络报错、指令异常、程序死循环等问题。

6. 轻量化简易部署无大型数据库、中间件依赖，仅安装基础第三方库，单条命令即可启动运行。

六、项目部署与运行教程

6.1 虚拟环境创建

conda create -n react_agent python=3.11
conda activate react_agent

6.2 项目依赖安装

pip install ollama==0.3.3 openai==1.45.0 python-dotenv requests==2.32.3

6.3 私密密钥配置

在项目根目录新建.env文件，填入个人大模型密钥

API_KEY=你的通义千问API密钥

6.4 本地模型连通测试

python test.py

6.5 启动智能客服系统

python main.py

七、总结与未来优化方向

本文基于 ReAct 推理行动框架，搭建完成兼具在线、离线双模式的电商 AI 智能客服 Agent。项目打破传统问答机器人局限，赋予大模型调用外部工具、自主拆解复杂问题的能力，能够独立处理商品查询、优惠解读、价格计算等日常客服业务，具备良好的学习参考价值与商业落地潜力。

后续可从多维度迭代优化项目：

1. 拓展工具类型，对接线上数据库、第三方物流 API，丰富业务场景
2. 增加长期记忆模块，留存历史会话记录，提升上下文关联理解能力
3. 优化流式输出效果，逐字返回答复内容，优化人机交互观感
4. 开发简易可视化界面，降低非技术人员操作使用门槛
5. 研发多 Agent 协同机制，分工处理咨询、售后、对账等不同业务

AI Agent 已然成为大模型产业落地核心形态，本项目从零完成框架搭建、代码开发、业务调试，为同类智能问答机器人开发提供完整可复用的开发范例。

---

创作不易，欢迎点赞收藏，评论区交流 AI Agent 开发相关问题～