当前位置：首页 > news >正文

LangGraph实战训练营-构建自然语言转SQL智能代理

news 2026/7/1 20:18:07

文章目录

- 一、引言：当自然语言遇见数据库
- 二、项目概述与核心能力
- - 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开发的初学者，这篇文章都将为你提供一份详尽的技术参考。