deepagents 实践：为 Text-to-SQL Agent 编写 Query Writing 技能（SKILL.md 全解）

deepagents 实践为 Text-to-SQL Agent 编写 Query Writing 技能SKILL.md 全解【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents导读本文以 deepagents 仓库中 examples/text-to-sql-agent/skills/query-writing/SKILL.md 为骨架完整拆解这一面向数据库查询场景的 Agent 技能文档从简单查询的 5 步工作流、复杂多表 JOIN 的规划方法到错误恢复策略与质量准则。同时结合 agent.py、AGENTS.md 以及 deepagents 核心库中的技能加载中间件实现说明该 SKILL.md 是如何通过 progressive disclosure渐进式披露机制被 Agent 按需加载并实际生效的。读完本文你将掌握一套可直接复用的 SQL 技能编写范式并理解其在 Deep Agents 框架中的完整调用链路。技能定位SKILL.md 在 Text-to-SQL Agent 中的角色query-writing是 Text-to-SQL 示例项目中的两个内置技能之一另一个是 schema-exploration。它的 frontmatter 定义如下--- name: query-writing description: Writes and executes SQL queries from simple SELECTs to complex multi-table JOINs, aggregations, and subqueries. Use when the user asks to query a database, write SQL, run a SELECT statement, retrieve data, filter records, or generate reports from database tables. ---这段description承担着路由入口的作用它明确列出技能适用的触发场景查询数据库、编写 SQL、执行 SELECT、取数、过滤记录、生成报表便于模型在收到用户问题时快速判断当前任务是否需要加载该技能。技能的挂载发生在 agent.py 的create_deep_agent调用中agent create_deep_agent( modelmodel, # Claude Sonnet 4.5 with temperature0 memory[./AGENTS.md], # Agent identity and general instructions skills[./skills/], # Specialized workflows (query-writing, schema-exploration) toolssql_tools, # SQL database tools subagents[], # No subagents needed backendFilesystemBackend(root_dirbase_dir), # Persistent file storage )从源码结构看skills[./skills/]指向包含两个子目录的技能目录每个子目录下的SKILL.md通过 YAML frontmatter 声明name与description这与 deepagents 核心库中SkillsMiddleware的加载约定完全一致详见下文底层实现部分。简单查询工作流单表问题的 5 步法对于只涉及单张表的直接问题query-writing技能定义了固定的 5 步处理流程Identify the table定位表—— 判断哪张表承载所需数据Get the schema获取表结构—— 调用sql_db_schema查看列定义Write the query编写查询—— SELECT 相关列配合 WHERE / LIMIT / ORDER BYExecute执行—— 通过sql_db_query运行Format answer组织答案—— 清晰呈现查询结果。以 README 中给出的示例问题 How many customers are from Canada? 为例Agent 的执行路径就是列出表 → 找到 Customer 表 → 查询 schema → 执行 COUNT 查询 → 返回数量。该流程与 AGENTS.md 中 Example Approach 一节描述的简单问题处理方式List tables → Find Customer table → Query schema → Execute COUNT query一一对应说明常驻记忆memory与按需技能skills在指令层面是相互印证的。复杂查询工作流多表问题的四阶段方法论当问题需要跨多张表时技能要求 Agent 从直接写 SQL切换到先规划再执行阶段 1用write_todos规划write_todos是 Deep Agents 框架提供的任务拆解工具。技能要求在处理复杂查询前先完成 4 项规划确认所有需要的表梳理表间关系外键规划 JOIN 结构确定聚合方式。值得注意的是deepagents 核心库对write_todos有严格的并发约束。在 test_todo_middleware.py 的test_todo_middleware_rejects_multiple_write_todos_in_same_message用例中可以看到同一消息中并行调用多次write_todos会被中间件拦截并返回错误因为该工具should never be called multiple times in parallel。这解释了为何技能中write_todos总是作为串行规划动作出现。阶段 2逐一检查表结构对参与查询的每一张表调用sql_db_schema目的是找到正确的连接列JOIN columns与所需字段。这一步与 schema-exploration 技能的能力重叠后者负责列出全部表 → 获取指定表结构 → 映射实体关系前者负责基于已知结构写出正确查询两者在复杂任务中常被顺序触发。阶段 3构造查询技能给出了完整的 SQL 构造检查单子句要点SELECT只选择需要的列与聚合表达式FROM / JOIN以 FK PK 的方式连接表WHERE在聚合之前完成过滤GROUP BY覆盖所有非聚合列ORDER BY按有意义的字段排序LIMIT默认 5 行阶段 4验证并执行执行前先自查所有 JOIN 都有连接条件、GROUP BY 完整然后再运行查询。示例按国家统计营收Revenue by Country技能文档给出了一个可直接运行的完整示例将上述方法论落成 SQLSELECT c.Country, ROUND(SUM(i.Total), 2) as TotalRevenue FROM Invoice i INNER JOIN Customer c ON i.CustomerId c.CustomerId GROUP BY c.Country ORDER BY TotalRevenue DESC LIMIT 5;该示例演示了技能强调的几个要点表别名iInvoice与cCustomer避免长表名重复书写JOIN 条件ON i.CustomerId c.CustomerId通过外键连接聚合 舍入SUM(i.Total)后用ROUND(..., 2)保留两位小数GROUP BY 完整性非聚合列c.Country全部进入 GROUP BYLIMIT 5符合默认 5 行的质量准则。数据来源是示例项目内置的 Chinook 数据库SQLite这是一个模拟数字媒体商店的样例库包含艺术家、专辑、曲目、客户、发票、员工等 11 张表覆盖了从简单计数到多表聚合的典型查询场景。错误恢复查询失败时的三条处置路径技能明确要求当查询失败或返回结果异常时按下述三类问题分别处理空结果Empty results—— 对照 schema 核对列名与 WHERE 条件检查大小写敏感性问题与 NULL 值语法错误Syntax error—— 复查 JOIN 条件、GROUP BY 完整性以及别名引用超时Timeout—— 收紧 WHERE 过滤条件或减小 LIMIT缩小结果集后再细化。这与 AGENTS.md 中 If a query fails, analyze the error and rewrite 的指导一致也符合 agent.py 中对异常的兜底处理逻辑捕获异常并输出错误面板。质量准则可复制的 SQL 输出规范技能文档最后给出了 5 条质量准则这些准则同时约束着 Agent 的输出质量与安全性只查询相关列不使用SELECT *始终应用 LIMIT默认 5 行使用表别名提升可读性复杂查询先用write_todos规划绝不使用 DML 语句INSERT、UPDATE、DELETE、DROP。其中禁止 DML不仅是技能层的建议更是 AGENTS.md 中 Safety Rules 的硬性约束除了上述 4 种语句ALTER、TRUNCATE、CREATE 也被列入禁用清单Agent 仅拥有 SELECT 只读权限。技能文档与常驻记忆在此形成了准则 底线的双层防护。底层实现SKILL.md 是如何被按需加载的query-writing/SKILL.md之所以能以元数据 全文两级形态工作背后是 deepagents 核心库的 SkillsMiddleware。从源码可以看到其关键设计SKILL.md 格式约定每个技能是一个目录内含SKILL.md必需的 YAML frontmatter Markdown 指令与可选辅助文件frontmatter 必须包含name与descriptionname需与所在目录名一致_validate_skill_namedescription上限 1024 字符Progressive disclosure渐进式披露中间件在before_agent阶段仅加载每个技能的元数据名称、描述、路径注入系统提示词完整指令留待模型判断命中后通过read_file读取——这正是 README 中所述 The agent sees skill descriptions in its context but only loads the full SKILL.md instructions when it determines which skill is needed 的源码级体现多来源叠加技能可从多个来源按顺序加载后加载的同名技能覆盖先加载的last one wins从而支持 base → user → project → team 的技能分层。完整调用链从用户提问到格式化答案结合 README.md 中的架构图与 agent.py 的实现query-writing技能生效的完整链路为用户自然语言提问 ↓ Deep Agent携带 AGENTS.md 常驻记忆 ├─ 命中 skills 描述 → 按需加载 query-writing / schema-exploration 全文 ├─ write_todos复杂问题先规划 ├─ SQL 工具SQLDatabaseToolkit │ ├─ sql_db_list_tables列全部表 │ ├─ sql_db_schema查表结构、示例行、主外键 │ ├─ sql_db_query_checker校验语法 │ └─ sql_db_query执行查询 └─ FilesystemBackend可选保存中间结果 ↓ SQLite Chinook 数据库 ↓ 格式化答案其中 SQL 工具来自langchain_community的SQLDatabaseToolkit见 agent.py与 SKILL.md 中使用的sql_db_schema、sql_db_query等工具名对应。项目依赖在 pyproject.toml 中声明包括deepagents0.6.12、langchain、langchain-anthropic、sqlalchemy等。运行验证要在本地复现该技能的实际效果可先按 README 准备环境Python 3.11、Anthropic API Key、Chinook SQLite 库随后通过 CLI 触发python agent.py Which employee generated the most revenue by country?该问题属于典型的多表分析场景Agent 会依次执行write_todos规划 → 检查 Employee、Invoice、InvoiceLine、Customer 表结构 → 编写 JOIN 聚合查询 → 执行并格式化答案。你可以在终端中直接观察query-writing技能所定义的每一步工作流是如何被逐条兑现的。小结query-writing/SKILL.md是一个把SQL 领域知识编码为 Agent 可执行流程的范本简单查询走 5 步标准流程复杂查询以write_todos规划为先导配合 schema-exploration 技能完成表结构探查再以错误恢复与质量准则兜底。结合 deepagents 的 SkillsMiddleware 源码可以确认这种元数据先行、全文按需加载的渐进式披露机制让技能既能在上下文中保持轻量又能在关键时刻提供完整的领域级指令。若你想为其他 Agent 场景如数据分析、报表生成编写技能本文梳理的结构、frontmatter 规范与质量准则可以直接作为起点。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考