AgentDesk｜带人工审批的客服工具调用智能体

AgentDesk 是一个用 FastAPI（后端）+ React/TypeScript（前端）编写的客服支持智能体示例项目。它的重点不在“聊天”，而在于把工具调用与人工审批闸门串成一条可测试的流程：读取类工具（查订单、查工单、查知识库）即时执行；写入类工具（创建工单）只生成挂起的审批记录，必须由人批准后才真正写入数据库。

本文为待审核草稿，内容依据项目 README 与仓库元数据整理。作者自述的测试、评测与性能数据均未在本站复现，标为“作者自述”，请以实际运行结果为准。

• 角色设定：项目定位为“不只会聊天、还能通过工具行动”的 AI 支持坐席；所有写操作都设有人工审批闸门。
• 原始系统提示词：README 中未给出完整的系统提示词原文，也未给出可直接复用的提示词模板；此字段待核验（需查阅仓库代码中 provider / prompt 相关文件确认）。
• 需要注意，项目自述“意图路由是确定性规则”而非由大模型自由规划，因此其行为并不完全由一段提示词决定。

• 四种工具：order_lookup（订单查询）、ticket_status（工单状态）、kb_search（知识库检索）为只读即时执行；ticket_create（创建工单）为写操作，始终先进入待审批状态。
• 人工审批回路：写操作生成 pending 审批记录，批准后只执行一次，拒绝则丢弃；重复处理返回 409。
• RAG 知识库：内置若干客服文档，切块后做向量化检索并附带 [DOC-ID] 引用；示例离线使用哈希向量，生产路径可换 OpenAI 向量或 pgvector。
• 多 LLM 提供方切换：通过 LLM_PROVIDER 在 fake（离线确定性）、openai、ollama 之间切换；失败时按重试与回退链降级。
• 流式输出：提供 SSE 接口，按 meta → token → done 推送。
• 鉴权与错误封装：/api 路由要求 X-API-Key；错误统一为带 request_id 的错误信封。
• 离线评测与测试：作者称有 24 条离线评测用例与一套 pytest 测试，结果为其自述数据，未在本站复现。

• 作者自述公共演示运行在本地 Ollama llama3.2:1b 上（无需 API Key、不外呼）。
• README 明确写道：该 1B 模型在工具调用 JSON 上表现不可靠，因此意图路由改由确定性规则完成，模型只负责知识库问答与开放闲聊的措辞。
• 也可配置 LLM_PROVIDER=openai 使用 OpenAI Chat Completions 路径；具体所需模型名、版本与额度要求：待核验。
• 离线测试与评测使用“fake provider”（规则路由 + 模板拼装），它不是大模型。

• 后端：Python（README 使用 python3 -m venv + requirements.txt），Web 框架 FastAPI，数据库可选 SQLite 或 Postgres。
• 前端：Node.js + npm ci，Vite 构建 React/TypeScript 界面。
• 容器化：提供 Dockerfile 与 docker-compose.yml，可组合 Postgres 16 + pgvector。
• 具体的最低 Python / Node 版本号、内存与显存要求：README 未列出，待核验。

• 源码仓库：GitHub 上的 Shraddhameduri/agentdesk（本文不附作者前缀，请自行按原名检索）。
• 是否提供发行包、镜像或包管理器安装方式：README 未说明，待核验。
• 作者提供的公共演示地址经 localhost.run 隧道暴露，重连后会变化；该地址的可用性与长期稳定性待核验，不建议依赖。

来源：https://github.com/Shraddhameduri/agentdesk

许可证：未声明，转载与再分发权限待核验

依据 GitHub 原始资料由 AI 整理的中文待审核草稿，未经本站实测。原始版权与许可归原作者；未声明许可不代表允许转载或再分发。

来源类型：GitHub；授权范围待核验

• 学习“工具调用 + 人工审批闸门”这类客服智能体的工程结构。
• 作为企业内部客服/售后助手的原型骨架，替换种子数据与知识库文档后做二次开发。
• 教学与评测：离线 provider 便于在无网络、无密钥环境下演示完整链路。

以下命令均摘自 README，未经本站实际执行验证：

本地（无 Docker、无密钥）：

cd agentdesk
python3 -m venv .venv && .venv/bin/pip install -r backend/requirements.txt
API_KEY=demo-key LLM_PROVIDER=fake .venv/bin/python -m uvicorn app.main:app \
  --app-dir backend --host 127.0.0.1 --port 8000

Docker Compose（Postgres + pgvector）：

cd frontend && npm ci && VITE_DEMO_MODE=true npx vite build && cp -r dist ../backend/static && cd ..
docker compose up --build

主要配置项：LLM_PROVIDER（fake / openai / ollama）、API_KEY、DEMO_MODE，以及重试相关的 PROVIDER_MAX_RETRIES。完整的 .env 变量清单以仓库为准，待核验。

• 许可证未声明：仓库元数据中 license 为 null，README 也未给出许可条款。因此不得默认允许转载、修改再分发或商用，使用前须联系作者确认，此点待核验。
• 作者自述的取舍：不依赖 LangChain/LangGraph，采用显式状态机；pgvector 路径仅完成配置，未做压力测试；鉴权是共享 API Key，不适合多租户生产；会话记忆仅保留约 10 条消息。
• 评测与性能数据（如 p50/p95 延迟、测试通过数）均为作者在其环境下的自述结果，本站未实测复现。
• 国内网络环境下能否拉取依赖、访问 Ollama 模型下载源：待核验。
• 演示用 API Key（如 demo-key）与种子数据仅适合本地试用，不可用于真实生产。
• 本项目为第三方开源项目，本站整理内容不代表原作者官方中文文档。