1. Agent 中为什么需要人机交互?
1.1 问题的由来
我们目前已经能够实现的最复杂的 AI Agent 逻辑是:具备多外部工具支持的完全自主循环代理结构,同时具备多轮对话的上下文记忆能力。这种能力已经能应对大部分 AI 应用场景。
但一个有趣且现实的情况是:我们希望 Agent 能自主处理任务,可当它真的有能力做到时,我们又开始担心它可能做出不当的决策------尤其是涉及高风险操作时。比如:
Agent可能不小心删除生产环境中的数据库;Agent可能转移账户中的余额等敏感数据。
这些操作是无法容忍的。因此在自主代理架构下,衍生出了一个非常明确的需求:
能否在保持 Agent 自主决策的基础上,对某些可预见的关键节点引入人工干预,暂时中止其自我决策过程,转而由人工介入审批和确认,再让其继续执行后续任务?
典型场景如:
| 场景 | 人机交互的作用 |
|---|---|
| 删除数据库操作 | Agent 决定删除数据库时先中止,等人工确认后才真正执行 |
| 机票改签操作 | Agent 决定改签时向用户发出通知,用户确认后 Agent 才继续执行 |
通过这种方式,既能保持 Agent 的自主性,又能避免意外或不可控的风险,实现人机协作的平衡。
1.2 这项技术的名称
实现这种功能的技术,在 Agent 领域被普遍称之为 Human-in-the-loop(HIL,人机交互/人在回路)。
在 LangGraph 的设计思路下,常见的用户交互模式有三种:
- 批准(Approval) :人工暂停代理的自主工作流,向用户展示当前状态,由用户批准或不批准执行该操作。(最常用)
- 编辑(Editing):人工暂停代理后,允许用户对代理当前的状态进行编辑修改。
- 输入(Input):专门设计一个图节点来收集用户的输入,并将这些输入直接用于更新代理的状态。
2. LangGraph 的人机交互实现原理
2.1 核心思路:断点(breakpoint)
LangGraph 底层是通过图结构来构建的,并由**状态(State)**做消息的传递。想在这样的架构中加入人工介入,大致思路是:
通过
Router Agent做判断,如果生成的响应触发了某种条件(比如高风险操作),就在原本要正常进入的节点之前先停止,等待人工确认,再决定要不要执行、或者执行什么逻辑。
HIL 在 LangGraph 中是通过战略性地放置断点(breakpoint)来实现的------断点会在关键点停止图的执行。暂停期间,Agent 等待用户输入,利用这段时间收集人工响应、将它集成到图状态中,然后顺利继续运行,从而实现用户和代理之间的协作式交互体验。
这个交互过程可以概括为下面的流程(示意图):

2.2 为什么中断后还能继续?------checkpointer
LangGraph 能够在中断后继续运行的核心在于 checkpointer 组件。它能在独立的线程中保存图中每个节点的状态。由于这些信息被持久化保存(包括将内存用作持久存储),我们可以随时提取并修改图产生的数据;更改完成后,再把数据重新传回图中继续运行。
因此要明确两个概念:
breakpoint(断点) :用于中断两个本应顺序执行的节点的操作,这就是LangGraph中对断点的称呼;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 实现要点小结
在图中的特定位置添加断点是启用人机协同的一种方法------只要开发人员知道工作流中的哪个位置需要人工输入,就在该节点之前/之后放置断点即可。具体要执行的关键步骤是:
- 图编译时通过
interrupt_before或interrupt_after设置断点; - 图编译时设置一个
checkpointer来保存图的状态; - 图暂停后,使用
.get_state()查看状态、.update_state()更新状态(写入人工响应); - 将
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 实现分析
如何做到"只对高危工具断点,其他工具照常执行"?关键设计是:
- 在路由函数中做条件判断 :
should_continue除了判断"是否还有工具调用",再增加一个分支------如果工具名是delete_weather_from_db,就路由到专门的run_tool节点;否则路由到普通的action节点。 - 断点只加在
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 转达"系统不允许删除";
- 全程保持多轮上下文记忆。
总结
-
为什么需要 HIL :完全自主循环的 Agent 在落地时会面临高风险操作失控的风险(如删除数据库、资金操作),因此需要"保持自主决策 + 关键节点人工审批 "的人机协作平衡,这项技术就是
Human-in-the-loop。 -
实现原理 :HIL 基于
breakpoint(断点) 实现,而断点构建在checkpointer之上------图运行到断点时暂停,状态已被checkpointer持久化;人工通过get_state()审查、update_state()修改状态后,再以input=None恢复执行。它不是新组件,而是既有底层组件延展出的实现方法。图编译时的interrupt_before/interrupt_after参数用于指定断点位置。 -
静态断点 :在明确的节点(如审批节点、工具执行节点
action)之前/之后放置断点,适合工作流明确 的业务场景。核心四步:设置断点 → 设置 checkpointer →update_state写入人工响应 →input=None恢复执行。 -
动态断点 :静态断点对所有工具"一刀切",而真实 Agent 中只有少数工具是高危的。动态断点通过路由函数按条件分流 (高危工具 → 带断点的
run_tool节点;普通工具 → 自主的action节点),实现"只在 Agent 判断要执行敏感操作时才触发人工介入"。 -
人工拒绝的优雅处理 :拒绝时不恢复原执行,而是构造一条与原
tool_call_id相同的模拟 ToolMessage (内容为拒绝信息),用update_state(..., as_node="run_tool")写入状态,让 Agent 自然地获知"操作被禁止"并向用户转达。 -
整体价值 :通过断点与状态更新的组合,人工决策可以无缝集成到代理的工作流中,允许实时干预和审批工具选择,增强整个 AI 系统的可信性和健壮性------这完全是在
checkpointer等既有知识之上,通过合理化应用技巧实现的更具落地价值的 Agent 形态。