用 LangGraph 把 Agent 重写成图之后,很多人会停在"能跑"这一步:checkpointer 用的还是 InMemorySaver,进程一退全丢;工具全暴露给模型,危险操作没人拦。

这篇把这两个尾巴收掉。加的东西不多——一处换个 Saver,一处加个审批——但你的 Agent 就从"能跑"变成"敢给人用"了。

01 从内存到 SQLite:换个 Saver,重启不丢

先看你手里现在这行:

checkpointer = InMemorySaver()

InMemorySaver 本质上就是个 Python dict,进程一退全没。换成 SQLite,核心就是换个 Saver 类,再用 with 把连接管住:

from langgraph.checkpoint.sqlite import SqliteSaver

with SqliteSaver.from_conn_string("agent.db") as checkpointer:
    graph = builder.compile(checkpointer=checkpointer)
    graph.invoke({"messages": [HumanMessage(content="北京天气怎么样?")]}, config)

先装依赖:pip install langgraph-checkpoint-sqlite。

跑起来你会发现目录下多了个 agent.db 文件——就是个 SQLite 数据库,每一步状态快照都存在里面。你 Ctrl+C 退出,重新跑,用同一个 thread_id invoke,它自动从数据库加载上次的 messages,接着聊。

这里必须用 with:from_conn_string() 返回的不是 Saver 实例,而是上下文管理器。直接 checkpointer = SqliteSaver.from_conn_string("agent.db") 再交给 compile,会报 TypeError: Invalid checkpointer provided——传进去的是 _GeneratorContextManager,不是 BaseCheckpointSaver。而且 invoke 也得放进 with 里,出了 with 连接就关了,再跑会报 Cannot operate on a closed database。

如果是要长期跑的服务,别用 with,自己建连接一直开着:

conn = sqlite3.connect("agent.db", check_same_thread=False)
checkpointer = SqliteSaver(conn)

那个 check_same_thread=False 不是可选项——SQLite 连接默认只认创建它的那个线程,FastAPI 用线程池一跑就报错,跟 Java 里数据库连接不能跨线程借用一个道理。

建表这块不用你操心:SqliteSaver 初始化时就把 checkpoints 和 writes 两张表建好了,不用手动 setup()。但 PostgresSaver、RedisSaver、MongoDBSaver 这些服务端后端不一样,第一次用都得显式调一次 setup()。

【图1:InMemorySaver 与 SqliteSaver 的差别。左列:InMemorySaver → 进程退出 → 内存清零 → 下次 invoke 从零开始;右列:SqliteSaver → 每个节点执行完写一行 agent.db → 进程退出数据还在 → 重启 + 同一 thread_id 自动加载。深色背景 #0d1117,紫 #a371f7 表示内存态,绿 #3fb950 表示已落盘,右下角水印 @梯度下降的咖啡师。CSDN 发布时上传原图。】

就这么简单。你手写时想了半天的"什么时候存、崩了怎么对齐",LangGraph 在每个节点执行完就把状态写进 SQLite——每个 super-step 存一份快照,节点级的产出另存进 writes 表,不用你管。

其他后端也是换个 Saver 类,图的拼装方式不变;但连接方式不一样——Postgres 和 Redis 有 from_conn_string,MongoDB、DynamoDB 得你自己把 client 传进去:

  • SQLite(本地开发):from langgraph.checkpoint.sqlite import SqliteSaver,pip install langgraph-checkpoint-sqlite
  • PostgreSQL(生产首选):from langgraph.checkpoint.postgres import PostgresSaver,pip install langgraph-checkpoint-postgres
  • MongoDB:from langgraph.checkpoint.mongodb import MongoDBSaver,pip install langgraph-checkpoint-mongodb
  • AWS DynamoDB / Valkey:langgraph-checkpoint-aws 包
  • Redis:from langgraph.checkpoint.redis import RedisSaver,pip install langgraph-checkpoint-redis,需要 RedisJSON 和 RediSearch 模块

Redis 不是不能做 checkpoint,是默认装不上——它要 RedisJSON 和 RediSearch 两个模块(Redis 8.0 以上自带),本地开箱即用一般不选它。它同时也能当 Store 用,做跨线程的长期记忆。MySQL 在官方 checkpointer 列表里没有,生产环境一般直接上 PostgreSQL。

如果你的图跑在 ainvoke 或者 FastAPI 里,换成同一个包里的 from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver:同步版塞进异步上下文,会把事件循环卡住。它同样是异步上下文管理器,用法是:

async with AsyncSqliteSaver.from_conn_string("agent.db") as checkpointer:
    ...

直接赋值照样报 Invalid checkpointer provided;长期服务别用 with,自己持有一条 aiosqlite 的异步连接传进去(注意不是 sqlite3 那条同步连接)。
在这里插入图片描述

02 为什么需要人工刹车

工具列表全暴露给模型的时候,查天气、查 AQI 是只读的,问题不大。但如果你的工具里有 send_email()、delete_user()——模型被一句话诱导就真的会去调。

Java 后端对这个味道太熟了:写操作接口不能裸奔,必须在关键节点加审批。Agent 也一样——高风险操作不能让模型自己决定,得暂停下来等人点"确认"。

LangGraph 里这个能力叫 Interrupt。你在节点函数里调一个 interrupt(),图就暂停在这一步,把这次中断的 payload 放进返回值的 __interrupt__ 里交给你。你看完决定继续还是拒绝,再用同一个 thread_id 调一次 graph.invoke(Command(resume="approve"), config)——图会把这个节点从头再跑一遍,这次 interrupt() 直接返回你传的值,接着往下走。

放到产品里,这就是两个接口:一个提交任务、把待审批的 payload 交给前端,一个提交审批结果(Command(resume=...))。中间隔多久都行,状态在 SQLite 里躺着。

03 给 tools_node 加审批

在已有的 LangGraph 版基础上,加一个需要审批的工具 send_email,然后改 tools_node。注意还有一处必须顺手改:原来的 tools schema 列表里只有 get_weather 和 get_aqi,得把 send_email 的定义也加进去——不然模型根本不知道有这个工具,永远不会调它。

from langgraph.types import interrupt, Command

# 加一个"危险"工具
def send_email(to: str, subject: str, body: str) -> str:
    return f"邮件已发送给 {to}:{subject}"

tool_map = {
    "get_weather": get_weather,
    "get_aqi": get_aqi,
    "send_email": send_email,
}

# tools schema 列表里也要补一条 send_email 的定义,bind_tools(tools) 那行不用动

# 哪些工具需要人工审批
DANGEROUS_TOOLS = {"send_email", "delete_user", "transfer_money"}


def tools_node(state: AgentState):
    last = state["messages"][-1]
    calls = last.tool_calls

    # 先把危险调用挑出来,一次性问人
    # tool_calls 里每一项都是 dict,取字段用 tc["name"],不是 tc.name
    dangerous = [tc for tc in calls if tc["name"] in DANGEROUS_TOOLS]
    decision = "approve"
    if dangerous:
        names = "、".join(tc["name"] for tc in dangerous)
        decision = interrupt({
            "tools": [{"tool": tc["name"], "args": tc["args"]} for tc in dangerous],
            "message": f"Agent 想执行 {names},批准吗?",
        })

    # 执行放到 interrupt 之后:恢复时节点从头重跑,工具只会在这一次真正被执行
    results = []
    for tc in calls:
        if tc["name"] in DANGEROUS_TOOLS and decision != "approve":
            # 拒绝也要回一条 ToolMessage,否则下一轮调模型会报错
            # 文案要点明"不要再重试",否则模型反复重提,审批就成了死循环
            results.append(ToolMessage(
                content=f"用户拒绝执行 {tc['name']},不要再重试这个操作",
                tool_call_id=tc["id"],
            ))
            continue
        try:
            result = tool_map[tc["name"]](**tc["args"])
        except Exception as e:
            result = f"工具调用失败: {e}"
        results.append(ToolMessage(content=result, tool_call_id=tc["id"]))
    return {"messages": results}

两点说明:上面 DANGEROUS_TOOLS 里的 delete_user、transfer_money 只是示意,没进 tools schema 模型也不会调,实际项目换成你自己的危险工具;ToolMessage、HumanMessage 沿用文件开头的 import,这里只贴改动部分。

运行方式和之前不一样了——第一次 invoke 遇到 interrupt 会暂停:

config = {"configurable": {"thread_id": "user-001"}}

# 第一次跑,遇到 send_email 会暂停
result = graph.invoke(
    {"messages": [HumanMessage(content="帮我发个邮件给 boss@company.com,说这周周报写完了")]},
    config
)

# 图停在了 interrupt(),这里能拿到审批请求
print(result["__interrupt__"])
# (Interrupt(value={'tools': [...], 'message': '...'}, id='...', response_schema=None),)
# __interrupt__ 是 Interrupt 对象的元组,真正的 payload 要再取一层 .value
pending = result["__interrupt__"][0].value
print(pending["message"])  # Agent 想执行 send_email,批准吗?

# 你看完觉得没问题,批准
graph.invoke(Command(resume="approve"), config)

# 不批准就传 "reject",tools_node 会给这条调用回"用户拒绝执行…"的 ToolMessage

你看,审批逻辑全在 tools_node 里——先把危险工具挑出来,一次性 interrupt 问人,批准了再统一执行。你不用自己写 while 循环等输入,不用自己管理暂停状态,框架帮你存好了。暂停状态也写进了 SQLite——你重启进程,用同一个 thread_id 调 Command(resume="approve"),它还能接着审批。

(这条我实测过:进程退出后新起一个进程,get_state 还能看到 next=('tools',) 和待处理的中断,接着 resume 就跑完了。)

这里有个必须知道的坑:LangGraph 恢复时,节点函数会从头重新执行,不是从 interrupt() 那一行接着跑。所以 interrupt 之前的代码会再跑一遍——这也是上面把"执行工具"放在 interrupt 之后的原因。要是你先执行了只读工具再 interrupt,恢复时那个工具会被重复调用一次。官方文档的原话是:interrupt 之前的副作用必须幂等。写业务工具时记住这条,尤其是发请求、写数据库这种。

还有一条同样致命:别把 interrupt() 包进 try/except。它是靠抛一个内部异常来暂停图的,你一个 except Exception 把它 catch 掉,图就永远停不下来——现象是"点了审批没反应"。上面这段代码里 try/except 只包住工具执行,是有意的。

【图2:Interrupt 的暂停与恢复。五步横向流程:① agent_node 模型决定调 send_email → ② tools_node 第 1 轮挑出危险工具,interrupt() 暂停 → ③ 人工审批看 interrupt,approve / reject → ④ tools_node 第 2 轮从头重跑,interrupt() 这次直接返回审批结果 → ⑤ 执行工具,返回 ToolMessage。第 ④ 步用红色线框高亮标出"这里最容易踩坑",下方三行说明写"恢复时节点从头重新执行,interrupt() 之前的代码会再跑一遍;副作用要么幂等,要么放到 interrupt 之后"。深色背景 #0d1117,紫 #a371f7、绿 #3fb950,右下角水印 @梯度下降的咖啡师。CSDN 发布时上传原图。】

调试的时候你会看到 interrupt 里的 args 是一坨 JSON——模型吐回来的参数结构,格式不对的时候丢到 ForJSON 里格式化看一眼,比在终端 print 清楚。
在这里插入图片描述

04 完整代码

把上面的改动拼回原来的骨架,就是一份能直接跑的实现。改掉 api_key 就能执行:

import sqlite3
from typing import Annotated, TypedDict

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, ToolMessage
from langgraph.graph import StateGraph, START, END
from langgraph.graph.message import add_messages
from langgraph.checkpoint.sqlite import SqliteSaver
from langgraph.types import interrupt, Command

# ===== 工具函数 =====
def get_weather(city: str) -> str:
    return f"{city}今天晴,25度"

def get_aqi(city: str) -> str:
    return f"{city}AQI 50,优"

def send_email(to: str, subject: str, body: str) -> str:
    # 真实项目在这里接 SMTP / 邮件服务
    return f"邮件已发送给 {to}:{subject}"

tool_map = {"get_weather": get_weather, "get_aqi": get_aqi, "send_email": send_email}

# ===== 工具 schema:手写 JSON,不用装饰器 =====
tools = [
    {"type": "function", "function": {
        "name": "get_weather",
        "description": "查询城市天气",
        "parameters": {"type": "object",
                       "properties": {"city": {"type": "string"}},
                       "required": ["city"]}}},
    {"type": "function", "function": {
        "name": "get_aqi",
        "description": "查询城市空气质量",
        "parameters": {"type": "object",
                       "properties": {"city": {"type": "string"}},
                       "required": ["city"]}}},
    {"type": "function", "function": {
        "name": "send_email",
        "description": "发送邮件",
        "parameters": {"type": "object",
                       "properties": {"to": {"type": "string"},
                                      "subject": {"type": "string"},
                                      "body": {"type": "string"}},
                       "required": ["to", "subject", "body"]}}},
]

# ===== State =====
class AgentState(TypedDict):
    messages: Annotated[list, add_messages]   # 这个 Annotated 不能省,否则整体覆盖


# ===== 节点1:调模型 =====
model = ChatOpenAI(
    model="deepseek-v4-flash",
    api_key="你的 DeepSeek API Key",
    base_url="https://api.deepseek.com",
)
model_with_tools = model.bind_tools(tools)


def agent_node(state: AgentState):
    return {"messages": [model_with_tools.invoke(state["messages"])]}


# ===== 节点2:执行工具,危险工具先过人工审批 =====
DANGEROUS_TOOLS = {"send_email"}   # 你的危险工具都加进来:delete_user、transfer_money…


def tools_node(state: AgentState):
    last = state["messages"][-1]
    calls = last.tool_calls

    dangerous = [tc for tc in calls if tc["name"] in DANGEROUS_TOOLS]
    decision = "approve"
    if dangerous:
        names = "、".join(tc["name"] for tc in dangerous)
        decision = interrupt({
            "tools": [{"tool": tc["name"], "args": tc["args"]} for tc in dangerous],
            "message": f"Agent 想执行 {names},批准吗?",
        })

    results = []
    for tc in calls:
        if tc["name"] in DANGEROUS_TOOLS and decision != "approve":
            results.append(ToolMessage(
                content=f"用户拒绝执行 {tc['name']},不要再重试这个操作",
                tool_call_id=tc["id"],
            ))
            continue
        try:
            result = tool_map[tc["name"]](**tc["args"])
        except Exception as e:
            result = f"工具调用失败: {e}"
        results.append(ToolMessage(content=result, tool_call_id=tc["id"]))
    return {"messages": results}


# ===== 条件边:有 tool_calls 去 tools,否则结束 =====
def should_continue(state: AgentState):
    return "tools" if state["messages"][-1].tool_calls else END


# ===== 拼图 =====
builder = StateGraph(AgentState)
builder.add_node("agent", agent_node)
builder.add_node("tools", tools_node)
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", should_continue, {"tools": "tools", END: END})
builder.add_edge("tools", "agent")


# ===== 跑起来 =====
if __name__ == "__main__":
    with SqliteSaver.from_conn_string("agent.db") as checkpointer:
        graph = builder.compile(checkpointer=checkpointer)
        config = {"configurable": {"thread_id": "user-001"}}

        result = graph.invoke(
            {"messages": [HumanMessage(
                content="帮我发个邮件给 boss@company.com,说这周周报写完了"
            )]},
            config,
        )
        pending = result["__interrupt__"][0].value
        print(pending["message"])

        graph.invoke(Command(resume="approve"), config)

这段脚本故意把"暂停"和"恢复"塞进同一个进程里跑,方便你一次看到全过程。真实服务里别这么干——拆成两个接口:POST /tasks 起任务、把 pending 原样返回给前端;POST /tasks/{id}/approval 收审批结果、转成 Command(resume=...) 恢复图。中间隔多久都行,状态在 SQLite 里躺着。

05 上线前还差这两笔

这套东西能给你用了,但真拿到线上,还差两笔:

一是审批没人管会一直挂着——得加超时兜底,定时扫一遍长时间没动的 thread,自动按"拒绝"处理;不然图就永久停在 interrupt() 那一步。

二是谁批的、批了什么、什么时候批,最好落一张审批日志表。出了事能回溯,这比事后看聊天记录靠谱得多。

到这里,你的 Agent 有了图结构、多轮记忆、多用户隔离、重启不丢的状态,还有一道人工刹车。骨架齐了,后面就是在这个骨架上长肉:接什么工具、连什么数据、做什么场景。


聊聊两个问题:

① 你现在最想给 Agent 接的第一个真实工具是什么?

② Interrupt 人工审批这个设计,你觉得在你的场景里是刚需还是过度设计?

咖啡续命,梯度下降。| 作者:梯度下降的咖啡师

Logo

更多推荐