文章目录一、引言：当自然语言遇见数据库二、项目概述与核心能力2.1 这个Agent能做什么？2.2 核心能力矩阵三、技术架构全景解读3.1 架构总览图3.2 Deep Agents框架的三大核心概念四、环境准备与项目搭建4.1 系统要求4.2 安装Python4.3 验证Python安装4.4 安装uv包管理器（推荐）4.5 创建项目目录结构五、依赖配置详解5.1 创建 pyproject.toml5.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.md8.1 什么是AGENTS.md？8.2 完整配置8.3 设计要点分析九、技能系统——渐进式披露的设计哲学9.1 渐进式披露（Progressive Disclosure）9.2 技能1：query-writing（SQL查询编写）Error RecoveryQuality Guidelines9.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 切换到其他LLM13.5 集成到Web应用（FastAPI示例）十四、常见问题排查Q1：安装依赖时报错找不到 deepagentsQ2：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查询智能代理，具备以下能力：理解自然语言问题：接收用户用日常语言提出的数