LangChain SQL 智能体：用自然语言查数据库

这篇适合谁，读完能做到什么

适合想用自然语言查询数据库、又想弄清智能体如何一步步工作的读者。读完你能用 SQLite 示例库跑通一个 SQL 智能体，看懂它的工具调用过程，并给执行 SQL 的步骤加上人工审核。

它怎么工作

智能体先获取数据库中的表和结构，判断哪些表与问题相关，再读取这些表的结构，生成 SQL，用 LLM 检查一遍，然后执行。数据库报错时，它会修正查询直到成功，最后根据结果组织回答^[1]。

先说安全

让模型生成的 SQL 直接执行是有风险的，数据库连接的权限应当收窄到智能体真正需要的范围^[1]。示例里的数据库工具只是演示用的薄封装，不具备安全性，也不适合直接用于生产环境。使用时需要配合收窄的数据库权限和针对应用的校验^[1]。

准备

安装依赖：Python 使用 pip install langchain langgraph；JavaScript 使用 npm i langchain @langchain/core sqlite3 zod^[1]。
示例数据库是 chinook，以 Chinook.db 文件的形式放在公开的 GCS 存储桶上，它是 SQLite 格式的示例数据库。SQLite 本身轻量，容易安装和使用^[1]。
模型：选择支持工具调用的模型^[1]。
追踪（可选）：设置下面两个环境变量，即可在 LangSmith 上查看每一步^[1]：

export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="..."

Python 版：用数据库工具

Python 版使用内置的 sqlite3 模块连接数据库。示例输出显示方言是 sqlite，共有 11 张表，包括 Album、Artist、Customer、Track 等^[1]。

数据库工具用 langchain.tools 的 @tool 装饰器封装，共四个：sql_db_query 执行查询，sql_db_schema 返回表结构和样例行，sql_db_list_tables 列出所有表，sql_db_query_checker 在执行前检查 SQL^[1]。工具的说明会直接交给模型，内容如下：

sql_db_query: Input to this tool is a detailed and correct SQL query, output is a result from the database.
    If the query is not correct, an error message will be returned.
    If an error is returned, rewrite the query, check the query, and try again.
    If you encounter an issue with Unknown column 'xxxx' in 'field list', use sql_db_schema to query the correct table fields.
sql_db_schema: Input to this tool is a comma-separated list of tables, output is the schema and sample rows for those tables.
    Be sure that the tables actually exist by calling sql_db_list_tables first!
    Example Input: table1, table2, table3
sql_db_list_tables: Input is an empty string, output is a comma-separated list of tables in the database.
sql_db_query_checker: Use this tool to double check if your query is correct before executing it.
    Always use this tool before executing a query with sql_db_query!

智能体用 create_agent 构建，它是一个 ReAct 智能体，写得具体的系统提示词可以约束它的行为^[1]。

运行一次看看

示例问题是：「哪个流派的曲目平均时长最长？」追踪记录显示，智能体先列出所有表，再读取 Track 和 Genre 的结构，用 sql_db_query_checker 检查查询，通过 sql_db_query 执行，最后给出回答^[1]。示例结果是 "Sci Fi & Fantasy"，平均时长约 2,911,783 毫秒^[1]。

加上人工审核

执行前先让人看一眼 SQL，可以防止误操作或低效查询。LangChain 的人工审核中间件可以让智能体在调用 sql_db_query 前暂停，但要加上检查点（checkpointer）才能暂停和恢复^[1]。配置之后，运行时会出现类似下面的输出^[1]：

...
INTERRUPTED:
Tool execution pending approval
Tool: sql_db_query
Args: {'query': 'SELECT g.Name AS Genre, AVG(t.Milliseconds) AS AvgTrackLength FROM Track t JOIN Genre g ON t.GenreId = g.GenreId GROUP BY g.Name ORDER BY AvgTrackLength DESC LIMIT 1;'}

确认无误后，用 Command 恢复执行，就会接受这条查询^[1]。人工审核的更多配置可以参考 LangChain 的 human-in-the-loop 文档，检查点的说明见短期记忆相关内容^[1]。

JavaScript 版

JavaScript 版使用 execute_sql 工具。执行前，代码会先经过名为 _safe_sql 的检查，人工审核也针对这个工具配置^[1]。示例输出中，Sci Fi & Fantasy 的平均曲目时长约为 48.5 分钟，即约 2,911,783 毫秒^[1]。

用 Studio 聊天（可选）

LangSmith Studio 提供客户端循环和记忆功能，可以把智能体当作聊天界面使用，问它「介绍一下数据库结构」或「显示消费最多的 5 位客户的发票」这样的问题^[1]。使用 Studio 需要运行 pip install -U langgraph-cli[inmem]>=0.4.0，并在运行目录下放一个 langgraph.json^[1]：

{
  "dependencies": ["."],
  "graphs": {
      "agent": "./sql_agent.py:agent",
      "graph": "./sql_agent_langgraph.py:graph"
  },
  "env": ".env"
}

为什么要给 SQL 加人工审核

模型写的 SQL 可能语法正确，却效率低、扫描范围大，或者做了并非用户本意的操作。在执行前暂停、让人确认，就能把这类问题拦在数据库之前^[1]。这一步依赖检查点：智能体要能中途停下，等待决定之后再从原地继续^[1]。

工具说明是给模型看的

sql_db_query 的说明写明，出错时要重写查询、检查后再试；遇到 Unknown column 这类报错，要先用 sql_db_schema 查正确的字段。这些说明会进入模型的上下文，影响它下一步的动作^[1]。sql_db_query_checker 的说明则要求，每次执行 sql_db_query 之前都先用它检查一遍^[1]。