NL2SQL 工具

NL2SQLTool 旨在将自然语言转换为 SQL 查询。

概述

该工具用于将自然语言转换为 SQL 查询。将其传递给智能体后，它会生成查询，然后使用这些查询与数据库交互。

这支持多种工作流，例如让智能体访问数据库，根据目标获取信息，然后使用这些信息生成响应、报告或任何其他输出。此外，它还使智能体能够根据其目标更新数据库。

注意：默认情况下，该工具为只读（仅允许 SELECT/SHOW/DESCRIBE/EXPLAIN）。写操作需要 allow_dml=True 或环境变量 CREWAI_NL2SQL_ALLOW_DML=true。启用写访问时，请确保智能体尽可能使用限定范围的数据库用户或只读副本。

安全模型

NL2SQLTool 是一个具备执行能力的工具。它会直接针对已配置的数据库连接运行模型生成的 SQL。

这意味着风险取决于你的部署选择：

你在 db_uri 中提供哪些凭证
不可信输入是否会影响提示词
是否在执行前添加工具调用护栏

如果你将不可信输入路由到使用此工具的智能体，请将其视为高风险集成。

加固建议

在生产环境中使用以下所有措施：

尽可能使用只读数据库用户
对于分析/检索工作负载，优先使用只读副本
授予最小权限（无超级用户/管理员角色，无文件/系统级能力）
应用数据库端资源限制（语句超时、锁超时、成本/行数限制）
添加 before_tool_call 钩子以强制执行允许的查询模式
为破坏性语句启用查询日志记录和告警

只读模式与 DML 配置

NL2SQLTool 默认以只读模式运行。未经额外配置时，仅允许以下语句类型：

SELECT
SHOW
DESCRIBE
EXPLAIN

除非显式启用 DML，否则任何执行写操作（INSERT、UPDATE、DELETE、DROP、CREATE、ALTER、TRUNCATE 等）的尝试都会引发错误。

包含分号的多语句查询（例如 SELECT 1; DROP TABLE users）在只读模式下同样会被阻止，以防止注入攻击。

启用写操作

你可以通过两种方式启用 DML（Data Manipulation Language，数据操作语言）：

方式 1 — 构造函数参数：

python

from crewai_tools import NL2SQLTool

nl2sql = NL2SQLTool(
    db_uri="postgresql://example@localhost:5432/test_db",
    allow_dml=True,
)

方式 2 — 环境变量：

bash

CREWAI_NL2SQL_ALLOW_DML=true

python

from crewai_tools import NL2SQLTool

# DML enabled via environment variable
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")

用法示例

只读（默认）— 适用于分析和报表：

python

from crewai_tools import NL2SQLTool

# Only SELECT/SHOW/DESCRIBE/EXPLAIN are permitted
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")

启用 DML — 写入类工作负载所必需：

python

from crewai_tools import NL2SQLTool

# INSERT, UPDATE, DELETE, DROP, etc. are permitted
nl2sql = NL2SQLTool(
    db_uri="postgresql://example@localhost:5432/test_db",
    allow_dml=True,
)

WARNING

启用 DML 会让智能体具备修改或销毁数据的能力。仅当你的用例明确需要写入权限时才启用，并确保数据库凭据被限定在最小必要权限范围内。

要求

SqlAlchemy
任何兼容的数据库库（例如 psycopg2、mysql-connector-python）

安装

安装 crewai_tools 包

shell

pip install 'crewai[tools]'

用量

要使用 NL2SQLTool，你需要将数据库 URI 传给该工具。URI 的格式应为 dialect+driver://username:password@host:port/database。

python

from crewai_tools import NL2SQLTool

# psycopg2 was installed to run this example with PostgreSQL
nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db")

@agent
def researcher(self) -> Agent:
    return Agent(
        config=self.agents_config["researcher"],
        allow_delegation=False,
        tools=[nl2sql]
    )