# deep_agent

**Repository Path**: mood6666/deep_agent

## Basic Information

- **Project Name**: deep_agent
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-22
- **Last Updated**: 2026-05-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Deep Agent 从 0 到 1 实战教程（豆包版）

> 面向已经掌握 LangChain / LangGraph 的开发者。**目标：用 6 个递进的 demo，1.5~2 小时把 `deepagents` 这个新东西彻底搞懂。**

---

## 它是什么？一句话定位

> **deepagent 不是新运行时，也不是新协议，它是一个"预装了固定套路"的 agent 模板（官方称为 agent harness / 外壳）。**

跑的还是 LangGraph 的图、用的还是 LangChain 的工具调用循环，只是把 Claude Code / Manus / Deep Research 这些产品被验证过的几样东西**默认打包给你了**：

| 内置能力 | 对应工具 | 你以前要自己实现的痛点 |
|---|---|---|
| 规划 / 待办 | `write_todos` | 自己写 planner 节点 |
| 虚拟文件系统 | `ls / read_file / write_file / edit_file` | 长上下文塞不下、要自己做摘要 |
| 子代理 | `task` | 自己用 Send / Subgraph 隔离 context |
| Shell 执行 | `execute`（sandbox 后端） | 自己接 e2b / docker |
| 长期记忆 | LangGraph Store | 自己接 vector store |
| 人审 | `interrupt_on` 包装 | 自己写 HITL |

学 deepagent 的关键不是学 API，**而是搞清"这套默认套路里，每个组件什么时候帮了你、什么时候挡了你"**。

---

## 项目结构

```
deep_agent/
├── README.md                       # 你正在看的这份
├── requirements.txt
├── .env.example                    # 复制成 .env 后填豆包 API Key
├── docs/
│   ├── 00_概念地图.md              # 全家桶里的定位 + 与 create_agent 的对比代码
│   ├── 01_最小demo详解.md
│   ├── 02_虚拟文件系统.md
│   ├── 03_自定义工具与提示.md
│   ├── 04_子代理.md
│   ├── 05_后端与人审.md
│   └── 06_迷你_deep_researcher.md
└── demos/
    ├── _model.py                   # 统一的豆包模型构造器（所有 demo 共用）
    ├── demo01_hello_deepagent.py   # 5 行代码跑通第一个 deep agent
    ├── demo02_virtual_fs.py        # 让 agent 自己用虚拟文件系统管理上下文
    ├── demo03_custom_tools.py      # 加自定义工具 + 自定义系统提示
    ├── demo04_subagents.py         # 子代理：上下文隔离的灵魂特性
    ├── demo05_backend_and_hitl.py  # 切换到本地磁盘后端 + 关键操作人审
    └── demo06_mini_deep_researcher.py  # 综合实战：迷你 deep researcher
```

---

## 快速开始

### 1. 准备 Python 环境（建议 Python 3.10+）

```bash
# 在项目根目录
python -m venv .venv
.venv\Scripts\activate          # Windows PowerShell
# source .venv/bin/activate     # macOS/Linux

pip install -r requirements.txt
```

### 2. 配置豆包 API Key

```bash
copy .env.example .env          # Windows
# cp .env.example .env          # macOS/Linux
```

打开 `.env`，把 `ARK_API_KEY` 替换成你自己的火山方舟 Key。

> 申请入口：https://console.volcengine.com/ark
> `ARK_MODEL` 默认填的是 `doubao-seed-2-0-pro`，如果你只开通了某个 endpoint，把它改成 `ep-xxxxx` 即可。

### 3. 按顺序跑 demo

```bash
python demos/demo01_hello_deepagent.py
python demos/demo02_virtual_fs.py
python demos/demo03_custom_tools.py
python demos/demo04_subagents.py
python demos/demo05_backend_and_hitl.py
python demos/demo06_mini_deep_researcher.py
```

每个 demo 跑完，**对应去看 `docs/` 里同名的 md 文档**，那里讲清楚了"刚才发生了什么"。

---

## 学习路径建议（强烈推荐按顺序）

| 顺序 | 文档 | Demo | 你应该 get 到什么 |
|---|---|---|---|
| 0 | `docs/00_概念地图.md` | — | 在脑子里画一张图：deepagent 在 LC/LG 全家桶的位置 |
| 1 | `docs/01_最小demo详解.md` | `demo01` | "原来一行 `create_deep_agent` 就帮我装了 6 个工具" |
| 2 | `docs/02_虚拟文件系统.md` | `demo02` | "上下文太长？让 agent 把东西写进虚拟 FS" |
| 3 | `docs/03_自定义工具与提示.md` | `demo03` | 真实业务里 90% 的用法 |
| 4 | `docs/04_子代理.md` | `demo04` | deepagent 的灵魂：context isolation |
| 5 | `docs/05_后端与人审.md` | `demo05` | 把玩具变可投产：真落盘 + 人工审核 |
| 6 | `docs/06_迷你_deep_researcher.md` | `demo06` | 把前 5 个组合起来，做一个迷你 Manus |

---

## 关于本教程

- 模型：火山引擎方舟 · 豆包 2.0（OpenAI 兼容协议，所以代码里走的是 `langchain-openai`）
- 联网搜索：**全部 mock**，无需任何外部 Key，专注于看 deepagent 自身的行为
- 注释规范：函数级 docstring 使用 JSDoc 风格的 `@param` / `@returns` 字段