# langchain-deepagent

**Repository Path**: chijunqiang/langchain-deepagent

## Basic Information

- **Project Name**: langchain-deepagent
- **Description**: 基于langchain的deepagent，智能问答智能体
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-03-23
- **Last Updated**: 2026-05-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Deep Agent 智能问答助手

基于 LangChain DeepAgent 的多轮对话智能助手，支持 Docker Sandbox 隔离环境执行 Skill 脚本。

## 项目概述

Deep Agent 是一个智能问答助手系统，提供以下核心能力：

- **多轮对话**：支持上下文关联的多轮对话，自动记忆历史记录
- **意图识别**：自动识别用户意图，补充不完整的问题输入
- **问题扩展**：回答后自动生成后续追问建议
- **技能扩展**：通过 Skill 系统扩展 Agent 能力，支持自定义脚本执行
- **技能库管理**：Web 界面管理技能，支持异常检测
- **沙箱隔离**：使用 Docker 容器隔离执行脚本，保障系统安全
- **会话持久化**：支持 MySQL 数据库存储会话历史，也可降级到内存存储
- **流式输出**：支持 SSE 流式响应，提升用户体验

## 架构设计

```mermaid
flowchart TB
subgraph Client[👤 用户端]
  direction TB
  A[Web Browser] --> B[HTTP Request]
end

subgraph App[📦 agent-api :8001]
  direction TB
  C[FastAPI Server] --> D[Deep Agent]
  D --> E[DockerSandboxBackend]
end

subgraph DB[🗄️ MySQL :3306]
  direction TB
  J[(MySQL 8.0.45)]
end

subgraph Sandbox[🔒 Sandbox]
  direction TB
    subgraph Skills[🔧 Skills 技能库]
    direction TB
        F[query-time]
        G[check-storage]
        I[其他技能...]
  end
  K[ /workspace] 
  L[ /session-A]
  M[ /session-B]
  N[ /session-N]

end

%% 连接线
D --> Skills
K --> N
K --> L
K --> M
B --> C
E --> K
C --> J

%% 样式定义
classDef client fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#0d47a1
classDef app fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
classDef skill fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
classDef db fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#e65100
classDef sandbox fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#880e4f
classDef skills fill:#dcdde1,stroke:#00a8ff,stroke-width:2px,color:#1e272e

%% 应用样式
class A,B client
class C,D,E app
class F,G,I skill
class J db
class K,L,M,N sandbox
```

**请求流程：**

```mermaid
sequenceDiagram
    participant U as 用户
    participant A as agent-api
    participant I as Intent Agent
    participant Q as Extension Agent
    participant S as sandbox
    participant D as MySQL
    U ->> A: POST /chat/stream (message)
    A ->> D: 获取会话历史
    D -->> A: 返回历史消息
    A ->> I: 意图识别（并行）
    A ->> A: Agent 处理请求
    A ->> S: 在 /workspace/{session_id} 执行脚本
    S -->> A: 返回执行结果
    A ->> Q: 生成后续问题（并行）
    A ->> D: 保存会话消息
    A -->> U: SSE 流式返回响应
```

## 功能说明

### 1. 智能对话

- 支持自然语言交互，自动调用合适的 Skill 完成任务
- 多轮对话记忆，理解上下文
- 流式输出支持，实时返回响应
- Markdown 渲染，支持代码高亮

### 2. 意图识别

自动识别用户输入是否完整：
- **不完整输入**：缺少主语、宾语、指代不明等 → 自动补充
- **完整输入**：表述清晰、主谓宾完整 → 保持原样

### 3. 问题扩展

回答后自动生成 3-5 个相关追问建议，帮助用户深入了解主题。

### 4. 会话管理

- 自动创建和恢复会话
- 会话历史持久化存储
- URL 分享会话（`#c=conversation_id`）
- 支持查询和删除会话

### 5. 技能库管理

Web 界面管理技能：
- 新增/编辑/删除技能
- 上传 Python/Shell 脚本
- 脚本在线测试
- **异常检测**：自动检测目录名与 SKILL.md 中 name 字段不一致

### 6. 沙箱隔离

- 固定沙箱容器，避免频繁创建/销毁
- 会话级别目录隔离：`/workspace/{session_id}`
- 资源限制（CPU、内存）
- 网络隔离（可选）

## API 接口

### 聊天接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/chat` | 发送消息（同步） |
| POST | `/chat/stream` | 发送消息（流式 SSE） |

### 会话接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/conversations` | 获取会话列表 |
| GET | `/conversations/{id}` | 获取会话详情 |
| DELETE | `/conversations/{id}` | 删除会话 |

### 技能库接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/skills` | 获取技能列表 |
| GET | `/api/skills/{name}` | 获取技能详情 |
| POST | `/api/skills` | 创建技能 |
| PUT | `/api/skills/{name}` | 更新技能 |
| DELETE | `/api/skills/{name}` | 删除技能 |
| POST | `/api/skills/{name}/scripts` | 添加脚本 |
| DELETE | `/api/skills/{name}/scripts/{script}` | 删除脚本 |
| POST | `/api/skills/test-script` | 测试脚本 |

### 其他接口

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/` | Web 界面 |
| GET | `/health` | 健康检查 |
| GET | `/api` | API 信息 |

## 参数配置

### 核心配置

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `OPENAI_API_KEY` | - | OpenAI API 密钥（必填） |
| `OPENAI_BASE_URL` | `https://api.openai.com/v1` | API 基础地址 |
| `MODEL_NAME` | `gpt-4` | 使用的模型名称 |

### 数据库配置

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `DB_HOST` | `mysql` | 数据库主机地址 |
| `DB_PORT` | `3306` | 数据库端口 |
| `DB_USER` | `root` | 数据库用户名 |
| `DB_PASSWORD` | `root123` | 数据库密码 |
| `DB_NAME` | `deep_agent` | 数据库名称 |
| `RETENTION_DAYS` | `90` | 会话数据保留天数 |

### 沙箱配置

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `USE_SANDBOX` | `true` | 是否启用沙箱 |
| `SANDBOX_IMAGE` | `deepagent-sandbox:latest` | 沙箱镜像 |
| `SANDBOX_TIMEOUT` | `60` | 执行超时时间（秒） |
| `SANDBOX_MEMORY_LIMIT` | `256m` | 内存限制 |
| `SANDBOX_NETWORK_DISABLED` | `true` | 是否禁用网络 |

### 其他配置

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `SKILLS_PATH` | `./skills` | Skills 目录路径（宿主机） |
| `SKILLS_DIR` | `/app/skills` | Skills 目录路径（容器内） |
| `LOG_LEVEL` | `INFO` | 日志级别 |

## 服务启动

### 前置要求

- Docker Engine 20.10+
- Docker Compose v2.0+

### 快速启动

1. **克隆项目**

```bash
git clone <repository-url>
cd langchain-deepagent
```

2. **配置环境变量**

```bash
cp .env.example .env
```

编辑 `.env` 文件，设置必要的配置：

```bash
# 必填项
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.openai.com/v1
MODEL_NAME=gpt-4

# 数据库密码
DB_PASSWORD=your-password
```

3. **启动服务**

```bash
docker-compose up --build -d
```

4. **查看状态**

```bash
docker-compose ps
```

预期输出：

```
NAME                    STATUS    PORTS
agent-api               running   0.0.0.0:8001->8001/tcp
mysql8                  running   0.0.0.0:3306->3306/tcp
sandbox                 running
```

### 服务管理

```bash
# 查看日志
docker-compose logs -f agent-api

# 停止服务
docker-compose down

# 停止并删除数据
docker-compose down -v

# 重启服务
docker-compose restart

# 重建镜像
docker-compose build agent-api && docker-compose up -d agent-api
```

## 技能开发

### 技能目录结构

```
skills/
└── my-skill/              # 技能目录名（必须与 name 字段一致）
    ├── SKILL.md           # 技能描述文件
    └── scripts/           # 脚本目录
        ├── main.py        # Python 脚本
        └── check.sh       # Shell 脚本
```

### SKILL.md 格式

```markdown
---
name: my-skill
description: 技能描述
---

## 技能内容

详细描述技能的使用方法和注意事项...
```

### 异常检测

系统会自动检测以下异常：
- 目录名与 `SKILL.md` 中 `name` 字段不一致

异常技能会在列表中显示警告标识，提示修改。

## 常见问题

### 1. 前端样式加载失败

确保重建镜像后启动：
```bash
docker-compose build agent-api && docker-compose up -d agent-api
```

### 2. 数据库连接失败

应用会自动降级到内存存储模式，日志中会显示警告：
```
数据库连接失败: ...
已启用内存存储降级模式
```

### 3. API 调用失败

检查 API Key 和 Base URL 配置：
```bash
curl http://localhost:8001/health
```
确认 `agent_ready` 为 `true`。

### 4. Skill 执行失败

检查沙箱容器是否正常运行：
```bash
docker ps --filter "name=sandbox"
```

## 技术栈

| 组件 | 技术选型 |
|------|---------|
| Web 框架 | FastAPI |
| AI Agent | LangChain DeepAgent |
| 状态管理 | LangGraph |
| 沙箱隔离 | Docker SDK for Python |
| 数据库 | MySQL (aiomysql) |
| LLM | OpenAI API Compatible |
| Markdown 渲染 | markdown-it |
| 代码高亮 | highlight.js |

## 许可证

MIT License