企业官网建设流程全解析

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 是一个稳定的四步流程，任何"问数据库长什么样"的问题都可以套用：

1. List All Tables（列全表）：调用sql_db_list_tables工具，拿到当前数据库中可查询的全部表名清单，这是后续所有步骤的地图。
2. Get Schema for Specific Tables（取指定表结构）：调用sql_db_schema工具并传入表名，返回五个维度的信息：
   • 列名（Column names）——表中有哪些字段可用；
   • 数据类型（Data types）——如INTEGER、TEXT、DATETIME等；
   • 样例数据（Sample data）——默认返回 3 行示例，用于理解内容形态；
   • 主键（Primary keys）——行的唯一标识；
   • 外键（Foreign keys）——与其他表的关联点。
3. Map Relationships（映射关系）：识别表之间的连接方式，要点包括：
   • 寻找以Id结尾的列（例如CustomerId、ArtistId），这类列通常是关联线索；
   • 外键指向另一张表的主键；
   • 记录父子层级关系（parent-child）。
4. Answer the Question（回答问题）：将探索结果组织成清晰答复，覆盖可用表及用途、各列含义、表间关系，以及用于说明内容的样例数据。

值得指出的是，这套流程所依赖的两个 SQL 工具并非 Deep Agents 框架内置，而是来自langchain-community的SQLDatabaseToolkit。在 agent.py 中可以看到它们被统一装配的过程：

toolkit = SQLDatabaseToolkit(db=db, llm=model) 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) - Customer's first name - LastName (NVARCHAR) - Customer's 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_info=3的配置，见 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, you'll 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 disclosure）：Agent 只在上下文中看到每个技能的description摘要，只有当它判定当前任务需要该技能时，才会从后端加载完整的 SKILL.md 正文。这种设计让长技能指令不常驻上下文，保持上下文窗口高效，同时又在需要时提供深度专业知识。text-to-sql-agent 的 README 也明确说明了这一模式在示例中的运用。

在 agent.py 中，技能通过skills=["./skills/"]参数传入create_deep_agent，与memory=["./AGENTS.md"]（常驻身份与规则）、tools=sql_tools、backend=FilesystemBackend(root_dir=base_dir)一起构成完整的 Agent 装配。其中 AGENTS.md 承担"始终加载"的全局约束（只读权限、默认 LIMIT 5、禁止 DML 等安全规则），而 schema-exploration 这类技能则在需要时按需加载，二者共同实现"常驻规则 + 按需专家"的分层指令体系。

实战：在 text-to-sql-agent 中触发本技能

要实际观察 schema-exploration 技能被调用，只需在 text-to-sql-agent 目录下用自然语言提问即可。以下问题类型会命中该技能的触发条件（依据 frontmatter 中的description）：

python 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