Deep Agents 数据库 Schema 探索技能schema-exploration实战指南从建表清单到外键关系映射【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents本篇技术指南聚焦 text-to-sql 示例中随 Deep Agents 框架分发的schema-exploration技能讲解 Agent 如何通过sql_db_list_tables与sql_db_schema工具完成「列全表 → 取结构 → 映射关系 → 组织回答」四步探索流程并结合仓库源码说明 SKILL.md 的格式约定与渐进式披露progressive disclosure加载机制。读完本文你将掌握一套可复制到任意 SQL Agent 场景中的数据库结构发现方法论并理解技能文件是如何被 Deep Agents 中间件按需注入上下文的。技能定位Agent 认识数据库的第一站schema-exploration是 text-to-sql-agent 示例中的两个内置技能之一完整文件位于 schema-exploration/SKILL.md。它的职责非常聚焦当用户询问数据库 schema、表结构、列类型、有哪些表、ERD、外键或实体关系时Agent 使用它来摸清数据库结构。从技能 frontmatter 的触发描述可以明确其边界--- name: schema-exploration description: Lists tables, describes columns and data types, identifies foreign key relationships, and maps entity relationships in a database. Use when the user asks about database schema, table structure, column types, what tables exist, ERD, foreign keys, or how entities relate. ---它与同目录下的 query-writing 技能形成明确分工schema-exploration 负责认识数据库query-writing 负责写出并执行 SQL。二者通过同一个skills/目录被 Agent 注册由 Agent 根据用户问题的语义决定何时加载哪个技能。四步工作流从全表清单到可回答的答案技能的 Workflow 是一个稳定的四步流程任何问数据库长什么样的问题都可以套用List All Tables列全表调用sql_db_list_tables工具拿到当前数据库中可查询的全部表名清单这是后续所有步骤的地图。Get Schema for Specific Tables取指定表结构调用sql_db_schema工具并传入表名返回五个维度的信息列名Column names——表中有哪些字段可用数据类型Data types——如INTEGER、TEXT、DATETIME等样例数据Sample data——默认返回 3 行示例用于理解内容形态主键Primary keys——行的唯一标识外键Foreign keys——与其他表的关联点。Map Relationships映射关系识别表之间的连接方式要点包括寻找以Id结尾的列例如CustomerId、ArtistId这类列通常是关联线索外键指向另一张表的主键记录父子层级关系parent-child。Answer the Question回答问题将探索结果组织成清晰答复覆盖可用表及用途、各列含义、表间关系以及用于说明内容的样例数据。值得指出的是这套流程所依赖的两个 SQL 工具并非 Deep Agents 框架内置而是来自langchain-community的SQLDatabaseToolkit。在 agent.py 中可以看到它们被统一装配的过程toolkit SQLDatabaseToolkit(dbdb, llmmodel) sql_tools toolkit.get_tools()sql_db_list_tables与sql_db_schema正是该 toolkit 暴露的工具之一它们连同 query checker、执行查询等工具一起被注册到 Agent供技能工作流调用。三个完整示例技能如何落地原文档用三个递进的问答示例完整演示了技能在不同问题类型下的执行路径。这些示例基于Chinook 数据库一个模拟数字媒体商店的 SQLite 示例库包含艺术家、专辑、曲目、客户、发票等业务数据导入方式见 text-to-sql-agent README。示例一What tables are available?只走工作流的第一步调用sql_db_list_tables后Agent 组织成如下回答The Chinook database has 11 tables: 1. Artist - Music artists 2. Album - Music albums 3. Track - Individual songs 4. Genre - Music genres 5. MediaType - File formats (MP3, AAC, etc.) 6. Playlist - User-created playlists 7. PlaylistTrack - Tracks in playlists 8. Customer - Store customers 9. Employee - Store employees 10. Invoice - Customer purchases 11. InvoiceLine - Individual items in invoices这是最简单的探索场景不涉及任何 JOIN只要求给出全量表清单并附带一句话用途说明。示例二What columns does the Customer table have?走工作流的第二步对Customer表调用sql_db_schema得到列清单、类型、键约束与样例数据The Customer table has these columns: - CustomerId (INTEGER) - Primary key, unique customer ID - FirstName (NVARCHAR) - Customers first name - LastName (NVARCHAR) - Customers last name - Company (NVARCHAR) - Company name (optional) - Address, City, State, Country, PostalCode - Location fields - Phone (NVARCHAR) - Phone number - Fax (NVARCHAR) - Fax number - Email (NVARCHAR) - Email address - SupportRepId (INTEGER) - Foreign key to Employee table Sample data shows customers like: - Luís Gonçalves from Brazil - Leonie Köhler from Germany - François Tremblay from Canada这个示例完整展示了技能要求的信息密度不仅列出列名与类型还标注主键CustomerId、外键SupportRepId → Employee并用 3 行真实样例数据对应sample_rows_in_table_info3的配置见 agent.py让回答有血有肉。示例三How do I find revenue by artist?这个问题已经超出探索本身进入如何查询的范畴因此技能演示了探索与查询规划如何衔接。Step 1 识别所需表Artist存艺术家名Album连接艺术家与曲目Track连接专辑与销售InvoiceLine存销售明细Invoice存收入总额Step 2 映射关系链Artist (ArtistId) ↓ 1:many Album (ArtistId, AlbumId) ↓ 1:many Track (AlbumId, TrackId) ↓ 1:many InvoiceLine (TrackId, UnitPrice, Quantity)Step 3 组织回答To find revenue by artist, youll need to: 1. Start with the Artist table 2. JOIN to Album on ArtistId 3. JOIN to Track on AlbumId 4. JOIN to InvoiceLine on TrackId 5. SUM the revenue (UnitPrice * Quantity) 6. GROUP BY artist name This requires the query-writing skill to execute.注意最后一句技能明确把执行 SQL交接给 query-writing 技能。这正是两个技能协作的接口——schema-exploration 负责把关系链画清楚query-writing 负责把它变成可运行的 SQL。质量准则不同问题的回答标准原文档按三类问题分别给出了回答质量基线这也是技能在生成答案时的自查清单对列全表类问题列出所有表名为每张表加一句内容说明按业务域分组如音乐目录、交易、人员。对描述表类问题列出全部列及其数据类型解释每列含义展示样例数据提供上下文标注主键与外键说明与其他表的关系。对如何查询 X类问题识别所需的表绘制 JOIN 路径解释关系链给出下一步建议转交 query-writing 技能。源码视角SKILL.md 如何被 Deep Agents 解析与加载schema-exploration/SKILL.md的格式并非随意约定而是与框架的 Skills 中间件实现严格对应。在 skills.py 中可以看到每个技能是一个包含 SKILL.md 的目录SKILL.md 必须由 YAML frontmatter 加 Markdown 正文组成frontmatter 中name技能标识符最多 64 字符小写字母数字与连字符description技能能力描述最多 1024 字符——正是这段描述在 Agent 上下文中决定何时需要加载该技能可选字段包括license、compatibility、metadata、allowed_tools等。该中间件实现的是 Anthropic 的 agent skills 模式中的渐进式披露progressive disclosureAgent 只在上下文中看到每个技能的description摘要只有当它判定当前任务需要该技能时才会从后端加载完整的 SKILL.md 正文。这种设计让长技能指令不常驻上下文保持上下文窗口高效同时又在需要时提供深度专业知识。text-to-sql-agent 的 README 也明确说明了这一模式在示例中的运用。在 agent.py 中技能通过skills[./skills/]参数传入create_deep_agent与memory[./AGENTS.md]常驻身份与规则、toolssql_tools、backendFilesystemBackend(root_dirbase_dir)一起构成完整的 Agent 装配。其中 AGENTS.md 承担始终加载的全局约束只读权限、默认 LIMIT 5、禁止 DML 等安全规则而 schema-exploration 这类技能则在需要时按需加载二者共同实现常驻规则 按需专家的分层指令体系。实战在 text-to-sql-agent 中触发本技能要实际观察 schema-exploration 技能被调用只需在 text-to-sql-agent 目录下用自然语言提问即可。以下问题类型会命中该技能的触发条件依据 frontmatter 中的descriptionpython agent.py What tables are available in the database? python agent.py What columns does the Customer table have? python agent.py How do invoices relate to customers?运行前的环境准备Python 3.11、Chinook 数据库下载、uv sync安装依赖、.env配置ANTHROPIC_API_KEY均记录在 text-to-sql-agent README 的 Quick Start 一节。提问后Agent 会依次执行 list tables → get schema → map relationships → answer 的完整链路并在最终回答中给出带类型、键约束与样例数据的结构化描述。如果你想在其他项目中复用这套方法论只需把该技能的 SKILL.md 放入你自己的skills/目录并在创建 Deep Agent 时通过skills参数注册——前提是你的 Agent 已装配提供sql_db_list_tables与sql_db_schema的 SQL 工具集如SQLDatabaseToolkit。技能本身不绑定特定数据库任意具备list tables / get schema能力的数据库后端均可套用这套四步探索流程。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Deep Agents 数据库 Schema 探索技能（schema-exploration）实战指南：从建表清单到外键关系映射
Deep Agents 数据库 Schema 探索技能schema-exploration实战指南从建表清单到外键关系映射【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents本篇技术指南聚焦 text-to-sql 示例中随 Deep Agents 框架分发的schema-exploration技能讲解 Agent 如何通过sql_db_list_tables与sql_db_schema工具完成「列全表 → 取结构 → 映射关系 → 组织回答」四步探索流程并结合仓库源码说明 SKILL.md 的格式约定与渐进式披露progressive disclosure加载机制。读完本文你将掌握一套可复制到任意 SQL Agent 场景中的数据库结构发现方法论并理解技能文件是如何被 Deep Agents 中间件按需注入上下文的。技能定位Agent 认识数据库的第一站schema-exploration是 text-to-sql-agent 示例中的两个内置技能之一完整文件位于 schema-exploration/SKILL.md。它的职责非常聚焦当用户询问数据库 schema、表结构、列类型、有哪些表、ERD、外键或实体关系时Agent 使用它来摸清数据库结构。从技能 frontmatter 的触发描述可以明确其边界--- name: schema-exploration description: Lists tables, describes columns and data types, identifies foreign key relationships, and maps entity relationships in a database. Use when the user asks about database schema, table structure, column types, what tables exist, ERD, foreign keys, or how entities relate. ---它与同目录下的 query-writing 技能形成明确分工schema-exploration 负责认识数据库query-writing 负责写出并执行 SQL。二者通过同一个skills/目录被 Agent 注册由 Agent 根据用户问题的语义决定何时加载哪个技能。四步工作流从全表清单到可回答的答案技能的 Workflow 是一个稳定的四步流程任何问数据库长什么样的问题都可以套用List All Tables列全表调用sql_db_list_tables工具拿到当前数据库中可查询的全部表名清单这是后续所有步骤的地图。Get Schema for Specific Tables取指定表结构调用sql_db_schema工具并传入表名返回五个维度的信息列名Column names——表中有哪些字段可用数据类型Data types——如INTEGER、TEXT、DATETIME等样例数据Sample data——默认返回 3 行示例用于理解内容形态主键Primary keys——行的唯一标识外键Foreign keys——与其他表的关联点。Map Relationships映射关系识别表之间的连接方式要点包括寻找以Id结尾的列例如CustomerId、ArtistId这类列通常是关联线索外键指向另一张表的主键记录父子层级关系parent-child。Answer the Question回答问题将探索结果组织成清晰答复覆盖可用表及用途、各列含义、表间关系以及用于说明内容的样例数据。值得指出的是这套流程所依赖的两个 SQL 工具并非 Deep Agents 框架内置而是来自langchain-community的SQLDatabaseToolkit。在 agent.py 中可以看到它们被统一装配的过程toolkit SQLDatabaseToolkit(dbdb, llmmodel) sql_tools toolkit.get_tools()sql_db_list_tables与sql_db_schema正是该 toolkit 暴露的工具之一它们连同 query checker、执行查询等工具一起被注册到 Agent供技能工作流调用。三个完整示例技能如何落地原文档用三个递进的问答示例完整演示了技能在不同问题类型下的执行路径。这些示例基于Chinook 数据库一个模拟数字媒体商店的 SQLite 示例库包含艺术家、专辑、曲目、客户、发票等业务数据导入方式见 text-to-sql-agent README。示例一What tables are available?只走工作流的第一步调用sql_db_list_tables后Agent 组织成如下回答The Chinook database has 11 tables: 1. Artist - Music artists 2. Album - Music albums 3. Track - Individual songs 4. Genre - Music genres 5. MediaType - File formats (MP3, AAC, etc.) 6. Playlist - User-created playlists 7. PlaylistTrack - Tracks in playlists 8. Customer - Store customers 9. Employee - Store employees 10. Invoice - Customer purchases 11. InvoiceLine - Individual items in invoices这是最简单的探索场景不涉及任何 JOIN只要求给出全量表清单并附带一句话用途说明。示例二What columns does the Customer table have?走工作流的第二步对Customer表调用sql_db_schema得到列清单、类型、键约束与样例数据The Customer table has these columns: - CustomerId (INTEGER) - Primary key, unique customer ID - FirstName (NVARCHAR) - Customers first name - LastName (NVARCHAR) - Customers last name - Company (NVARCHAR) - Company name (optional) - Address, City, State, Country, PostalCode - Location fields - Phone (NVARCHAR) - Phone number - Fax (NVARCHAR) - Fax number - Email (NVARCHAR) - Email address - SupportRepId (INTEGER) - Foreign key to Employee table Sample data shows customers like: - Luís Gonçalves from Brazil - Leonie Köhler from Germany - François Tremblay from Canada这个示例完整展示了技能要求的信息密度不仅列出列名与类型还标注主键CustomerId、外键SupportRepId → Employee并用 3 行真实样例数据对应sample_rows_in_table_info3的配置见 agent.py让回答有血有肉。示例三How do I find revenue by artist?这个问题已经超出探索本身进入如何查询的范畴因此技能演示了探索与查询规划如何衔接。Step 1 识别所需表Artist存艺术家名Album连接艺术家与曲目Track连接专辑与销售InvoiceLine存销售明细Invoice存收入总额Step 2 映射关系链Artist (ArtistId) ↓ 1:many Album (ArtistId, AlbumId) ↓ 1:many Track (AlbumId, TrackId) ↓ 1:many InvoiceLine (TrackId, UnitPrice, Quantity)Step 3 组织回答To find revenue by artist, youll need to: 1. Start with the Artist table 2. JOIN to Album on ArtistId 3. JOIN to Track on AlbumId 4. JOIN to InvoiceLine on TrackId 5. SUM the revenue (UnitPrice * Quantity) 6. GROUP BY artist name This requires the query-writing skill to execute.注意最后一句技能明确把执行 SQL交接给 query-writing 技能。这正是两个技能协作的接口——schema-exploration 负责把关系链画清楚query-writing 负责把它变成可运行的 SQL。质量准则不同问题的回答标准原文档按三类问题分别给出了回答质量基线这也是技能在生成答案时的自查清单对列全表类问题列出所有表名为每张表加一句内容说明按业务域分组如音乐目录、交易、人员。对描述表类问题列出全部列及其数据类型解释每列含义展示样例数据提供上下文标注主键与外键说明与其他表的关系。对如何查询 X类问题识别所需的表绘制 JOIN 路径解释关系链给出下一步建议转交 query-writing 技能。源码视角SKILL.md 如何被 Deep Agents 解析与加载schema-exploration/SKILL.md的格式并非随意约定而是与框架的 Skills 中间件实现严格对应。在 skills.py 中可以看到每个技能是一个包含 SKILL.md 的目录SKILL.md 必须由 YAML frontmatter 加 Markdown 正文组成frontmatter 中name技能标识符最多 64 字符小写字母数字与连字符description技能能力描述最多 1024 字符——正是这段描述在 Agent 上下文中决定何时需要加载该技能可选字段包括license、compatibility、metadata、allowed_tools等。该中间件实现的是 Anthropic 的 agent skills 模式中的渐进式披露progressive disclosureAgent 只在上下文中看到每个技能的description摘要只有当它判定当前任务需要该技能时才会从后端加载完整的 SKILL.md 正文。这种设计让长技能指令不常驻上下文保持上下文窗口高效同时又在需要时提供深度专业知识。text-to-sql-agent 的 README 也明确说明了这一模式在示例中的运用。在 agent.py 中技能通过skills[./skills/]参数传入create_deep_agent与memory[./AGENTS.md]常驻身份与规则、toolssql_tools、backendFilesystemBackend(root_dirbase_dir)一起构成完整的 Agent 装配。其中 AGENTS.md 承担始终加载的全局约束只读权限、默认 LIMIT 5、禁止 DML 等安全规则而 schema-exploration 这类技能则在需要时按需加载二者共同实现常驻规则 按需专家的分层指令体系。实战在 text-to-sql-agent 中触发本技能要实际观察 schema-exploration 技能被调用只需在 text-to-sql-agent 目录下用自然语言提问即可。以下问题类型会命中该技能的触发条件依据 frontmatter 中的descriptionpython agent.py What tables are available in the database? python agent.py What columns does the Customer table have? python agent.py How do invoices relate to customers?运行前的环境准备Python 3.11、Chinook 数据库下载、uv sync安装依赖、.env配置ANTHROPIC_API_KEY均记录在 text-to-sql-agent README 的 Quick Start 一节。提问后Agent 会依次执行 list tables → get schema → map relationships → answer 的完整链路并在最终回答中给出带类型、键约束与样例数据的结构化描述。如果你想在其他项目中复用这套方法论只需把该技能的 SKILL.md 放入你自己的skills/目录并在创建 Deep Agent 时通过skills参数注册——前提是你的 Agent 已装配提供sql_db_list_tables与sql_db_schema的 SQL 工具集如SQLDatabaseToolkit。技能本身不绑定特定数据库任意具备list tables / get schema能力的数据库后端均可套用这套四步探索流程。【免费下载链接】deepagentsThe batteries-included agent harness.项目地址: https://gitcode.com/GitHub_Trending/de/deepagents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考