用 Vue 3 + FastAPI 跑通 LangChain DeepAgent：任务规划、双轨 Skills，以及可复现的本地 Agent 工作台

副标题（TL;DR）：这不是又一个「调一下 Chat API」的具 Demo而是一套把 DeepAgent 的规划、工具、官方 Skills、文件系统与会话持久化，装进 Vue 聊天界面的可运行工程。

阅读时间： 12 分钟｜适合Python / AI / Agent 工程师

公开仓库：github.com/liuyanqun08...

素材说明：全文仅依据该仓库已公开的 README / 设计文档 / 源码，不含任何本地私文件或真实密钥。

---

一、项目诞生景

它解决什么问？

很多人第一次接 Agent，会遇到同一类尬：

• 模能聊天，但会规划复杂任务；
• • 想加能力，只能改代码硬编码工；
• • 会话一关就丢，没有可管理的 Skills / 模型配置面。

langchain-deep-agent（仓库内称 DeepAgent Demo要做的是：给你一个看得、点得着」的 Agent 工台------左侧话、中间聊天、旁边型与技能管理，后端用 FastAPI + SQLite，核心智能用 LangChain 的 deepagents

为么传统方案不够好？

常见法	痛点
单页调 Chat Completions	没有规划、工具、记忆的统一壳
脚本跑 Agent	给非同事试，也难管理技能开关
只堆 Prompt	杂任务靠多写几句」撑不住

核心创新是什么？

两点很务实：

1. 产品化外壳：Vue 3 SPA + FastAPI REST，会话 / 消息 / 技能都进 SQLite
2. 2. 双轨扩展 ：同一 backend/skills/ 目录下，既能 Tools（skill.yaml → 可调用函数） ，又能挂 官方 Skills（SKILL.md → 渐进式披露） ，一起喂给 create_deep_agent。

可以把它成：给 DeepAgent 配了一间「前台接待室 + 工具柜 + 说明书书架」。接待室聊天 UI，工具柜是 Tools书架是 SKILL.md。

---

、先看整体架构必须有图）

用 Mermaid 把模块关系再画一遍（掘金也持）：

graph TB subgraph FE[前端 Vue 3 SPA] SL[SessionList 会话列表] CW[ChatWindow 聊天] SP[SkillPanel / ModelConfig] end subgraph API[FastAPI] R1["/api/sessions"] R2["/api/skills"] R3["/api/models"] R4["/api/agent/config"] AS[Agent 服务层] end subgraph DATA[数据与运行时] DB[(SQLite sessions/messages/skills)] REG[Skills 注册表] FS[文件系统 /skills /uploads /memories] DA[deepagents create_deep_agent] end SL --> R1 CW --> R1 SP --> R2 SP --> R3 SP --> R4 R1 --> AS R2 --> REG AS --> DA AS --> DB REG --> DA DA --> FS ``` ### 各层干（白话版） - **前端**：只负责展示与收集输，不碰数据库。 - **API 层**：校验请、调 service，返回 JSON。 - **服务层**：会话 CRUD、技能 CRUD、把用户消息交给 Agent 写回 assistant。 - **Agent 层**封装 deepagents------规、端文件系、长期记忆存储、tools / skills。 - **数据层**：SQLite 持久化会话与技元数据。 公开设计文档的职责划分，和码目录是对的：`routers/` 很薄，`services/` 做业务，`agent/` 才碰 DeepAgent。 --- ## 三、一次请求到底发生了什么 ```mermaid sequenceDiagram participant U as 用户 participant FE as Vue 前端 participant API as FastAPI participant Svc as agent_service participant AG as DeepAgent participant DB as SQLite U->>FE: 输入消息并发送 FE->>API: POST /api/sessions/{id}/messages API->>Svc: 加载历史与配置 Svc->>AG: 构建上下文并调用 Agent AG->>AG: Planner 拆分任务 / 调 Tools / 读 Skills AG-->>Svc: assistant 内容 Svc->>DB: 写入 user + assistant 消息 Svc-->>FE: 返回 assistant FE-->>U: 展示回复（可含理过程） ``` ### ①②③④⑤ 分步说明 1. **前端发 REST**：携带 `session_id` 与 `user_message`。 2. **服务层取上下文**：历史消 +（设上的）长期记忆片段 + 当前启用能。 3. **DeepAgent 执行**：Planner 决定否拆任务、是否调用工具或读 SKILL.md。 4. **落库**：用户句与助手句写 `messages`。 5. **前端染**：聊天区追加气泡仓库 README 还提到理过展示与文件上传。 启动还会先「热」一 Agent：公开的 `backend/main.py` 在 lifespan 里 `init_db` → 同步磁盘 skills `skill_registry.reload_from_db()` → `get_agent()`，避免第一聊天才冷启动。 --- ## 四、核心源码解析 公开仓库核心录可以样理解： ```text langchain-deep-agent/ ├─ frontend/ # Vue 3 + Vite + Naive UI ├── backend/ │ ├── main.py # FastAPI 入口 + lifespan │ ── config.py # 变与默认模型 │ ├── app/ │ │ ├── routers/ # sessions / skills / models / agent_config │ │ ├── services/ # 业务编排 │ │ ├── db/ # SQLModel + SQLite │ └── agent/ # factory / skills registry / sync │ └── skills/ # skill.yaml Tools + SKILL.md Skills ├── docs/ # REQUIREMENTS / TECHNICAL_DESIGN / SKILLS └─ docker-compose.yml ``` ### 4.1 应用入口：把「装技能」放进 lifespan ```python @asynccontextmanager async def lifespan(app: FastAPI): init_db() settings.skills_root_dir.mkdir(parents=True, exist_ok=True) sync_skills_from_disk() skill_registry.reload_from_db() get_agent() yield app = FastAPI(title="DeepAgent Demo", lifespan=lifespan) ``` **为什么存在**：Agent 依赖工具列表与 Skills 路径。启动时同步磁盘并 reload，比「第一次请求再拼」更稳。 **数据流**：磁盘 skills → DB / 注册表 → `create_deep_agent` 单例。 ### 4.2 factory：真正组装 DeepAgent 地方 公开文件 `backend/app/agent/factory.py` 是全文最值得读一块。 **第一层（小白）**：工厂函数像组装一台电脑------主板是模型，槽 tools，说明书目录是 skills，硬盘分区是 `/skills/`、`/uploads/`、`/memories/`。 **第二层程）**： - 用 `skill_registry.get_tools()` 拿可调 Tools - 描含 `SKILL.md` 的子录，到官方 skills 路径； - `CompositeBackend` 把本地 shell、技能目录、上传目录、记忆 store 挂到虚拟路径； - `create_deep_agent(model=..., tools=..., skills=[...], store=..., backend=..., checkpointer=...)`。 **第层（源码要点）**： ```python tools = skill_registry.get_tools() skill_paths = _get_skill_paths_for_agent() create_kw = dict( model=model, tools=tools, store=_store, backend=_make_backend, checkpointer=_checkpointer, ) if skill_paths: create_kw["skills"] = ["/skills/"] _agent_graph = create_deep_agent(**create_kw) ``` 注意：`skills=["/skills/"]` 传的是**后端拟路径**，不便一个宿主机对路径------这和 FilesystemBackend 的 `virtual_mode` 一致。 配或技更后走 `rebuild_agent()`： `reload_from_db()`，再重图，避免「开关能了但 Agent 握着旧工具表」。 ### 4.3 开发小坑：热重载别盯着 skills 目录 README 特写了：`run_dev.py` 以 `--reload` 启动，并**排除 `skills/`**则你从机路径添加技能复制文件时，uvicorn 会误重启，聊天中途被断。这是典型「工程节念更救命」的点。 --- ## 五、最重要的技术原理：双轨 Skills ### 三层解释法 **第层（小白）** Tools 像**钻**：真的能在上打洞。 Skills（SKILL.md）像**说明书**：告诉 Agent「什么时候该拿电钻、按哪几步」。 渐进披像「先看目录再翻文」------读 frontmatter 的 name/description，匹配到任务才加载全文，省上下。 **第二层（工程** | | Tools（本目） | Skills（官方 SKILL.md） | |--|----------------|-------------------------| | 清 | skill.yaml | SKILL.md | | 用途 | 注可调用函数 | 提供说明与步骤，按需读 | | 加 | DB + 注册表 → `tools=[...]` | 目录路径 → `skills=[...]` | | 动态添加 | 本地子录 / GitHub `skills/*` | 放好 SKILL.md 后 rebuild | 同一 `backend/skills/` 下可以者共，**同时生效**。 **第三层（源 / 规）** - `type: python` 的 skill.yaml：`entry_point` 形如 `块名:函数`。 - `type: http`：用内置 HTTP 工具，config 里写 url/method。 - 官方 Skills 遵循 [Agent Skills 规范](https://agentskills.io/specification)；DeepAgent 文档见 LangChain DeepAgent Skills。 - GitHub 导：仓库需有 `skills/`，系统把 `repo/skills/*` 复制到本地 skills 根录，为每个技能独立录（可单独开关）。 > Embedding / RAG 不本仓第一的主线；设计文档写长期记忆第一版可是「SQLite + 文本」或简 embedding，后再换独立向量。文不编检索迟或召回率。 --- ## 六、性能优化与工程实践 下列对比来自公开文档与代码图，**不是压测数据**： | 优化点 | 原方案风险 | 程做法 | 原因 | |--------|-----------|---------|------| | 热重载 IO | 视整个 backend | `--reload-exclude skills/*` | 避免复制技能触发重启 | | Agent 冷启动 | 首请求才 create | lifespan 预热 `get_agent()` | 降低首包等待 | | 技能更 | 旧 tools 残留 | `rebuild_agent()` | 配置与运行时一致 | | 调试噪音 | 全程 verbose | `APP_DEBUG` / `LANGCHAIN_DEBUG` 开关 | 生产认静 | | Shell 后 | 任意命令风险 | 文档标明仅地开发，生产需沙箱/HITL | 安全界清 | | 密 | 写进仓库 | `.env` / 环境变量，示用占位符 | 不落真实密钥 | | 并发、缓存、CPU 占用等量化指，公开材料未给出数------这里不强行「优化了 X%」。 --- ## 七、手把手复现 ### 1. 环境准备 - Docker（推荐），或本机 Python 3.x + Node.js - 克隆公开仓： ```bash git clone https://github.com/liuyanqun0815/langchain-deep-agent.git cd langchain-deep-agent

2. 方式 A：Docker Compose

cp .env.example .env
# 编辑 .env，填入你己的 DEEPSEEK_API_KEY （不要提交真实密钥）
docker-compose up -d
docker-compose logs -f

按 README：Compose 会拉前后端具体端口以你本机 compose 映射为。

3. 方式 B本开发

后端

cd backend
pip install -r requirements.txt
python run_dev.py

前端

cd frontend
npm install
npm run dev

前端通常通过 Vite /api 理到 http://127.0.0.1:8000。

4. 配置文件（无真实密钥）

公开 .env.example 形态类似：

DEEPSEEK_API_KEY=sk-xxxxxxxx
LANGCHAIN_DEBUG=0
# LANGSMITH_API_KEY=...
# DATABASE_URL=sqlite:///./data/agent_app.db

5. 测试接口

curl http://127.0.0.1:8000/api/health

预期：{"status":"ok"}。随后在 UI 新建会话、发一句「你好」，再试 Skills 面板启用/禁用。

6. 常见错误

• 模型连上 ：检查 API Key 与 DEFAULT_MODEL，用「测试模型」接口查。
• • 技后服务狂重启 ：确认用的是 run_dev.py 或手动 --reload-exclude=skills/*。
• • 技能不生效 ：看是否需要 rebuild_agent / 重启；SKILL.md 是否在子目录根下。
• • PowerShell 展开通符：README 提醒直接写 uvicorn 时注意 exclude 写法。

---

八、总与思考

值得学习

• 把 Agent 能力产品化：会话、模型、能都有界面与 API而不是藏在 notebook。
• • 双扩展模型：可执行 Tools + 可披露 Skills齐官方 DeepAgent 能力边界。
• • 启动与热更：lifespan 预热、registry reloadreload-exclude，都是能直接的工习惯。

存在不足 / 适用界

• 记忆与向检索设计里仍偏第一版可简化」，重 RAG 场另接向量库。
• • LocalShellBackend 明确偏本地开发，上生产必须换沙箱人工审批。
• • 多用户鉴权在设计文档中标为后项当更像单机工作。

一句启发

正好用的 Agent 项目，往往不是 Prompt 写得更长，而是把「规划、工具、说明书、会话」做成可关、可持久、可给别人点的系统。

---

如果你在用 DeepAgent / LangChain 做办公助手，迎直接看源码并 Star：

github.com/liuyanqun08...

（图为本配套示意图；发布到掘金时会一并上传。Mermaid 可在支持该语法的编辑器中直接渲染。）