NOTES · 学习笔记
Agents on Duty 项目完整体验
项目地址:https://github.com/Keviniscool-boy/agents-on-duty
最近在做 Agents on Duty,一个面向客服场景的 Agent 项目。
相比单纯让 Agent 回答问题,我更想尝试让它真正参与业务流程:能够查询订单、受理退款申请、检索知识库,并在需要人工判断时暂停流程或创建工单,交由客服继续处理。
这篇文章记录了项目的完整体验过程,包括环境搭建、主要功能、Agent 的协作方式,以及我在开发过程中对业务流程和工程实现的一些理解。
项目目前仍以演示数据为主,距离真实的生产客服系统还有一定差距。下面从实际运行开始,介绍这个项目。
一、准备环境
先把项目克隆到本地,再进入项目目录。
git clone https://github.com/Keviniscool-boy/agents-on-duty.git
cd agents-on-duty配置模型与数据库
打开 PowerShell,在项目目录中操作。
在项目目录复制 .env.example 为 .env。
打开 .env,填写聊天模型、Embedding、MySQL 密码和 JWT_SECRET_KEY。
文章只展示需要填写的变量名,不展示实际密码或 JWT_SECRET_KEY。大家在自己的 .env 中填写各自的值。
我这次使用 GPT-5.6-Luna 作为聊天模型,并使用阿里云的 qwen3.7-text-embedding-flash 生成知识库向量。
我准备了一枚临时体验 Key,供大家试用;使用前请留意它的有效期和可用额度。
这枚 Key 用于 DashScope 的向量模型配置,填入 .env 的 DASHSCOPE_API_KEY。
Embedding 模型用于生成向量;qwen3.7-text-rerank 是重排模型,作用不同,是否配置取决于项目当前设置。
MySQL 普通用户和 root 账户建议使用不同密码。
请为 JWT_SECRET_KEY 生成足够长、难以猜测的随机字符串,并写入本地 .env。
在项目目录运行以下命令,构建并启动项目。
DASHSCOPE_API_KEY=sk-ws-H.YLPMDLH.4f9A.MEUCIQDYqSMVDHYRxj0km4NDueULrXxxYL6ytc6ZZp_tGdgO0AIgeDy09pZUElIdgPNk-7wKH4ZGyAGefjWfp5oocZ7dm90启动后,先确认 app、frontend、mysql 和 redis 服务均正常,再继续操作。
docker compose up --build -d二、登录并查看演示数据
服务正常后,访问 http://localhost:8080,注册一个普通账号并登录。
登录后打开“订单售后”,查看当前账号的演示订单。
记下页面显示的订单号,后面用它测试订单查询和退款申请。
三、准备管理员和客服账号
注册账号后,在 PowerShell 中将下方的 <用户名> 替换成你刚注册的账号;运行时去掉尖括号,以该账号授予管理员角色:
docker compose exec app python -m auth.bootstrap_admin <用户名>如果还要体验客服工作台,可以再注册一个独立账号。管理员登录后,在管理员工作区把这个账号的角色设为“客服”。bootstrap_admin 命令授予的是管理员角色,不要用它来创建客服账号。
四、按系统流程体验主要功能
下面从普通用户和客服的视角,看看项目里可以实际体验哪些功能。
如果问题超出客服业务范围,系统会提示用户咨询订单、售后或知识库相关内容。
订单查询
用户可以查询当前账号的演示订单,也可以按订单号查询指定订单。每个账号只能查看自己的订单,查询结果会以订单卡片展示。
订单状态与物流信息
用户可以在“订单售后”查看自己的订单号,再在聊天中询问订单状态。当前演示订单不一定包含物流轨迹;如果没有相关数据,系统会说明暂无物流信息,不会编造轨迹。项目尚未连接真实物流平台。
我用订单号查询后,页面会同时显示 Agent 的文字回复和结构化订单卡片。
退款审核与流程恢复
用户可以提交退款申请,由客服批准、拒绝或要求补充信息。要求补充信息时,用户提交后申请会回到待审核状态;这里演示的是申请和审核,不会实际退款。
转人工与工单
用户发送“转人工”或“找人工”后,系统会创建客服工单并返回编号和状态。客服或管理员可以在工作台回复、更新状态,用户则在“订单售后”的“我的工单”中查看进度和回复。工单用于跟踪客服处理,不代表提交给管理员审批。
知识库问答
知识库 Agent 使用 RAG(检索增强生成):系统先从当前有效的知识文档中检索相关片段,再把检索结果交给模型组织回答,并展示来源。资料不足或知识库不可用时,系统会说明无法确认,并引导用户转人工。
五、这套 Agent 是怎么协作的
一次请求会经过浏览器、FastAPI 和 LangGraph:浏览器负责聊天和展示进度,FastAPI 处理登录、权限和业务接口,LangGraph 将请求送到合适的节点。模型参与理解和生成,订单、退款和工单状态由业务工具与存储层处理。
我选择 LangGraph,是因为客服流程里有明确的等待和恢复步骤。普通问答可以直接走到回答;退款需要人工审核时,流程会在检查点暂停,等客服处理后从保存的位置继续。
整体架构与请求路由
用户发来消息后,Supervisor 会先看能不能用确定规则判断。像“你好”“找人工”“查询订单号”这类明确请求,可以直接进入对应节点;不确定的问题再交给模型做意图分类。这样做是为了让明确的业务动作更稳定,也少让简单请求多走一次模型调用。
各业务节点如何分工
问候和超出服务范围的问题由 fallback 返回固定提示。订单查询、退款申请和工单由 ticket_handler 处理;政策类问题交给 knowledge_rag 检索资料。普通业务答复还会经过合规检查和最终整理。退款申请需要人工判断时,流程会进入 human_review 并暂停,等待客服作出决定。
订单、退款与工单:工具调用和业务边界
ticket_handler 可以通过 MCP 调用订单、退款和工单工具。如果 MCP 服务暂时不可用,系统会尝试本地备用工具。当前订单和退款是按用户隔离的演示数据;创建退款申请或工单时,用户身份由服务端注入,模型不能替用户指定其他账号的 ID。
退款与工单的幂等处理
退款申请和人工工单都会考虑重复提交。用户重试或网络抖动时,系统尽量返回已有的申请或工单,而不是再造一份。用户身份、会话号和幂等信息由服务端提供,模型不负责决定这些安全字段。
合规检查在回答前做什么
业务回答会先经过规则检查,识别手机号、身份证号、银行卡号、邮箱等隐私信息和固定禁词。需要时再调用合规模型补充判断;模型最多等待 15 秒,超时或异常时按规则结果继续,并记录降级状态。问候、固定兜底和确定性转人工回复仍做规则检查,但跳过合规模型调用。
退款申请和转人工工单是两类不同的处理流程。退款申请进入退款审核队列;客服作出决定后,聊天中暂停的 LangGraph 流程会恢复。转人工则创建普通客服工单,客服在人工工单队列里回复和更新状态,用户在“我的工单”查看。两类队列分开,避免把“申请退款”和“找客服”混成一种状态。
MCP 把 Agent 可调用的工具接口和具体业务实现分开。Agent 根据用户需求选择工具,服务端负责校验身份、补齐请求参数,再把工具结果交回工作流。MCP 服务断开时,本地备用工具可以接手;两条路径复用幂等存储,降低网络重试带来的重复操作。
知识库问答:RAG 检索与引用
知识库问答使用 RAG:系统先通过 FAISS 向量检索和关键词检索召回片段,再融合排序,把相关内容交给模型组织回答,并展示来源。检索会排除未发布或已过期的文档;资料不足、内容冲突或知识库不可用时,系统会说明无法确认并引导用户转人工。RAG 提供核对线索,但不能保证知识语料本身正确。
退款审核:流程暂停与恢复
聊天里发起退款并创建待审核申请后,流程会在 human_review 节点暂停。LangGraph 的 SQLite checkpointer 保存当时的状态,客服决定后通过 resume 恢复执行。系统还用发件箱记录待恢复动作,避免客服决定已经保存、但一次恢复失败就丢掉处理结果。售后页面直接提交的退款申请是独立申请,不会关联到某条聊天线程。
权限与运行记录
项目使用普通用户、客服和管理员三种角色。前端按角色显示入口,后端再次校验权限;普通用户只能查看自己的订单、退款和工单。每个请求带有 trace ID,可串起节点、模型和工具调用,并查看耗时与降级路径。审计记录保存操作类型和结果,不把聊天正文当作审计日志。
数据存储与部署
当前账号、演示售后数据、工单幂等记录和 LangGraph 检查点使用 SQLite;Redis 用于会话相关热数据,MySQL 为工作上下文提供持久化和降级路径,知识向量索引保存在 FAISS。项目目前以单机 Docker Compose 运行,运行指标保存在进程内,服务重启后会清零。不同存储的数据需要分别备份。
MySQL 中查看到的三张表
截图列出了 short_term_messages、working_memory_context 和 working_memory_history 三张表。
Pi 在知识库里的实验
我也把 Pi Agent 框架用在知识库问答的独立实验中。这个实验使用 Pi Agent Core 和 Pi 的模型接入层,让 Agent 按问题调用 knowledge_search,通过现有知识服务检索资料,再根据检索结果组织带来源的回答。这样我可以比较通用 Agent loop 在多轮检索和引用回答上的表现。它目前没有替换主业务里的 LangGraph:退款审批、人工接管与恢复、权限和工单状态仍由现有业务流程负责;Pi 实验也不直接访问这些业务状态。
六、我重点验证了哪些地方
我用普通用户和客服两个角色走过转人工闭环:用户发起请求后拿到工单号,客服在工作台回复并更新状态,用户再回到“我的工单”查看结果。普通用户不能打开运维接口;退款审核和人工工单也分别进入不同队列。
我还模拟过后端暂停,确认聊天失败时用户消息会保留,并出现重试入口。合规模型超时后会按规则检查结果继续处理;MCP 调用失败时则会尝试本地工具。它们解决的是流程失败后的恢复问题,不代表外部服务永远可用。
在本机 Docker Compose 单实例环境里,我分别测了 5 次问候和转人工:
问候:5 次,819–952 毫秒。
转人工:5 次,734–831 毫秒。
这组结果只用于观察当前本机环境,不代表生产环境性能。订单查询会调用模型整理回复,因此不与这两项固定流程的耗时作比较。
我把回归测试按问题分类:权限矩阵检查不同角色的访问范围,工单测试检查重复请求和跨用户隔离,合规测试检查模型超时后的行为,前端测试检查 Markdown 注入和订单卡片数据来源;浏览器双角色实测则串起用户建单、客服处理、用户查看状态的流程。项目也有后端 pytest、前端测试和构建检查。部分后端用例依赖独立 MySQL 环境,测试报告会标明跳过原因。这些测试证明已覆盖的路径按预期工作,但不能替代真实用户量、真实订单和真实物流系统的验证。
七、目前还不是生产客服系统
项目用演示订单和退款验证 Agent 与业务流程的衔接,没有接入真实支付、订单或物流平台;知识库也只覆盖项目内的政策文档。退款审批通过不代表实际退款。
项目目前按单机 Docker Compose 运行,账号、售后数据和 LangGraph 检查点存放在 SQLite,运行指标保存在进程内,服务重启后会清零。多副本部署、真实业务数据权限、知识文档运营和更完整的审计仍需完善。Pi 知识助手是独立实验,不参与主业务中的退款和权限处理。