agent-sql 是默认只读的 SQL CLI，位于 $PATH，供代理探索数据库结构、表与数据。支持 PostgreSQL、CockroachDB、MySQL、MariaDB、SQLite、DuckDB、Snowflake、MSSQL。输出默认走 stdout 的 NDJSON：查询结果与列表每行一个 JSON 对象，无外层封装；单资源与回执为一行紧凑 JSON。--format json 输出美化 JSON，--format yaml 输出 YAML；错误走 stderr，形如 { "error": "...", "fixable_by": "agent|human|retry", "hint": "..." } 并返回非零退出码，提示为 stderr 上的 { "notice": "...", "hint": "..." } 行。
用法上，可用 -c 接文件路径、URL 或已保存别名做临时查询，例如 agent-sql run -c ./data.db 'SELECT * FROM users'。也支持 postgres://、cockroachdb://、mysql://、mariadb://、duckdb://、snowflake://、mssql:// 等 URL。常用命令包括 schema tables、schema describe、schema indexes、schema constraints、schema search、schema dump、query sample、query run、query explain、query count。写入默认被阻止，需用户配置具备写权限的凭证，并在单次查询加 --write。
输出控制：字符串超过 truncation.maxLength（默认 200）会被截断并附 @truncated 元数据；可用 --full 或 --expand 字段展开。默认超时 30s，可用 --timeout <ms> 覆盖。关键配置含 defaults.format（jsonl）、query.format（jsonl，可为 csv）、defaults.limit（20）、query.timeout（30000ms）、query.maxRows（10000）、truncation.maxLength（200）。
连接由用户配置，代理只能列出与测试，不能增删改。连接解析顺序为 -c 参数 > AGENT_SQL_CONNECTION 环境变量 > 配置默认 > 报错。含凭据的 URL 在添加时会被拒绝，密钥须经凭证机制存入钥匙串；不要将用户粘贴的密码放入 --password，应让用户用 credential add --form 在本地输入，代理只能看到脱敏回执。
安全方面：默认只读，写入需 --write 与写权限凭证；不同数据库采用只读事务、关键字守卫、只读打开、只读 CLI 标志、关键字允许列表等防御；结果受 query.maxRows 限制（默认 10000）。错误含 fixable_by：agent 可自行修复，human 需人工处理不要重试，retry 为瞬时错误可重试。每条命令组都有 usage 子命令提供详细文档，如 agent-sql usage、agent-sql schema usage。DuckDB 需先安装 duckdb CLI（brew install duckdb）。其余平台支持、收费与价格资料暂未提供。