# text-to-sql-agent

**Repository Path**: weedlu/text-to-sql-agent

## Basic Information

- **Project Name**: text-to-sql-agent
- **Description**: 一个基于 Langchain deepagent 的 text-to-sql-agent
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-02
- **Last Updated**: 2026-07-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Text-to-SQL 深度智能体

一个由 LangChain **Deep Agents** 框架驱动的自然语言转 SQL 查询智能体。这是一个具备规划、文件系统和子智能体能力的增强版文本转 SQL 智能体。

## 什么是 Deep Agents？

Deep Agents 是一个基于 LangGraph 构建的先进智能体框架，提供以下功能：

- **规划能力** - 使用 `write_todos` 工具分解复杂任务
- **文件系统后端** - 通过文件操作保存和检索上下文
- **子智能体生成** - 将专业任务委托给专注型智能体处理
- **上下文管理** - 防止复杂任务中出现上下文窗口溢出

## 演示数据库

使用 [Chinook 数据库](https://github.com/lerocha/chinook-database) - 一个代表数字媒体商店的示例数据库。

## 快速开始

### 前置条件

- Python 3.11 或更高版本
- Anthropic API 密钥（[获取方式](https://console.anthropic.com/)）
- （可选）LangSmith API 密钥用于追踪（[注册地址](https://smith.langchain.com/)）

### 安装步骤

1. 克隆 deepagents 仓库并进入此示例目录：

```bash
git clone https://github.com/langchain-ai/deepagents.git
cd deepagents/examples/text-to-sql-agent
```

2. 下载 Chinook 数据库：

```bash
# 下载 SQLite 数据库文件
curl -L -o chinook.db https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite
```

3. 创建虚拟环境并安装依赖：

```bash
# 使用 uv（推荐）
uv venv --python 3.11
source .venv/bin/activate  # Windows 系统：.venv\Scripts\activate
uv sync
```

4. 配置环境变量：

```bash
cp .env.example .env
# 编辑 .env 文件并添加您的 API 密钥
```

`.env` 文件中必需的配置：

```
ANTHROPIC_API_KEY=your_anthropic_api_key_here
```

可选配置：

```
LANGCHAIN_TRACING_V2=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=your_langsmith_api_key_here
LANGCHAIN_PROJECT=text2sql-deepagent
```

## 使用方法

### 命令行界面

使用自然语言问题从命令行运行智能体：

```bash
python agent.py "销量前5的艺术家有哪些？"
```

```bash
python agent.py "哪位员工在哪些国家创造了最多收入？"
```

```bash
python agent.py "有多少客户来自加拿大？"
```

### 程序化调用

您也可以在 Python 代码中使用该智能体：

```python
from agent import create_sql_deep_agent

# 创建智能体
agent = create_sql_deep_agent()

# 提问
result = agent.invoke({
    "messages": [{"role": "user", "content": "销量前5的艺术家有哪些？"}]
})

print(result["messages"][-1].content)
```

## Deep Agent 工作原理

### 架构

```
用户问题
     ↓
Deep Agent（带规划功能）
     ├─ write_todos（规划方法）
     ├─ SQL 工具
     │  ├─ list_tables
     │  ├─ get_schema
     │  ├─ query_checker
     │  └─ execute_query
     ├─ 文件系统工具（可选）
     │  ├─ ls
     │  ├─ read_file
     │  ├─ write_file
     │  └─ edit_file
     └─ 子智能体生成（可选）
     ↓
SQLite 数据库（Chinook）
     ↓
格式化答案
```

### 配置

Deep Agents 使用基于**渐进式披露**的记忆文件和技能：

**AGENTS.md**（始终加载）包含：

- 智能体身份和角色
- 核心原则和安全规则
- 通用指南
- 沟通风格

**skills/**（按需加载）包含专业工作流：

- **query-writing** - 如何编写和执行 SQL 查询（简单和复杂）
- **schema-exploration** - 如何发现数据库结构和关系

智能体在其上下文中看到技能描述，但仅在确定当前任务需要哪个技能时，才加载完整的 SKILL.md 指令。这种**渐进式披露**模式既保持了上下文的效率，又在需要时提供了深入的专业知识。

## 示例查询

### 简单查询

```
"有多少客户来自加拿大？"
```

智能体将直接查询并返回数量。

### 带规划功能的复杂查询

```
"哪位员工在哪些国家创造了最多收入？"
```

智能体将：

1. 使用 `write_todos` 来规划方法
2. 识别所需的表（Employee、Invoice、Customer）
3. 规划 JOIN 结构
4. 执行查询
5. 用分析结果格式化输出

## Deep Agent 输出示例

Deep Agent 会展示其推理过程：

```
问题：哪位员工在哪些国家创造了最多收入？

[规划步骤]
使用 write_todos：
- [ ] 列出数据库中的表
- [ ] 检查 Employee 和 Invoice 的模式
- [ ] 规划多表 JOIN 查询
- [ ] 按员工和国家进行聚合执行
- [ ] 格式化结果

[执行步骤]
1. 正在列出表...
2. 获取模式：Employee、Invoice、InvoiceLine、Customer
3. 生成 SQL 查询...
4. 执行查询...
5. 格式化结果...

[最终答案]
员工 Jane Peacock（ID: 3）创造了最多收入...
排名前列的国家：美国（$1000）、加拿大（$500）...
```

## 项目结构

```
text-to-sql-agent/
├── agent.py                      # 核心 Deep Agent 实现，包含 CLI
├── AGENTS.md                     # 智能体身份和通用指令（始终加载）
├── skills/                       # 专业工作流（按需加载）
│   ├── query-writing/
│   │   └── SKILL.md             # SQL 查询编写工作流
│   └── schema-exploration/
│       └── SKILL.md             # 数据库结构发现工作流
├── chinook.db                    # 示例 SQLite 数据库（已下载，已加入 gitignore）
├── pyproject.toml                # 项目配置和依赖
├── uv.lock                       # 锁定的依赖版本
├── .env.example                  # 环境变量模板
├── .gitignore                    # Git 忽略规则
├── text-to-sql-langsmith-trace.png  # LangSmith 追踪示例图片
└── README.md                     # 本文件
```

## LangSmith 集成

### 设置

1. 在 [LangSmith](https://smith.langchain.com/) 注册免费账户
2. 从账户设置中创建 API 密钥
3. 将以下变量添加到 `.env` 文件：

```
LANGCHAIN_TRACING_V2=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=your_langsmith_api_key_here
LANGCHAIN_PROJECT=text2sql-deepagent
```

### 您将看到的内容

配置后，每个查询都会被自动追踪：

![Deep Agent LangSmith 追踪示例](text-to-sql-langsmith-trace.png)

您可以查看：

- 包含所有工具调用的完整执行追踪
- 规划步骤（write_todos）
- 文件系统操作
- Token 使用量和成本
- 生成的 SQL 查询
- 错误消息和重试尝试

查看您的追踪记录：<https://smith.langchain.com/>

## 资源

- [Deep Agents 文档](https://docs.langchain.com/oss/python/deepagents/overview)
- [LangChain](https://www.langchain.com/)
- [Claude Sonnet 4.5](https://www.anthropic.com/claude)
- [Chinook 数据库](https://github.com/lerocha/chinook-database)
- [LangChain Academy](https://academy.langchain.com/) — 由 LangChain 团队制作的关于 LangChain 库和产品的综合免费课程。
- [行为准则](https://github.com/langchain-ai/langchain/?tab=coc-ov-file) — 社区指南和标准

## 许可证

MIT

## 贡献

欢迎贡献！请随时提交 Pull Request。