diff --git a/doc/docs/en/user-guide/local-tools/index.md b/doc/docs/en/user-guide/local-tools/index.md index 27dc72ebc..9006f415c 100644 --- a/doc/docs/en/user-guide/local-tools/index.md +++ b/doc/docs/en/user-guide/local-tools/index.md @@ -9,6 +9,8 @@ Local tools let agents interact with the workspace, remote hosts, and external s - [Search Tools](./search-tools): Local/DataMate KB search plus Exa/Tavily/Linkup web search. - [Multimodal Tools](./multimodal-tools): Download/parse/analyze text files and images. - [Terminal Tool](./terminal-tool): Persistent SSH sessions for remote commands. +- [SQL Tools](./sql-tools): Connect to MySQL, PostgreSQL, SQL Server to execute SQL queries. +- [Skills](../skills): Nexent's built-in tool combinations or custom capability packs with NL generation and version management. ## ⚙️ Configuration Entry diff --git a/doc/docs/en/user-guide/local-tools/sql-tools.md b/doc/docs/en/user-guide/local-tools/sql-tools.md new file mode 100644 index 000000000..859b5fbba --- /dev/null +++ b/doc/docs/en/user-guide/local-tools/sql-tools.md @@ -0,0 +1,78 @@ +--- +title: SQL Database Tools +--- + +# SQL Database Tools + +The SQL database toolset enables AI agents to connect to and query relational databases such as MySQL, PostgreSQL, and SQL Server, allowing direct data access and manipulation. + +## Tool List + +- `mysql_database`: Connect to MySQL and execute SQL queries +- `postgres_database`: Connect to PostgreSQL and execute SQL queries +- `mssql_database`: Connect to SQL Server and execute SQL queries + +## Usage Scenarios + +- Query report data from business databases for agent analysis and summarization +- Cross-database joins to retrieve related information scattered across multiple tables +- Real-time queries of business status to provide agents with up-to-date data + +## Parameters and Behavior + +### Common Parameters + +- `sql`: The SQL query to execute (required) +- `parameters`: Parameter values for parameterized queries (optional) +- `max_rows`: Maximum number of rows to return (default: 100) +- `timeout`: Query timeout in seconds (default: 10) + +### Database Connection Parameters + +| Database | Connection Parameters | +|-------------|---------------------------------------------------------------------------| +| MySQL | `host`, `user`, `password`, `database`, `port` (default 3306) | +| PostgreSQL | `host`, `user`, `password`, `database`, `port` (default 5432) | +| SQL Server | `host`, `user`, `password`, `database`, `port` (default 1433) | + +### Security Restrictions + +- Forbidden operations: `DROP DATABASE`, `GRANT`, `REVOKE`, `CREATE USER`, `INTO OUTFILE`, `LOAD DATA INFILE` +- `UPDATE` and `DELETE` statements must include a `WHERE` clause +- `LIMIT` is automatically added to restrict returned rows + +### Response Format + +```json +{ + "status": "success", + "columns": ["id", "name", "email"], + "rows": [[1, "John Doe", "john@example.com"]], + "row_count": 1, + "execution_time_ms": 45.23 +} +``` + +## Getting Started + +1. **Prepare connection info**: Obtain host address, port, database name, username, and password +2. **Configure the tool**: Add the appropriate database tool in agent configuration and fill in connection parameters +3. **Test connection**: Use a simple query to verify connectivity +4. **Construct queries**: Let the agent understand natural language requirements and generate corresponding SQL + +## Security Best Practices + +- Use read-only accounts in production to limit operation permissions +- Store sensitive information like database passwords in a key management service +- Set reasonable `max_rows` values to avoid returning excessive data at once +- Enable SSL/TLS encryption for database connections + +## Common Database Connection Examples + +| Database | Connection Example | Parameter Placeholder | +|-------------|-------------------|---------------------| +| MySQL | `localhost:3306` | `?` | +| PostgreSQL | `localhost:5432` | `$1, $2, ...` | +| SQL Server | `localhost:1433` | `?` | + +> Note: Different databases use different parameter placeholder formats. PostgreSQL uses `$1, $2`, while others use `?`. diff --git a/doc/docs/zh/user-guide/local-tools/index.md b/doc/docs/zh/user-guide/local-tools/index.md index ceaac3f54..71ba3e950 100644 --- a/doc/docs/zh/user-guide/local-tools/index.md +++ b/doc/docs/zh/user-guide/local-tools/index.md @@ -9,6 +9,7 @@ - [搜索工具](./search-tools):本地/DataMate/Dify 知识库检索与 Exa/Tavily/Linkup 公网搜索。 - [多模态工具](./multimodal-tools):文本文件与图片的下载、解析、模型分析。 - [终端工具](./terminal-tool):持久化 SSH 会话,远程执行命令。 +- [SQL 工具](./sql-tools):连接 MySQL、PostgreSQL、SQL Server 执行 SQL 查询。 - [技能(Skills)](../skills):Nexent内置工具组合或自定义能力包,支持 NL 生成与版本管理。 ## ⚙️ 配置入口 diff --git a/doc/docs/zh/user-guide/local-tools/sql-tools.md b/doc/docs/zh/user-guide/local-tools/sql-tools.md new file mode 100644 index 000000000..b5b50af59 --- /dev/null +++ b/doc/docs/zh/user-guide/local-tools/sql-tools.md @@ -0,0 +1,75 @@ +--- +title: SQL 数据库工具 +--- + +# SQL 数据库工具 + +SQL 数据库工具组支持连接和查询 MySQL、PostgreSQL、SQL Server 等关系型数据库,让 AI 智能体能够直接读取和操作数据库数据。 + +## 工具清单 + +- `mysql_database`:连接 MySQL 数据库执行 SQL 查询 +- `postgres_database`:连接 PostgreSQL 数据库执行 SQL 查询 +- `mssql_database`:连接 SQL Server 数据库执行 SQL 查询 + +## 使用场景示例 + +- 从业务数据库中查询报表数据,供智能体分析汇总 +- 跨数据库关联查询,获取分散在多个表中的关联信息 +- 实时查询业务状态,为智能体提供最新数据参考 + +## 参数要求与行为 + +### 通用参数 +- `sql`:要执行的 SQL 查询语句,必填 +- `parameters`:参数化查询的参数值列表,可选 +- `max_rows`:最大返回行数,默认 100 +- `timeout`:查询超时时间(秒),默认 10 + +### 数据库连接参数 + +| 数据库 | 连接参数 | +|--------|----------| +| MySQL | `host`、`user`、`password`、`database`、`port`(默认 3306) | +| PostgreSQL | `host`、`user`、`password`、`database`、`port`(默认 5432) | +| SQL Server | `host`、`user`、`password`、`database`、`port`(默认 1433) | + +### 安全限制 +- 禁止执行 `DROP DATABASE`、`GRANT`、`REVOKE`、`CREATE USER`、`INTO OUTFILE`、`LOAD DATA INFILE` 等危险操作 +- `UPDATE` 和 `DELETE` 语句必须包含 `WHERE` 子句 +- 自动添加 `LIMIT` 限制返回行数 + +### 返回格式 +```json +{ + "status": "success", + "columns": ["id", "name", "email"], + "rows": [[1, "张三", "zhang@example.com"]], + "row_count": 1, + "execution_time_ms": 45.23 +} +``` + +## 操作指引 + +1. **准备数据库连接信息**:获取主机地址、端口、数据库名、用户名和密码 +2. **配置工具**:在智能体工具配置中添加对应数据库工具,填写连接参数 +3. **测试连接**:使用简单查询验证连接是否正常 +4. **构造查询**:让智能体理解自然语言需求,生成对应 SQL 执行 + +## 安全与最佳实践 + +- 生产环境建议使用只读账号,限制操作权限 +- 敏感信息如数据库密码可通过密钥管理服务存储 +- 合理设置 `max_rows` 避免一次性返回过多数据 +- 建议开启数据库连接的 SSL/TLS 加密选项 + +## 常见数据库连接示例 + +| 数据库 | 连接地址示例 | 参数占位符 | +|--------|-------------|------------| +| MySQL | `localhost:3306` | `?` | +| PostgreSQL | `localhost:5432` | `$1, $2, ...` | +| SQL Server | `localhost:1433` | `?` | + +> 不同数据库的参数占位符格式不同,PostgreSQL 使用 `$1, $2` 格式,其他使用 `?`。