让智能体直接查询数据库:lca-lc-foundations 附赠 SQL 查询 Agent 完整教程
让智能体直接查询数据库:lca-lc-foundations 附赠 SQL 查询 Agent 完整教程
在 lca-lc-foundations(LangChain Academy 官方基础课程仓库)的 Module 2 中,隐藏着一个实用的 SQL 查询 Agent 教程——bonus_sql.ipynb。它教你用不到 50 行代码,让大语言模型通过自然语言直接查询 SQLite 数据库,无需手写复杂的提示词工程。这篇完整教程带你从零搭建这个数据库查询智能体,掌握 LangChain 工具调用的核心模式。
为什么需要 SQL 查询 Agent? 🤔
传统方式下,用户要查询数据库必须会写 SQL。而通过 LangChain 的 工具调用(Tool Calling) 机制,你可以把 sql_query 函数注册为 Agent 的工具,Agent 会自动把用户的自然语言问题翻译成 SQL 语句,执行查询后把结果返回给用户。
这正是 lca-lc-foundations 附赠教程的核心思路:
用户提问 → Agent 生成 SQL → 执行查询 → 返回结果
整个流程由 LangChain 的 create_agent 函数自动编排,开发者只需定义"工具"和"模型"即可。
项目结构与环境配置
快速克隆与安装
如果你还没有这个仓库,可以通过以下命令获取:
git clone --depth 1 https://gitcode.com/gh_mirrors/lc/lca-lc-foundations
cd lca-lc-foundations
项目要求 Python >= 3.12, < 3.14,推荐使用 uv 管理依赖:
cp example.env .env # 创建环境配置文件
uv sync # 安装所有依赖
uv run env_utils.py # 验证环境
uv run jupyter lab # 启动 Jupyter
⚠️ 你需要在
.env文件中配置OPENAI_API_KEY,因为教程默认使用gpt-5-nano模型。模板文件为 example.env。
关键依赖说明
SQL 查询 Agent 用到两个核心库(已包含在 requirements.txt 中):
| 依赖包 | 作用 |
|---|---|
langchain-community |
提供 SQLDatabase 数据库连接工具 |
langchain |
提供 create_agent、@tool、HumanMessage 等核心 API |
三步搭建 SQL 查询工具 🔧
整个 Agent 的构建只有 三步,对应 notebooks/module-2/bonus_sql.ipynb 中的前四个代码单元。
第一步:连接数据库
LangChain 通过 SQLDatabase 类来连接数据库。教程使用的是内置的 Chinook 示例数据库(一个经典的音乐商店 SQLite 数据库,包含歌手、专辑、歌曲、客户等表):
from langchain_community.utilities import SQLDatabase
db = SQLDatabase.from_uri("sqlite:///resources/Chinook.db")
这里用 from_uri 一行代码完成连接,支持 SQLite、PostgreSQL、MySQL 等多种数据库,只需替换连接字符串即可。
第二步:定义查询工具
用 @tool 装饰器把一个普通函数变成 Agent 可以调用的工具:
from langchain.tools import tool
@tool
def sql_query(query: str) -> str:
"""Obtain information from the database using SQL queries"""
try:
return db.run(query)
except Exception as e:
return f"Error: {e}"
这里有 两个关键细节:
- docstring 很重要——它是 Agent 理解"这个工具能做什么"的依据,写清楚"用什么、做什么"
- 异常捕获——数据库查询可能出错(语法错误、表不存在),捕获后返回错误信息让 Agent 有机会自我修正
第三步:创建 Agent
from langchain.agents import create_agent
agent = create_agent(
model="gpt-5-nano",
tools=[sql_query]
)
create_agent 是 LangChain 提供的高层 API,传入 模型名称 和 工具列表,Agent 就自动具备了"思考 → 调用工具 → 观察结果 → 回答"的完整循环能力。
用自然语言对话数据库 🗣️
搭建完成后,只需发送一条自然语言消息:
from langchain.messages import HumanMessage
from pprint import pprint
question = HumanMessage(
content="Who is the most popular artist beginning with 'S' in this database?"
)
response = agent.invoke({"messages": [question]})
pprint(response["messages"])
Agent 收到问题后,会经历以下过程:
- 推理阶段:模型分析问题,决定调用
sql_query工具 - SQL 生成:自动编写一条类似
SELECT ... FROM Artist WHERE Name LIKE 'S%' ORDER BY ...的 SQL - 执行查询:
sql_query工具执行 SQL,返回查询结果 - 总结回答:模型把查询结果整理成自然语言回复给用户
你可以在 notebooks/module-2/bonus_sql.ipynb 的最后一个代码单元中查看 Agent 实际生成的 SQL 语句:
print(response["messages"][-3].tool_calls[0]['args']['query'])
这会打印出 Agent 推理过程中生成的原始 SQL,帮助你理解它的"思考过程"。
从 SQLite 扩展到更多场景 🚀
SQLDatabase.from_uri 支持多种数据库,只需修改连接字符串:
| 数据库类型 | 连接示例 |
|---|---|
| SQLite | sqlite:///path/to/db.db |
| PostgreSQL | postgresql://user:pass@host/dbname |
| MySQL | mysql://user:pass@host/dbname |
| SQL Server | mssql://user:pass@host/dbname |
安全提示
在实际生产环境中,建议给工具函数加上 只读限制,防止 Agent 执行 DROP TABLE、DELETE 等危险操作。可以在 sql_query 函数内对 SQL 语句做关键词过滤,或让数据库账号只具备 SELECT 权限。
更多学习资源 📚
lca-lc-foundations 仓库包含三个递进模块,SQL 查询 Agent 位于 Module 2 的附赠课程中。以下是与本文相关的扩展学习路径:
| 模块 | 文件 | 学习重点 |
|---|---|---|
| Module 1 - 工具基础 | notebooks/module-1/1.2_tools.ipynb | @tool 装饰器用法、工具调用原理 |
| Module 2 - 多 Agent | notebooks/module-2/2.4_wedding_planners.ipynb | 多 Agent 协作,其中也使用了 Chinook 数据库 |
| Module 2 - RAG | notebooks/module-2/bonus_rag.ipynb | 另一个附赠课程,用文档问答代替数据库查询 |
| Module 3 - 动态工具 | notebooks/module-3/3.4_dynamic_tools.ipynb | 运行时动态加载 SQL 工具 |
项目完整说明与安装步骤见 README.md,环境验证脚本为 env_utils.py。
总结
bonus_sql.ipynb 用最简洁的方式展示了 LangChain 智能体与数据库交互 的完整模式:SQLDatabase 连接 → @tool 包装 → create_agent 组装 → 自然语言查询。掌握这个模式后,你可以快速将其迁移到 PostgreSQL、MySQL 等任意数据库,构建属于自己的"对话式数据分析"应用。