智扫通机器人智能客服 Agent

项目简介

面向扫地 / 扫拖机器人的 RAG + 多工具 Agent + Harness 控制层 系统。项目不仅覆盖知识库问答、天气与环境适配、用户设备使用记录查询、个性化报告生成，还把 Agent 生产化中常见的可控性问题纳入架构：统一状态、预算停止、动态工具策略、真实人工审批、答案验证、artifact 留存、诊断 trace、评测门禁和服务化交付。

ReactAgent 负责 ReAct 推理和工具调用，AgentRunner 负责请求级控制；工具、RAG、MCP、审批、artifact、trace、metrics 都围绕 Harness 形成可治理的 Agent 运行框架。

核心功能

RAG 知识库：从 PDF / TXT 构建 Chroma 向量库，Dense 向量分数与中文 BM25 双路召回，经 RRF 融合与可选 Cross-Encoder 精排后生成 evidence 与引用。
多工具 Agent：支持知识库检索、天气、用户位置、用户 ID、当前月份、使用记录查询和报告上下文切换。
Harness 控制层：统一 AgentRunner / AgentState，支持预算停止、动态工具策略、真实审批、答案验证、artifact 存储和诊断 trace。
动态工具治理：ToolRegistry 管工具元数据，ToolPolicy 从版本化 YAML 加载 tenant / role / scene / tool / args 规则，输出可审计的 allow / deny / need_approval / need_redaction 决策。
真实 HITL 审批：敏感工具进入 SQLiteApprovalStore，普通用户需审批，operator / admin 可审批。
答案质量闸门：AnswerVerifier 依次执行结构校验、Claim-Evidence 对齐与危险结论检测，仅在高风险或低置信时调用 LLMJudge。
产物留存：SQLiteArtifactStore 按 request_id 保存 final answer、verification failure、evidence、tool results 等运行产物。
MCP 工具服务：支持 JSON-RPC initialize、tools/list、tools/call；MCP 工具调用同样经过 ToolPolicy 和审批存储。
可观测性：包含 request / tool / model trace、diagnostic event、OpenTelemetry 风格 span、Prometheus 指标，以及带序号、心跳、背压和断线重放的实时 SSE 事件流。
评测门禁：PR 运行 30 条冻结真实检索排名和 62 条离线 Agent golden，校验固定阈值与相对基线退化；真实模型评测由独立工作流定期执行。

系统架构

整体分为四个层面：

执行面：ReactAgent、LangChain ReAct、工具、RAG、数据服务。
控制面：AgentRunner、AgentState、Budget、ToolPolicy、审批、Verifier、Artifact、Diagnostic Trace。
接入面：FastAPI（/chat、/chat/stream、/harness/run、审批、artifact、MCP、trace、metrics、judge）、Streamlit、MCP stdio / HTTP。
治理面：API Key 鉴权、租户 / 角色 / principal 可信上下文、限流、Prompt Injection 检测、metrics、trace、评测门禁。

个人负责

整体架构设计与执行 / 控制 / 接入 / 治理四层拆分。
RAG 双路召回、RRF 融合与 Cross-Encoder 精排链路。
Harness 控制层：AgentState 状态机、Budget、动态工具策略、审批、Verifier、Artifact、Trace 整套实现。
ToolPolicy 版本化 YAML 规则引擎和可审计决策输出。
MCP JSON-RPC 服务与 fetch_external_data 等敏感工具的审批门。
FastAPI 全部 HTTP / SSE 接口、事件序号与断线重放。
Prometheus / OpenTelemetry 风格 metrics、trace 采集。
评测门禁：检索排名冻结集 + Agent golden，CI 阈值与基线比对。

项目价值

项目重点解决 Agent 生产化过程中普遍存在的可控性问题：让工具调用、审批、答案验证、观测、评测都成为可治理的一等公民，而不是散落在应用代码里的旁支能力。