第十章: LangGraph的人机交互Human-in-the-loop实践

1. Agent 中为什么需要人机交互?

1.1 问题的由来

我们目前已经能够实现的最复杂的 AI Agent 逻辑是:具备多外部工具支持的完全自主循环代理结构,同时具备多轮对话的上下文记忆能力。这种能力已经能应对大部分 AI 应用场景。

但一个有趣且现实的情况是:我们希望 Agent 能自主处理任务,可当它真的有能力做到时,我们又开始担心它可能做出不当的决策------尤其是涉及高风险操作时。比如:

  • Agent 可能不小心删除生产环境中的数据库;
  • Agent 可能转移账户中的余额等敏感数据。

这些操作是无法容忍的。因此在自主代理架构下,衍生出了一个非常明确的需求:

能否在保持 Agent 自主决策的基础上,对某些可预见的关键节点引入人工干预,暂时中止其自我决策过程,转而由人工介入审批和确认,再让其继续执行后续任务?

典型场景如:

场景 人机交互的作用
删除数据库操作 Agent 决定删除数据库时先中止,等人工确认后才真正执行
机票改签操作 Agent 决定改签时向用户发出通知,用户确认后 Agent 才继续执行

通过这种方式,既能保持 Agent 的自主性,又能避免意外或不可控的风险,实现人机协作的平衡。

1.2 这项技术的名称

实现这种功能的技术,在 Agent 领域被普遍称之为 Human-in-the-loop(HIL,人机交互/人在回路)。

在 LangGraph 的设计思路下,常见的用户交互模式有三种:

  1. 批准(Approval) :人工暂停代理的自主工作流,向用户展示当前状态,由用户批准或不批准执行该操作。(最常用)
  2. 编辑(Editing):人工暂停代理后,允许用户对代理当前的状态进行编辑修改。
  3. 输入(Input):专门设计一个图节点来收集用户的输入,并将这些输入直接用于更新代理的状态。

2. LangGraph 的人机交互实现原理

2.1 核心思路:断点(breakpoint)

LangGraph 底层是通过图结构来构建的,并由**状态(State)**做消息的传递。想在这样的架构中加入人工介入,大致思路是:

通过 Router Agent 做判断,如果生成的响应触发了某种条件(比如高风险操作),就在原本要正常进入的节点之前先停止,等待人工确认,再决定要不要执行、或者执行什么逻辑。

HIL 在 LangGraph 中是通过战略性地放置断点(breakpoint)来实现的------断点会在关键点停止图的执行。暂停期间,Agent 等待用户输入,利用这段时间收集人工响应、将它集成到图状态中,然后顺利继续运行,从而实现用户和代理之间的协作式交互体验。

这个交互过程可以概括为下面的流程(示意图):

2.2 为什么中断后还能继续?------checkpointer

LangGraph 能够在中断后继续运行的核心在于 checkpointer 组件。它能在独立的线程中保存图中每个节点的状态。由于这些信息被持久化保存(包括将内存用作持久存储),我们可以随时提取并修改图产生的数据;更改完成后,再把数据重新传回图中继续运行。

因此要明确两个概念:

  1. breakpoint(断点) :用于中断两个本应顺序执行的节点的操作,这就是 LangGraph 中对断点的称呼;
  2. breakpoint 是构建在 checkpointer 之上的 :没有 checkpointer 保存状态,中断后就无从恢复。

换句话说,HIL 并不是一个全新的组件,而是基于 LangGraph 底层的 checkpointer 延展出来的一种实现方法。

2.3 在代码中如何开启 HIL

当我们需要在图结构中加入人机交互时,图必须具备两个核心参数,正如 compile() 方法的源码所示:

python 复制代码
def compile(
    self,
    checkpointer: Checkpointer = None,    # 状态检查点:负责保存图的状态(HIL 的地基)
    *,
    store: Optional[BaseStore] = None,
    interrupt_before: Optional[Union[All, list[str]]] = None,  # 断点:在指定节点【之前】中断图运行
    interrupt_after: Optional[Union[All, list[str]]] = None,   # 断点:在指定节点【之后】中断图运行
    debug: bool = False,
) -> "CompiledStateGraph":

参数含义一目了然:

  • checkpointer:接收任意类型的 checkpointer,用来保存图的状态(例如内存版的 MemorySaver);
  • interrupt_before:接收图中某个(或某些)节点的名称,将其作为 breakpoint,在该节点执行之前中断图的运行;
  • interrupt_after:在该节点执行之后中断图的运行。

3. Graph 中添加断点实践

3.1 案例需求

实现一个自动化的人机交互流程,用于执行内容删除这种高度敏感性的操作:

  • 用户输入包含"删除"字样 → 触发人工审批流程,图在审批节点前暂停,等人工回复"是/否"决定是否执行;
  • 用户输入是普通问答 → 直接调用大模型回答,无需审批;
  • 最后统一加一个翻译节点,把回复翻译成英文。

3.2 实现分析

定义三个节点:

节点 职责
call_model 处理用户输入:包含"删除"则标记"请人工确认";否则直接调用大模型回答
execute_users 根据 user_approval 字段中人工写入的"是/否"决定最终响应内容
translate_message 把最终回复翻译成英文

关键点:在编译图时设置 interrupt_before=["execute_users"],图就会在进入人工审批节点之前暂停,等我们通过 update_state 把人工决策写进状态后,再恢复运行。

3.3 完整实现代码

python 复制代码
from typing import TypedDict
from langgraph.graph import StateGraph, START, END, MessagesState
from langgraph.checkpoint.memory import MemorySaver
from langchain_openai import ChatOpenAI
from langchain_core.messages import SystemMessage, HumanMessage, AIMessage

# ============ 1. 初始化大模型(这里使用 deepseek-chat) ============
llm = ChatOpenAI(
    model="deepseek-chat",              # 使用 deepseek-chat 作为基座模型
    api_key="sk-xxxxxxxx",              # 替换为你的 DeepSeek API Key
    base_url="https://api.deepseek.com",  # DeepSeek 的 OpenAI 兼容接口地址
    temperature=0,
)

# ============ 2. 定义状态模式 ============
class State(TypedDict):
    user_input: str       # 用户的原始输入
    model_response: str   # 模型最终响应
    user_approval: str    # 人工审批结果("是"/"否"),由人工在断点处写入

# ============ 3. 定义节点函数 ============
# 节点1:与大模型交互的节点
def call_model(state):
    messages = state["user_input"]
    if '删除' in state["user_input"]:
        # 输入包含"删除"→ 标记为高危操作,写入提示语等待人工确认
        state["user_approval"] = f"用户输入的指令是:{state['user_input']}, 请人工确认是否执行!"
    else:
        # 普通问答 → 直接调用大模型生成回答
        response = llm.invoke(messages)
        state["user_approval"] = "直接运行!"   # 标记无需人工审批
        state["model_response"] = response
    return state

# 节点2:人工审批后的执行逻辑(断点所在节点)
def execute_users(state):
    if state["user_approval"] == "是":
        # 人工批准 → 返回执行成功的响应
        response = "您的删除请求已经获得管理员的批准并成功执行。"
        return {"model_response": AIMessage(response)}
    elif state["user_approval"] == "否":
        # 人工拒绝 → 返回拒绝执行的响应
        response = "对不起,您当前的请求是高风险操作,管理员不允许执行!"
        return {"model_response": AIMessage(response)}
    else:
        return state

# 节点3:翻译节点,把最终响应翻译成英文
def translate_message(state: State):
    system_prompt = "Please translate the received text in any language into English as output"
    messages = state['model_response']
    messages = [SystemMessage(content=system_prompt)] + [HumanMessage(content=messages.content)]
    response = llm.invoke(messages)
    return {"model_response": response}

# ============ 4. 构建状态图 ============
builder = StateGraph(State)

# 向图中添加节点
builder.add_node("call_model", call_model)
builder.add_node("execute_users", execute_users)
builder.add_node("translate_message", translate_message)

# 构建边:START → call_model → execute_users → translate_message → END
builder.add_edge(START, "call_model")
builder.add_edge("call_model", "execute_users")
builder.add_edge("execute_users", "translate_message")
builder.add_edge("translate_message", END)

# ============ 5. 编译图:设置 checkpointer + 断点 ============
# 设置 checkpointer,使用内存存储(断点依赖它保存状态)
memory = MemorySaver()

# interrupt_before=["execute_users"]:在 execute_users 节点之前中止图的运行,等待人工审核
graph = builder.compile(checkpointer=memory, interrupt_before=["execute_users"])

3.4 运行测试:图会在断点处停下

python 复制代码
# 创建一个线程(thread_id 用于区分不同的会话/任务)
config = {"configurable": {"thread_id": "2"}}

# 运行图,直至运行到断点节点之前
async for chunk in graph.astream(
    {"user_input": "我将在数据库中删除 id 为 lilaoshi 的所有信息"},
    config,
    stream_mode="values",
):
    print(chunk)

输出结果:

text 复制代码
{'user_input': '我将在数据库中删除 id 为 lilaoshi 的所有信息'}
{'user_input': '...', 'user_approval': '用户输入的指令是:...删除..., 请人工确认是否执行!'}

可以观察到:图在执行到 execute_users 节点之前就暂停了 ,等待人工介入决定是否继续。这就是断点的关键作用。此时可以审查并调整图的状态------关键是修改状态中的 user_approval 字段,从而指导 execute_users 节点的行为。

3.5 查看断点处的状态快照

通过 get_state() 方法,可以查看截至断点前图的运行产生了哪些状态信息:

python 复制代码
snapshot = graph.get_state(config)
snapshot

返回的 StateSnapshot 中包含几个关键信息:

  • values:当前图状态(包含 user_input 和 user_approval);
  • next:('execute_users',),说明下一个待执行的节点就是断点节点;
  • tasks:待执行任务列表(execute_users)。

3.6 写入人工决策并恢复执行

第一步:把人工的"批准/拒绝"写进状态。

python 复制代码
# 模拟人工审批:手动把 user_approval 设置为"是"(批准)
snapshot.values['user_approval'] = '是'
# 调用 update_state 把包含人工决策的最新状态更新回图中
graph.update_state(config, snapshot.values)

第二步:以 input=None 恢复图运行。

python 复制代码
# input 参数传 None,图会从上次中断的地方(断点处)继续执行
async for chunk in graph.astream(None, config, stream_mode="values"):
    print(chunk)

输出:

text 复制代码
{'user_input': '...', 'user_approval': '是'}                                   # 人工批准后的状态
{'user_input': '...', 'model_response': AIMessage('您的删除请求已经获得管理员的批准并成功执行。'), 'user_approval': '是'}   # execute_users 执行
{'user_input': '...', 'model_response': AIMessage('Your deletion request has been approved by the administrator...'), 'user_approval': '是'}  # 翻译节点执行

如果把人工决策改为 '否' 再恢复运行,则 execute_users 会返回"对不起,您当前的请求是高风险操作,管理员不允许执行!"。

普通问答无需审批 :如果用户输入不包含"删除"(如"你好,请你介绍一下你自己"),user_approval 为"直接运行!",在断点处无需写入任何决策,直接 astream(None) 即可让图继续执行完剩余节点。

3.7 封装成多轮对话流程

把上述"运行至断点 → 人工确认 → 恢复执行"的过程封装成完整的多轮对话:

python 复制代码
def run_dialogue(graph, config, all_chunks=[]):
    while True:
        # 接收用户输入
        user_input = input("请输入您的消息(输入'退出'结束对话):")
        if user_input.lower() == '退出':
            break

        # 第一阶段:运行图,直至到断点的节点
        for chunk in graph.stream({"user_input": user_input}, config, stream_mode="values"):
            all_chunks.append(chunk)

        # 第二阶段:处理可能的审批请求(判断 user_approval 是否为"请人工确认"提示语)
        last_chunk = all_chunks[-1]
        if last_chunk["user_approval"] == f"用户输入的指令是:{last_chunk['user_input']}, 请人工确认是否执行!":
            # 让人工输入 是/否,并把决策更新到图状态中
            user_approval = input(f"当前用户的输入是:{last_chunk['user_input']}, 请人工确认是否执行!请回复 是/否。")
            graph.update_state(config, {"user_approval": user_approval})

        # 第三阶段:以 input=None 恢复图执行至结束
        for chunk in graph.stream(None, config, stream_mode="values"):
            all_chunks.append(chunk)

        # 显示最终模型的响应
        print("人工智能助理:", all_chunks[-1]["model_response"].content)


config = {"configurable": {"thread_id": "3"}}
run_dialogue(graph, config)

运行效果:普通提问直接得到回答;一旦输入"帮我删除id是li123的用户",系统会暂停并提示人工回复"是/否",回复"是"则执行、回复"否"则拒绝。

3.8 实现要点小结

在图中的特定位置添加断点是启用人机协同的一种方法------只要开发人员知道工作流中的哪个位置需要人工输入,就在该节点之前/之后放置断点即可。具体要执行的关键步骤是:

  1. 图编译时通过 interrupt_before 或 interrupt_after 设置断点;
  2. 图编译时设置一个 checkpointer 来保存图的状态;
  3. 图暂停后,使用 .get_state() 查看状态、.update_state() 更新状态(写入人工响应);
  4. 将 input 参数设为 None 恢复图执行,等待图运行结束,输出最终响应。

这种策略特别适用于有明确工作流的业务场景:开发人员可以根据业务逻辑精确确定哪些环节涉及高风险操作,通过人工决策介入提升 Agent 应用的稳定性和可靠性。


4. Graph 中添加动态断点实践

4.1 从静态断点到动态断点

第 3 节的案例是在普通节点 上加断点,由我们自己在代码里判断是否需要审批。接下来看更贴近真实 Agent 的场景:在具备工具调用的 Agent 架构(Tool Calling / ReAct)中添加断点。

最直接的做法:如果希望在执行任意一个工具之前 都由人工审核,只需在编译图时给 action(工具执行节点)加断点即可。

先准备两个外部工具(一个实时检索互联网信息、一个查询实时天气):

python 复制代码
from langchain_core.tools import tool
from pydantic import BaseModel, Field
import requests, json

# 工具参数的 Schema 定义
class WeatherLoc(BaseModel):
    location: str = Field(description="The location name of the city")

class SearchQuery(BaseModel):
    query: str = Field(description="Questions for networking queries")

# 工具1:联网检索实时信息
@tool(args_schema=SearchQuery)
def fetch_real_time_info(query):
    """Get real-time Internet information"""
    url = "https://google.serper.dev/search"
    payload = json.dumps({"q": query, "num": 1})   # 构建搜索请求体
    headers = {
        'X-API-KEY': '你的serper_api_key',          # 替换为自己的 API Key
        'Content-Type': 'application/json'
    }
    response = requests.post(url, headers=headers, data=payload)
    data = json.loads(response.text)               # 将返回的JSON字符串转换为字典
    if 'organic' in data:
        return json.dumps(data['organic'], ensure_ascii=False)  # 返回搜索结果
    else:
        return json.dumps({"error": "No organic results found"}, ensure_ascii=False)

# 工具2:查询指定城市当前天气(OpenWeather API)
@tool(args_schema=WeatherLoc)
def get_weather(location):
    """Function to query current weather."""
    url = "https://api.openweathermap.org/data/2.5/weather"   # OpenWeather 接口地址
    params = {
        "q": location,        # 城市名(中国的城市需用英文,如 Beijing)
        "appid": "你的openweather_api_key",   # 输入API key
        "units": "metric",    # 使用摄氏度
        "lang": "zh_cn"       # 输出语言为简体中文
    }
    response = requests.get(url, params=params)  # 发送GET请求
    data = response.json()                       # 解析响应
    return json.dumps(data)

使用 ToolNode 组件将普通函数处理成实际可执行的工具节点,并构建标准的 Tool Calling Agent 图:

python 复制代码
from langgraph.prebuilt import ToolNode
from langgraph.graph import MessagesState, START, END, StateGraph
from langgraph.checkpoint.memory import MemorySaver
from langchain_openai import ChatOpenAI

# 构建可执行的工具节点
tools = [get_weather, fetch_real_time_info]
tool_node = ToolNode(tools)

# 初始化大模型(deepseek-chat)并绑定工具
llm = ChatOpenAI(model="deepseek-chat", api_key="sk-xxxxxxxx",
                 base_url="https://api.deepseek.com", temperature=0)
llm = llm.bind_tools(tools)

# 路由函数:根据大模型响应判断下一步走向
def should_continue(state):
    messages = state["messages"]
    last_message = messages[-1]
    if not last_message.tool_calls:
        # 没有工具调用 → 直接输出最终响应
        return "end"
    else:
        # 还有工具调用需要执行 → 继续执行工具
        return "continue"

# 大模型交互节点:接收用户消息,生成响应(可能包含工具调用)
def call_model(state):
    messages = state["messages"]
    response = llm.invoke(messages)
    return {"messages": [response]}

# 构建图:状态图 → 添加节点 → 添加边
workflow = StateGraph(MessagesState)
workflow.add_node("agent", call_model)
workflow.add_node("action", tool_node)
workflow.add_edge(START, "agent")
# 添加条件边:agent 根据 should_continue 的结果走向 action 或 END
workflow.add_conditional_edges("agent", should_continue, {"continue": "action", "end": END})
workflow.add_edge("action", "agent")   # 工具执行完回到 agent 继续推理

# 关键一步:编译时在 action 节点之前添加断点 → 执行任意工具前都暂停等人工批准
memory = MemorySaver()
graph = workflow.compile(checkpointer=memory, interrupt_before=["action"])

其结构如下(示意图):

4.2 动态断点的定义

像上面这样给 action 节点加断点,呈现出来的特性是**"一刀切"**:要么整个流程完全停止,要么全部通过。而现实中一个 Agent 往往有数十甚至上百个工具,其中只有少数涉及高风险或敏感操作。

动态断点(dynamic breakpoints)指的就是:在图结构中,可以根据某些条件,从给定节点内部动态地中断图 。即------在保留自主循环的同时,仅在 Agent 自行判断必须执行敏感工具或操作时,才触发人工介入机制。

事实上第 3 节中已经用到了这种思想:

python 复制代码
# 节点内部根据状态值动态决定行为(而非所有输入都走审批)
def execute_users(state):
    if state["user_approval"] == "是":
        ...
    elif state["user_approval"] == "否":
        ...

以及在多轮对话逻辑中,根据 user_approval 的状态值采用不同的状态更新策略:

python 复制代码
if last_chunk["user_approval"] == f"用户输入的指令是:{last_chunk['user_input']}, 请人工确认是否执行!":
    user_approval = input("...请回复 是/否。")
    graph.update_state(config, {"user_approval": user_approval})

5. Graph 中添加动态断点测试

对 4.1 编译好的 Tool Calling Agent 图进行实际调用测试:

第一轮:发起需要调用工具的请求,图会在工具执行前暂停。

python 复制代码
config = {"configurable": {"thread_id": "4"}}

# 运行图:大模型判断需要调用 get_weather 工具,随后图在 action 之前中断
for chunk in graph.stream({"messages": "请帮我查一下北京的天气"}, config, stream_mode="values"):
    chunk["messages"][-1].pretty_print()

输出:

text 复制代码
================================ Human Message =================================
请帮我查一下北京的天气
================================== Ai Message ==================================
Tool Calls:
  get_weather (call_xxx)
  Args:
    location: Beijing

与不加断点的执行过程不同,输出停在工具调用(Tool Calls)这一步,并没有真正的执行结果 ------图已在 action 节点前自动中断。

第二轮:人工批准后,以 input=None 恢复执行。

python 复制代码
# input=None 表示将已持久化的全部状态传回图,从中断处恢复执行
for chunk in graph.stream(None, config, stream_mode="values"):
    chunk["messages"][-1].pretty_print()

输出:

text 复制代码
================================== Ai Message ==================================
Tool Calls:
  get_weather (call_xxx)
  Args:
    location: Beijing
================================= Tool Message =================================
Name: get_weather
{"coord": {...}, "weather": [{"main": "Clear", "description": "晴"}], "main": {"temp": 2.83, ...}}
================================== Ai Message ==================================
北京的当前天气状况如下:
- 天气:晴
- 温度:2.83°C
...

当 input 参数传入 None 时,会把状态模式中全部已产生的消息数据传回图,所以执行过程看起来就像没有中断一样,顺利完成了所有节点的执行逻辑。另一个工具 fetch_real_time_info 同理:只要 Agent 判断需要调用它,仍然会在执行前停止,等待人工批准。


6. LangGraph 的人机交互机制 Human-in-the-loop 应用案例详解

6.1 案例需求

实现一个灵活且自主的天气信息管理系统,通过四个工具函数操作天气数据:

工具 功能 风险等级
get_weather 输入城市名,调用 OpenWeather API 获取当前天气(JSON 格式) 低
insert_weather_to_db 将获取的天气数据存入 MySQL 数据库 低
query_weather_from_db 按城市名查询已存储的天气信息 低
delete_weather_from_db 删除指定城市的天气信息 高危

核心需求:仅当用户需求触发 Agent 判断需要执行 delete_weather_from_db 这个高危工具时,才由人工介入决定是否执行删除操作;其余工具正常自主执行,不打扰人工。

6.2 实现分析

如何做到"只对高危工具断点,其他工具照常执行"?关键设计是:

  1. 在路由函数中做条件判断 :should_continue 除了判断"是否还有工具调用",再增加一个分支------如果工具名是 delete_weather_from_db,就路由到专门的 run_tool 节点;否则路由到普通的 action 节点。
  2. 断点只加在 run_tool 节点上 :普通工具走 action(无断点、完全自主);高危工具走 run_tool(有断点、必须人工批准)。

这样,"是否中断"就由 Agent 的工具调用决策动态触发,而不是对所有工具一刀切。整体流程如下(示意图):

6.3 第一步:建立数据库表

python 复制代码
from sqlalchemy import create_engine, Column, Integer, String, Float
from sqlalchemy.orm import sessionmaker, declarative_base

# 创建 ORM 基类
Base = declarative_base()

# 定义 WeatherInfo 数据模型(对应数据库中的 weather 表)
class Weather(Base):
    __tablename__ = 'weather'
    city_id = Column(Integer, primary_key=True)   # 城市ID(主键)
    city_name = Column(String(50))                # 城市名称
    main_weather = Column(String(50))             # 主要天气状况
    description = Column(String(100))             # 天气描述
    temperature = Column(Float)                   # 当前温度
    feels_like = Column(Float)                    # 体感温度
    temp_min = Column(Float)                      # 最低温度
    temp_max = Column(Float)                      # 最高温度

# 数据库连接 URI:用户名:密码@服务器IP/数据库名,字符集用 utf8mb4 支持中文
DATABASE_URI = 'mysql+pymysql://用户名:密码@localhost/langgraph?charset=utf8mb4'
engine = create_engine(DATABASE_URI)

# 如果表不存在则自动创建表
Base.metadata.create_all(engine)

# 创建会话工厂,后续每次数据库操作都从它创建新会话
Session = sessionmaker(bind=engine)

6.4 第二步:定义四个外部工具函数

python 复制代码
from langchain_core.tools import tool
from pydantic import BaseModel, Field
import requests, json

# ---------- 各工具的参数 Schema ----------
class WeatherLoc(BaseModel):
    location: str = Field(description="The location name of the city")

class WeatherInfo(BaseModel):
    """插入数据库时需要的完整天气信息字段"""
    city_id: int = Field(..., description="The unique identifier for the city")
    city_name: str = Field(..., description="The name of the city")
    main_weather: str = Field(..., description="The main weather condition")
    description: str = Field(..., description="A detailed description of the weather")
    temperature: float = Field(..., description="Current temperature in Celsius")
    feels_like: float = Field(..., description="Feels-like temperature in Celsius")
    temp_min: float = Field(..., description="Minimum temperature in Celsius")
    temp_max: float = Field(..., description="Maximum temperature in Celsius")

class QueryWeatherSchema(BaseModel):
    city_name: str = Field(..., description="The name of the city to query weather information")

class DeleteWeatherSchema(BaseModel):
    city_name: str = Field(..., description="The name of the city to delete weather information")

# ---------- 工具1:获取实时天气 ----------
@tool(args_schema=WeatherLoc)
def get_weather(location):
    """
    Function to query current weather.
    中国城市需使用英文名,如查询北京应输入 'Beijing'。
    """
    url = "https://api.openweathermap.org/data/2.5/weather"  # OpenWeather 接口地址
    params = {
        "q": location,                     # 城市名
        "appid": "你的openweather_api_key",  # API key
        "units": "metric",                 # 摄氏度
        "lang": "zh_cn"                    # 中文输出
    }
    response = requests.get(url, params=params)  # 发送GET请求
    data = response.json()                       # 解析JSON响应
    return json.dumps(data)

# ---------- 工具2:将天气信息插入数据库 ----------
@tool(args_schema=WeatherInfo)
def insert_weather_to_db(city_id, city_name, main_weather, description,
                         temperature, feels_like, temp_min, temp_max):
    """Insert weather information into the database."""
    session = Session()  # 每次操作创建新会话
    try:
        # 根据参数创建天气数据实例
        weather = Weather(
            city_id=city_id, city_name=city_name, main_weather=main_weather,
            description=description, temperature=temperature, feels_like=feels_like,
            temp_min=temp_min, temp_max=temp_max,
        )
        session.add(weather)      # 添加到会话
        session.commit()          # 提交事务
        return {"messages": [f"天气数据已成功存储至Mysql数据库。"]}
    except Exception as e:
        session.rollback()        # 出错时回滚
        return {"messages": [f"数据存储失败,错误原因:{e}"]}
    finally:
        session.close()           # 关闭会话

# ---------- 工具3:按城市名查询数据库中的天气信息 ----------
@tool(args_schema=QueryWeatherSchema)
def query_weather_from_db(city_name: str):
    """Query weather information from the database by city name."""
    session = Session()
    try:
        weather_data = session.query(Weather).filter(Weather.city_name == city_name).first()
        if weather_data:
            # 找到记录 → 以字典形式返回全部字段
            return {
                "city_id": weather_data.city_id, "city_name": weather_data.city_name,
                "main_weather": weather_data.main_weather, "description": weather_data.description,
                "temperature": weather_data.temperature, "feels_like": weather_data.feels_like,
                "temp_min": weather_data.temp_min, "temp_max": weather_data.temp_max,
            }
        else:
            return {"messages": [f"未找到城市 '{city_name}' 的天气信息。"]}
    except Exception as e:
        return {"messages": [f"查询失败,错误原因:{e}"]}
    finally:
        session.close()

# ---------- 工具4(高危):按城市名删除数据库中的天气信息 ----------
@tool(args_schema=DeleteWeatherSchema)
def delete_weather_from_db(city_name: str):
    """Delete weather information from the database by city name."""
    session = Session()
    try:
        weather_data = session.query(Weather).filter(Weather.city_name == city_name).first()
        if weather_data:
            session.delete(weather_data)  # 删除记录
            session.commit()
            return {"messages": [f"城市 '{city_name}' 的天气信息已成功删除。"]}
        else:
            return {"messages": [f"未找到城市 '{city_name}' 的天气信息。"]}
    except Exception as e:
        session.rollback()
        return {"messages": [f"删除失败,错误原因:{e}"]}
    finally:
        session.close()

# ---------- 构建可执行的工具节点 ----------
from langgraph.prebuilt import ToolNode
tools = [get_weather, insert_weather_to_db, query_weather_from_db, delete_weather_from_db]
tool_node = ToolNode(tools)

6.5 第三步:定义模型节点与路由函数(动态断点的核心)

python 复制代码
from langchain_openai import ChatOpenAI

# 初始化大模型(deepseek-chat)并绑定全部工具
llm = ChatOpenAI(model="deepseek-chat", api_key="sk-xxxxxxxx",
                 base_url="https://api.deepseek.com", temperature=0)
llm = llm.bind_tools(tools)

# 大模型交互节点:分析用户意图,决定是否调用工具
def call_model(state):
    messages = state["messages"]
    response = llm.invoke(messages)
    return {"messages": [response]}

# 路由函数:动态断点的关键!
def should_continue(state):
    messages = state["messages"]
    last_message = messages[-1]
    if not last_message.tool_calls:
        # 没有工具调用 → 直接结束,输出最终响应
        return "end"
    elif last_message.tool_calls[0]["name"] == "delete_weather_from_db":
        # 工具调用是【删除】这种高危操作 → 路由到带断点的 run_tool 节点
        return "run_tool"
    else:
        # 其余普通工具 → 路由到无断点的 action 节点,正常自主执行
        return "continue"

# 高危工具的执行节点(断点就设在这个节点之前)
def run_tool(state):
    new_messages = []
    tool_calls = state["messages"][-1].tool_calls
    # 注意:这里只注册高危工具 delete_weather_from_db
    tools = [delete_weather_from_db]
    tools = {t.name: t for t in tools}
    for tool_call in tool_calls:
        tool = tools[tool_call["name"]]
        result = tool.invoke(tool_call["args"])   # 真正执行删除
        new_messages.append({
            "role": "tool",
            "name": tool_call["name"],
            "content": result,
            "tool_call_id": tool_call["id"],
        })
    return {"messages": new_messages}

6.6 第四步:构建并编译图

python 复制代码
from langgraph.graph import MessagesState, START, END, StateGraph
from langgraph.checkpoint.memory import MemorySaver

workflow = StateGraph(MessagesState)

# 添加三个节点
workflow.add_node("agent", call_model)
workflow.add_node("action", tool_node)
workflow.add_node("run_tool", run_tool)

workflow.add_edge(START, "agent")

# 条件边:agent 依据 should_continue 走向三种不同去向
workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "continue": "action",     # 普通工具 → action
        "run_tool": "run_tool",   # 高危工具 → run_tool(此前有断点)
        "end": END,               # 无工具 → 结束
    },
)

workflow.add_edge("action", "agent")     # 普通工具执行完回到 agent
workflow.add_edge("run_tool", "agent")   # 高危工具执行完也回到 agent

# 编译:断点只设置在 run_tool 节点之前 → 只有删除操作才会触发人工审批
memory = MemorySaver()
graph = workflow.compile(checkpointer=memory, interrupt_before=["run_tool"])

6.7 第五步:功能测试

测试1:常规天气咨询与入库(不触发断点,完全自主执行)。

python 复制代码
config = {"configurable": {"thread_id": "100"}}

for chunk in graph.stream({"messages": "北京的天气怎么样?并把数据插入数据库中"},
                          config, stream_mode="values"):
    chunk["messages"][-1].pretty_print()

执行过程:Agent 依次调用 get_weather 获取北京实时天气 → 调用 insert_weather_to_db 入库 → 输出总结,全程无中断。

测试2:触发高危删除操作(图在 run_tool 前暂停)。

python 复制代码
for chunk in graph.stream({"messages": "帮我删除数据库中北京的天气数据"},
                          config, stream_mode="values"):
    chunk["messages"][-1].pretty_print()

输出停在工具调用处,说明 Agent 判断需要执行 delete_weather_from_db 时并没有自主执行,而是进入断点状态等待人工介入。此时可以查看图状态确认暂停位置:

python 复制代码
state = graph.get_state(config)
print(state.next)    # ('run_tool',)  → 下一个待执行节点是 run_tool,即断点处
print(state.tasks)   # 待执行任务列表
print(state.values)  # 当前全部消息状态

测试3:人工批准 → 恢复执行删除。

python 复制代码
# input=None 恢复中断的执行,删除操作真正被执行
for chunk in graph.stream(None, config, stream_mode="values"):
    chunk["messages"][-1].pretty_print()

输出:

text 复制代码
================================= Tool Message =================================
Name: delete_weather_from_db
{'messages': ["城市 'Beijing' 的天气信息已成功删除。"]}
================================== Ai Message ==================================
数据库中北京的天气信息已成功删除。

6.8 关键进阶:人工拒绝时如何优雅地"模拟"工具反馈

当人工回复**"否"(不允许执行)**时,不能直接恢复运行(否则工具还是会执行)。解决思路是:

把人工的自然语言反馈,作为一条"模拟的工具调用返回数据"插入到状态中 ------即构造一条 role=tool 的消息,其 tool_call_id 与待响应的工具调用 ID 相同,内容为拒绝信息,并通过 update_state(..., as_node="run_tool") 伪装成 run_tool 节点已经执行完毕。这样 Agent 读到的工具结果是"管理员不允许执行该操作!",自然会向用户转达拒绝。

python 复制代码
config = {"configurable": {"thread_id": "101"}}

for chunk in graph.stream({"messages": "帮我删除数据库中杭州的天气数据"}, config, stream_mode="values"):
    state = graph.get_state(config)

    # 如果没有待执行任务,说明整轮已运行结束
    if not state.tasks:
        chunk["messages"][-1].pretty_print()
        break

    # 检查是否停在了高危工具的动态断点上
    if state.tasks[0].name == 'run_tool':
        # 循环收集人工决策,只接受"是/否"
        while True:
            user_input = input("是否允许执行删除操作?请输入'是'或'否':")
            if user_input in ["是", "否"]:
                break
            else:
                print("输入错误,请输入'是'或'否'。")

        if user_input == "是":
            # 批准:更新状态后恢复执行,真正执行删除
            graph.update_state(config=config, values=chunk)
            for event in graph.stream(None, config, stream_mode="values"):
                event["messages"][-1].pretty_print()
        elif user_input == "否":
            # 拒绝:取出当前待响应的工具调用 ID
            state = graph.get_state(config)
            tool_call_id = state.values["messages"][-1].tool_calls[0]["id"]

            # 构造一条"模拟的工具返回消息",ID 必须与原工具调用 ID 一致
            new_message = {
                "role": "tool",
                "content": "管理员不允许执行该操作!",   # 人工拒绝的反馈
                "name": "delete_weather_from_db",
                "tool_call_id": tool_call_id,
            }
            # 以 as_node="run_tool" 写入 → 相当于替 run_tool 节点"执行"了这次工具调用
            graph.update_state(config, {"messages": [new_message]}, as_node="run_tool")
            for event in graph.stream(None, config, stream_mode="values"):
                event["messages"][-1].pretty_print()

输出效果:

text 复制代码
是否允许执行删除操作?请输入'是'或'否': 否
================================= Tool Message =================================
Name: delete_weather_from_db
管理员不允许执行该操作!
================================== Ai Message ==================================
抱歉,管理员不允许执行删除数据库中的天气数据。如果您还有其他需要,欢迎告诉我!

注意关键点 :更新 state 时,模拟的工具数据消息的 ID 必须与要响应的工具调用 ID 相同,这样 Agent 才能把"拒绝"这条反馈和之前的工具调用请求正确配对。

6.9 封装为完整的多轮人机交互代理

python 复制代码
def run_multi_round_dialogue(graph, config):
    while True:  # 多轮对话循环
        user_input = input("请输入您的问题(例如:'帮我查询上海的天气数据'),输入'退出'结束对话:")
        if user_input.lower() == '退出':
            print("对话已结束。")
            break

        # 运行图并实时检查状态
        for chunk in graph.stream({"messages": user_input}, config, stream_mode="values"):
            state = graph.get_state(config)

            # 没有待执行任务 → 本轮结束,打印最终回复
            if not state.tasks:
                if "messages" in chunk and len(chunk["messages"]) > 0:
                    print("人工智能助理:", chunk["messages"][-1].content)
                break

            # 停在动态断点(run_tool 之前)→ 请求人工审批
            if state.tasks[0].name == 'run_tool':
                while True:
                    user_approval = input("是否允许执行删除操作?请输入'是'或'否':")
                    if user_approval in ["是", "否"]:
                        break
                    else:
                        print("输入错误,请输入'是'或'否'。")

                if user_approval == "是":
                    # 批准 → 更新状态并恢复执行
                    graph.update_state(config=config, values=chunk)
                    for event in graph.stream(None, config, stream_mode="values"):
                        if "messages" in event and len(event["messages"]) > 0:
                            print("人工智能助理:", event["messages"][-1].content)
                elif user_approval == "否":
                    # 拒绝 → 构造模拟工具反馈,让 Agent 知道操作被禁止
                    state = graph.get_state(config)
                    tool_call_id = state.values["messages"][-1].tool_calls[0]["id"]
                    new_message = {
                        "role": "tool",
                        "content": "管理员不允许执行该操作!",
                        "name": "delete_weather_from_db",
                        "tool_call_id": tool_call_id,
                    }
                    graph.update_state(config, {"messages": [new_message]}, as_node="run_tool")
                    for event in graph.stream(None, config, stream_mode="values"):
                        if "messages" in event and len(event["messages"]) > 0:
                            print("人工智能助理:", event["messages"][-1].content)


config = {"configurable": {"thread_id": "102"}}
run_multi_round_dialogue(graph, config)

实测效果:

  • 普通问答("请你介绍一下自己")→ 直接回答,无需审批;
  • 查天气并入库("帮我查询大理,丽江,北京三个地方的天气信息")→ 自主调用工具完成,无需审批;
  • 删除操作("删除数据库里面大理的天气信息")+ 回复"是" → 断点暂停,批准后真正删除;
  • 删除操作("帮我删除数据库里面丽江的天气信息")+ 回复"否" → 断点暂停,拒绝后 Agent 转达"系统不允许删除";
  • 全程保持多轮上下文记忆。

总结

  1. 为什么需要 HIL :完全自主循环的 Agent 在落地时会面临高风险操作失控的风险(如删除数据库、资金操作),因此需要"保持自主决策 + 关键节点人工审批 "的人机协作平衡,这项技术就是 Human-in-the-loop。

  2. 实现原理 :HIL 基于 breakpoint(断点) 实现,而断点构建在 checkpointer 之上------图运行到断点时暂停,状态已被 checkpointer 持久化;人工通过 get_state() 审查、update_state() 修改状态后,再以 input=None 恢复执行。它不是新组件,而是既有底层组件延展出的实现方法。图编译时的 interrupt_before / interrupt_after 参数用于指定断点位置。

  3. 静态断点 :在明确的节点(如审批节点、工具执行节点 action)之前/之后放置断点,适合工作流明确 的业务场景。核心四步:设置断点 → 设置 checkpointer → update_state 写入人工响应 → input=None 恢复执行。

  4. 动态断点 :静态断点对所有工具"一刀切",而真实 Agent 中只有少数工具是高危的。动态断点通过路由函数按条件分流 (高危工具 → 带断点的 run_tool 节点;普通工具 → 自主的 action 节点),实现"只在 Agent 判断要执行敏感操作时才触发人工介入"。

  5. 人工拒绝的优雅处理 :拒绝时不恢复原执行,而是构造一条与原 tool_call_id 相同的模拟 ToolMessage (内容为拒绝信息),用 update_state(..., as_node="run_tool") 写入状态,让 Agent 自然地获知"操作被禁止"并向用户转达。

  6. 整体价值 :通过断点与状态更新的组合,人工决策可以无缝集成到代理的工作流中,允许实时干预和审批工具选择,增强整个 AI 系统的可信性和健壮性------这完全是在 checkpointer 等既有知识之上,通过合理化应用技巧实现的更具落地价值的 Agent 形态。

相关推荐
泯泷3 小时前
AI Agent 工具设计:给模型装上“手脚”,为什么不能只会调用 API?
人工智能·llm·agent
xyphf_和派孔明4 小时前
第六章: LangGraph的工具调用代理-Tool Calling Agent
langchain·llm
泯泷5 小时前
AI Agent 工具设计:能执行任务的 Agent,先要学会何时停手
llm·agent
土豆125017 小时前
dsh-orchestrator 介绍与使用实践:让你的 AI 从「一个人硬扛」到「带团队干活
llm·ai编程·deepseek
M--Y17 小时前
LangGraph 工作流模式
开发语言·javascript·python·langchain·大模型·llm·langgraph
泯泷17 小时前
AI Agent 工具设计:接了上百个工具,为什么反而更难干活?
llm·agent
泯泷19 小时前
AI Agent 工具设计:读完一百页 PDF,不等于真的看懂了
人工智能·llm·agent
泯泷21 小时前
AI 怎样"查资料"?——RAG 检索增强生成入门(三)
人工智能·llm
xyphf_和派孔明1 天前
第五章: LangGraph的路由代理-Router Agent介绍
langchain·llm