LangGraph实战训练营-构建自然语言转SQL智能代理
文章目录
- 一、引言：当自然语言遇见数据库
- 二、项目概述与核心能力
- 2.1 这个Agent能做什么？
- 2.2 核心能力矩阵
- 三、技术架构全景解读
- 3.1 架构总览图
- 3.2 Deep Agents框架的三大核心概念
- 四、环境准备与项目搭建
- 4.1 系统要求
- 4.2 安装Python
- 4.3 验证Python安装
- 4.4 安装uv包管理器（推荐）
- 4.5 创建项目目录结构
- 五、依赖配置详解
- 5.1 创建 pyproject.toml
- 5.2 依赖包功能说明
- 5.3 安装依赖
- 六、数据库准备——Chinook示例库
- 6.1 关于Chinook数据库
- 6.2 下载数据库文件
- 6.3 Chinook数据库ER关系图
- 七、核心代码实现（完整源码与逐行解析）
- 7.1 完整源码
- 7.2 关键代码逐行解析
- 导入部分
- `create_sql_deep_agent()` 函数——Agent的"装配工厂"
- `main()` 函数——命令行入口
- 八、Agent身份配置——AGENTS.md
- 8.1 什么是AGENTS.md？
- 8.2 完整配置
- 8.3 设计要点分析
- 九、技能系统——渐进式披露的设计哲学
- 9.1 渐进式披露（Progressive Disclosure）
- 9.2 技能1：query-writing（SQL查询编写）
- Error Recovery
- Quality Guidelines
- 9.4 技能文件结构说明
- 十、环境变量与安全配置
- 10.1 创建.env.example模板
- 10.2 创建实际的.env文件
- 10.3 API密钥获取方式
- 10.4 创建.gitignore
- 十一、运行测试与效果验证
- 11.1 验证项目结构完整性
- 11.2 测试1：简单查询
- 11.3 测试2：多表JOIN排序查询
- 11.4 测试3：复杂分析查询
- 11.5 编程式调用测试
- 11.6 常见运行问题速查表
- 十二、架构原理深度解析
- 12.1 Deep Agents的完整工作流程
- 12.2 三大关键设计模式
- 十三、扩展开发指南
- 13.1 添加新技能
- 13.2 更换为生产数据库
- 13.3 添加自定义工具
- 13.4 切换到其他LLM
- 13.5 集成到Web应用（FastAPI示例）
- 十四、常见问题排查
- Q1：安装依赖时报错找不到 deepagents
- Q2：Anthropic API认证失败
- Q3：数据库连接失败
- Q4：生成的SQL有语法错误
- Q5：响应太慢或超时
- Q6：如何查看详细的执行过程？
- 十五、总结与学习路线
- 你已掌握的能力
- 关键要点回顾
- 建议的下一步学习路径
- 附录
- A. 传统pip安装方式（替代uv）
- B. Docker部署
一、引言：当自然语言遇见数据库
在过去，如果你想从数据库中获取某个业务问题的答案，通常需要经历这样的流程：理解需求 → 写SQL → 执行查询 → 分析结果 → 写报告。这个过程不仅对非技术人员的门槛极高，即便是开发者，面对复杂的多表JOIN和聚合查询，也常常需要反复调试。
而随着大语言模型（LLM）的成熟，Text-to-SQL成为了AI落地场景中的热门方向。LangChain 社区推出的Deep Agents框架在此基础上更进一步——它不仅会生成SQL，还能像一位经验丰富的数据库工程师一样：自主探索表结构、规划查询策略、验证语法、执行查询、格式化结果，甚至处理错误并自动重试。
本文将基于 Deep Agents 官方示例，带你从零开始搭建一个完整的Text-to-SQL Deep Agent，深入剖析其架构设计、核心代码和扩展方法。无论你是希望将AI能力接入企业内部数据库的架构师，还是正在学习Agent开发的初学者，这篇文章都将为你提供一份详尽的技术参考。
二、项目概述与核心能力
2.1 这个Agent能做什么？
Text-to-SQL Deep Agent 是一个基于 LangChain Deep Agents 框架构建的自然语言转SQL查询智能代理，具备以下能力：
- 理解自然语言问题：接收用户用日常语言提出的数