用 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
    1. 双轨扩展 :同一 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

bash 复制代码
cp .env.example .env
# 编辑 .env,填入你己的 DEEPSEEK_API_KEY (不要提交真实密钥)
docker-compose up -d
docker-compose logs -f

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

3. 方式 B本开发

后端

bash 复制代码
cd backend
pip install -r requirements.txt
python run_dev.py

前端

bash 复制代码
cd frontend
npm install
npm run dev

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

4. 配置文件(无真实密钥)

公开 .env.example 形态类似:

env 复制代码
DEEPSEEK_API_KEY=sk-xxxxxxxx
LANGCHAIN_DEBUG=0
# LANGSMITH_API_KEY=...
# DATABASE_URL=sqlite:///./data/agent_app.db

5. 测试接口

bash 复制代码
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 可在支持该语法的编辑器中直接渲染。)

相关推荐
ZhengEnCi10 小时前
AI 读不懂你的代码怎么办:用高价值注释消除曲解、过度优化与上下文膨胀
aigc·ai编程
学无止境小袁同学13 小时前
LangGraph 深度指南
语言模型·框架·agent·并发·上下文·langgraph·长期记忆
爱查宝小二14 小时前
爱查宝降AIGC效果实测与过检能力展示
aigc
Cosolar14 小时前
2026 年 Java AI Agent 生态全景盘点:50+ Java 开源项目的分类、实测与选型判断
人工智能·架构·agent
花椒技术14 小时前
从“实时生成游戏”出发,我们用 AI 做了四次游戏开发尝试
人工智能·aigc·游戏开发
张一凡9315 小时前
你的 AGENTS.md,真的管到模型写代码了吗?
前端·后端·agent
qinglongcn15 小时前
怎么让 200 轮的长任务不崩——三层保全策略
agent·ai编程
花椒技术15 小时前
数字人为什么突然爆发?从 H3 Max Lip Sync 看生成式数字人的临界点
人工智能·aigc
小虎AI生活16 小时前
太好了!豆包终于接入了多模型,正面硬刚WorkBuddy
aigc·ai编程
数字工作台16 小时前
给 LangGraph 加一道可审计记忆:替换默认 Checkpointer,实现防篡改 + 崩溃不丢数据
python·agent