• angChain = 组件库 + 简单链：做 RAG、问答、单步工具调用最方便；
• LangGraph = 状态机 + 流程编排：把复杂逻辑画成图、能循环、能分支、能断点续跑；
• Deep Agents = 基于 LangGraph 的「企业级 Agent 脚手架」：自带规划、文件上下文、子 Agent、长期记忆，开箱即用做长任务.
• LangChain（基础）→ LangGraph（编排）→ Deep Agents（成品智能体框架）

Deep Agents（2026 年初 LangChain 官方出）

• 定位：LangGraph 的企业级封装（Agent Harness）；
• 核心内置能力（你最关心）：
  1. 自动规划（write_todos）：复杂任务自动拆成待办列表，跟踪进度；
  2. 文件系统上下文：大日志 / 代码直接读写文件，突破上下文窗口限制；
  3. 子 Agent 生成（task 工具）：主 Agent 自动派生子 Agent，上下文隔离；
  4. 长期记忆：跨会话记住历史，不用每次重说背景；
  5. 沙箱执行：安全跑代码、SQL、脚本；
• 适合：复杂工业智能体、长周期任务、需要多技能协作；
• 优点：开箱即用，代码极少；缺点：封装较厚，底层自由度略低于纯 LangGraph。

特性	LangChain	LangGraph	Deep Agents
形态	线性链	状态图	自主大脑
复杂度	低–中	高	极高
状态管理	弱（短时）	强（持久）	极强（长期）
任务规划	无	需自定义	内置
文件处理	无	需自定义	内置
子 Agent	无	需自定义	内置
上手难度	低	中–高	中（开箱即用）
你的场景适配	简单问答 / Text2SQL	自定义流程	直接做完整智能体

# 安装核心包
uv add langchain langgraph deepagents

DEEPAGENTS-SQL-AGENT
|                 
├── skills/                   # 【核心：所有技能统一存放目录，一个子文件夹=1个独立Skill】
│   ├── query-writing/        # 技能1：SQL编写技能
│   │   └── SKILL.md          # 当前技能的声明配置（描述、能力、工具定义，DeepAgents自动读取）
│   └── schema-exploration/   # 技能2：数据库表结构探查技能
│       └── SKILL.md
├── .env                      # 环境配置：大模型Key、数据库连接串、参数配置
├── AGENT.md                  # 主Agent全局配置（Supervisor角色、系统Prompt、技能加载规则）
|── agent.py                  # 项目入口启动文件（实例化主Agent、加载配置、启动服务/交互）

中间件全部是 DeepAgents 框架内部自动注册，不用你手写中间件代码，你在create_deep_agent()时传入skills=[]/memory=[]参数，框架就自动挂载对应中间件，你的 agent.py 没有显式写中间件代码，是框架内部封装。

用户提问→

1. Skills 中间件：加载两个技能、注入技能说明；
2. Patch 工具中间件：预处理 4 个 SQL 工具；
3. Memory 中间件：加载 AGENT.md 规则；
4. Qwen 模型：判断先用 schema-exploration 技能→调用查表工具；
5. Todo 中间件：下发工具执行；
6. tools 执行完回流 model→模型再切 query-writing 技能执行 SQL；
7. 最终无工具调用→end 输出答案

deepagents自动创建的智能体架构,太方便了

我们看一下skill怎么写,这里有三个skill,先看一下AGENT.md

# Text-to-SQL智能体全局配置【AGENT.md：Agent身份证】
## 一、角色定义 Your Role
你是一个专门对接SQL数据库的智能数据分析Agent，收到用户自然语言提问后，必须严格按固定步骤完成查询：
1.  探查数据库全部可用数据表；
2.  查看问题关联数据表的字段结构、表关联关系；
3.  生成语法完全正确的SELECT查询SQL；
4.  执行SQL语句并解析返回数据结果；
5.  将查询结果整理成通顺、易读的自然语言回复用户。

## 二、安全约束规则 Safety Rules
### 禁止执行语句清单
严禁执行任何修改/删改数据库的SQL指令：
- INSERT、UPDATE、DELETE、DROP、ALTER、TRUNCATE、CREATE等DDL/DML变更语句
### 权限说明
本Agent仅拥有数据库**只读权限**，**只允许生成并执行SELECT查询语句**。

## 三、复杂问题任务规划规则 Planning for Complex Questions
遇到多条件、多表关联的复杂统计类问题，必须分步拆解任务：
1.  调用内置`write_todos`工具拆解任务，生成分步待办清单；
2.  清单中明确本次查询需要探查哪些数据表；
3.  预先规划SQL关联逻辑、查询结构；
4.  编写SQL、执行查询并校验数据结果合理性。

## 四、全局技能调度规则（关键：对应skills目录下两个技能）
框架会自动扫描项目`skills/`文件夹下全部子技能：
1.  `schema-exploration`（库表探查技能）：需要查表名、字段、表结构时自动调用；
2.  `query-writing`（SQL编写执行技能）：拿到表结构后自动调用，生成+运行SQL；
> Agent自主判断调度顺序：**优先查表结构→再生成SQL执行**，无需人工编码流程。

## 五、兜底应答规则（适配你最开始的多助手架构逻辑）
用户提问不在数据库查询范畴（闲聊、笑话、对联、无关需求），直接礼貌拒绝：「我仅能提供数据库数据查询服务，无法解答该类问题。」

1、AGENT.md 核心定位

• 不再像 LangChain 一样把超长 system_prompt 硬编码在 Python 代码里，配置与代码分离；
• 只写三大核心：「我是谁（角色）+ 该干什么（步骤）+ 不能干什么（约束）+ 技能调度规则」

文件	存放内容	作用
AGENT.md（根目录）	全局角色、安全红线、跨技能调度、兜底逻辑	管控整个 Agent 的顶层行为 = 你的 Supervisor 总控
SKILL.md（每个 skill 子文件夹）	单个技能专属描述、绑定本技能内部工具	定义单个子助手能干什么

skill.md怎么写

---
name: query-writing
description: 根据表结构生成安全、正确的 SQL 查询语句，并执行查询，仅支持 SELECT 只读操作
---

# SQL 查询编写与执行技能

## 功能
1. 根据用户需求生成标准 SQL
2. 检查 SQL 安全性，禁止增删改
3. 执行 SQL 并返回结果
4. 将结果转为自然语言

## 调用时机
获取表结构之后，执行数据查询时使用。

## 安全规则
- 只允许 SELECT 查询
- 禁止 INSERT、UPDATE、DELETE、DROP、ALTER

import os
from dotenv import load_dotenv
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from langchain_openai import ChatOpenAI
from langchain_community.agent_toolkits import SQLDatabaseToolkit
from langchain_community.utilities import SQLDatabase

# 加载环境配置
load_dotenv()

def create_sql_deep_agent():
    base_dir = os.path.dirname(os.path.abspath(__file__))

    # ==========【改动点：替换为MySQL连接，删掉sqlite Chinook】==========
    # 读取.env内MySQL配置
    db_host = os.getenv("DB_HOST", "127.0.0.1")
    db_port = os.getenv("DB_PORT", "3306")
    db_user = os.getenv("DB_USER")
    db_pwd = os.getenv("DB_PASSWORD")
    db_name = os.getenv("DB_NAME")

    # MySQL连接串：mysql+pymysql://账号:密码@地址:端口/库名?字符集
    mysql_uri = (
        f"mysql+pymysql://{db_user}:{db_pwd}@{db_host}:{db_port}/{db_name}"
        "?charset=utf8mb4"
    )
    db = SQLDatabase.from_uri(
        database_uri=mysql_uri,
        sample_rows_in_table_info=3,
        # 可选：白名单限定可访问表，比如include_tables=["user","order"]
        # include_tables=[]
    )

    # Qwen3-MAX 伪装OpenAI 配置不变
    model = ChatOpenAI(
        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        model="qwen3-max",
        temperature=0
    )

    toolkit = SQLDatabaseToolkit(db=db, llm=model)
    sql_tools = toolkit.get_tools()

    # DeepAgent实例化完全不动
    agent = create_deep_agent(
        model=model,
        memory=["./AGENT.md"],
        skills=["./skills/"],
        tools=sql_tools,
        subagents=[],
        backend=FilesystemBackend(root_dir=base_dir, virtual_mode=False)
    )
    return agent

agent = create_sql_deep_agent()

if __name__ == "__main__":
    # 输出架构图
    with open("./graph.png", "wb") as f:
        f.write(agent.get_graph().draw_mermaid_png())
    print("智能体架构图已生成 graph.png")

    # 测试提问，改成你自己库的业务问题
    user_input = {"messages": [{"role": "user", "content": "高一(1)班有多少学生"}]}
    # 流式打印执行步骤：先探查表结构→再写SQL→执行MySQL查询
    for step in agent.stream(user_input, stream_mode="values"):
        step["messages"][-1].pretty_print()

这里用到的工具是预定义好的

toolkit = SQLDatabaseToolkit(db=db, llm=model)
sql_tools = toolkit.get_tools()

工具包括：

• sql_db_list_tables → 列出所有表
• sql_db_schema → 查看表结构
• sql_db_query → 执行查询
• sql_db_query_checker → 检查 SQL 是否安全

agent = create_deep_agent(
    model=model,
    memory=["./AGENT.md"],     # 全局角色
    skills=["./skills/"],     # 自动加载 2 个技能
    tools=sql_tools,           # 注入工具
)

这里 DeepAgents 自动做了 3 件事：

1. 读取 AGENT.md → 设定全局角色
2. 读取 skills/ 下 2 个技能 → 构建技能库
3. 把工具绑定给技能 → 技能可以调用工具

用户问题
  ↓
【主Agent（AGENT.md）】
  ↓
调度技能1：schema-exploration（查表）
  ↓
调度技能2：query-writing（写SQL）
  ↓
执行工具 → 查询MySQL
  ↓
返回答案