构建具有限制的 LangGraph 工具调用代理,并加入人工审核
一种实用模式:通过明确的步骤限制、对高风险操作进行人工批准,以及可重复的测试用例,评估 LangGraph 工具调用代理。
摘要 · TL;DR
使用图步骤限制约束执行范围,使用 HumanInTheLoopMiddleware 暂停高风险工具调用,并通过一组小型固定测试检查批准、拒绝和达到限制时的行为。请将这些示例视为起点:必须在自己的环境中测试模型和工具的行为。
核心要点
- 图递归限制为代理提供明确的执行边界,但不能保证代理完成任务。
- 当图配置了检查点和线程 ID 后,人工审核可以暂停工具执行,并在之后恢复。
- 固定测试输入、预期结果、工具夹具和执行限制,可以让评估保持可重复。
- 应明确测试被拒绝的操作和达到限制的情况;这两者都不等同于成功恢复。
文章目录 (6)
工具调用代理需要的不只是一个好的提示词:它还需要停止边界、处理高风险操作的方案,以及能够让其行为可重复的测试。在 LangGraph 中,你可以将图递归限制与针对特定工具的人工参与(HITL)审核结合起来。然后,使用固定用例评估工作流,而不是仅依赖少数几次成功运行。
下面的示例仅用于说明,并非经过测试的配置。它假设你使用的是兼容的 LangChain 和 LangGraph 软件包、支持工具调用的聊天模型,以及一个已实现的工具。请在自己的环境中检查版本和模型提供商参数。
在添加工具前确定边界
递归限制用于约束图的执行步骤。它是安全边界,并不保证代理会完成任务,也不是对工具调用次数的精确限制:步骤的计算方式会受到图结构影响。如果执行达到限制,应预期出现图递归错误,并将其作为未完成运行处理。不要将其视为成功响应。
评估期间先使用较小的限制,只有当某个测试用例证明工作流需要更多步骤时,才提高限制。同时,应让工具操作保持明确且范围有限。图级别的限制无法撤销工具已经执行的副作用。
配置可暂停等待审核的工具调用
本示例使用带有 HITL 中间件的 create_agent。write_file 工具需要中断以等待批准或拒绝;read_data 则不需要。工具实现和模型名称均为占位内容。请确认所选模型和端点支持代理所使用的参数及工具调用行为。
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
# Replace these placeholders with your own tool implementations.
tools = [write_file, read_data]
agent = create_agent(
model="your-tool-capable-chat-model",
tools=tools,
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"write_file": {"allowed_decisions": ["approve", "reject"]},
"read_data": False,
}
)
],
checkpointer=InMemorySaver(),
)
config = {
"configurable": {"thread_id": "evaluation-case-001"},
"recursion_limit": 8,
}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Save the approved summary."}]},
config=config,
version="v2",
)
InMemorySaver 适合原型或在单个进程中运行的测试;进程重启后它无法持久化。对于已部署的工作流,请使用持久化检查点。LangChain 的 HITL 指南说明,暂停和恢复执行需要检查点和线程 ID。来源:Human-in-the-loop。
当运行返回中断时,应向审核者展示请求执行的操作及其参数。使用审核决定恢复同一线程。决定的顺序必须与中断中的操作顺序一致。要拒绝某项操作,应拒绝该操作;respond 用于将人工回答作为工具结果返回,而不是拒绝副作用。
from langgraph.types import Command
# Use the same config, including the same thread ID, to resume.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Outside the approved scope."}]}),
config=config,
version="v2",
)
让评估具备可重复性
将一组精简的测试集纳入版本控制。每个用例都应说明用户请求、预期的工具行为、是否需要审核,以及预期的最终状态。测试时使用无害的夹具或模拟工具;不要让评估用例写入真实文件或修改生产数据。
| 用例 | 设置 | 预期结果 |
|---|---|---|
| 安全读取 | 通过 read_data 请求信息 | 不出现 HITL 中断;返回工具结果 |
| 经审核的写入 | 请求执行允许的写入操作 | 写入执行前出现中断;批准后允许执行 |
| 被拒绝的写入 | 请求写入,然后拒绝该操作 | 不执行写入工具;拒绝反馈返回给代理 |
| 步骤限制边界 | 使用使工作流无法完成的夹具 | 运行在配置的边界处停止,并记录为未完成 |
对于每次运行,记录用例 ID、配置的限制、工具调用、中断决定、完成状态和任何错误。将这些字段与预期值进行比较。不要只根据最终的自然语言响应进行判断:代理可能在采取错误操作后仍生成看似合理的回答。
失败处理:暂停、拒绝或停止
HITL 是受控暂停机制,不是通用的重试机制。审核者可以根据配置的策略批准、编辑、拒绝或响应。拒绝会跳过请求的工具调用,并将拒绝反馈返回给代理。之后代理是完成任务、请求其他操作,还是失败,取决于其后续行为,因此应测试这条路径。
如果图达到递归限制,应将此次运行记录为限制失败,并检查其状态和工具历史。不要自动重放可能已经执行副作用的运行。在可行的情况下让工具具备幂等性,或者在重复操作前要求进行单独检查。所提供的文档介绍了基于检查点的暂停和恢复,但并未说明可以从任意工具或模型失败中自动恢复。
故障排查清单
- 没有出现中断: 检查工具名称是否与
interrupt_on映射匹配,以及其策略是否启用了审核。 - 恢复时找不到已暂停的运行: 确认使用的是同一个检查点和线程 ID。
- 运行提前停止: 检查配置的递归限制和图路径;只有当测试用例能够证明有必要时,才提高限制。
- 看起来被拒绝的操作似乎已经发生: 确认审核前没有调用工具,并确认审核者使用的是
reject,而不是respond。 - 测试结果在不同运行之间不一致: 固定工具夹具和测试输入,并在设置允许的情况下控制或替换模型响应。仅固定输入并不能让模型输出具备确定性。
实用规则
使用递归限制约束图工作量,使用 HITL 把关具有实际影响的工具调用,并通过一组小型且明确的测试集验证成功路径和失败路径。将中断、拒绝和达到限制的运行视为不同结果。这种区分能让代理更易于评估,也能更安全地进行修改。
常见问题
LangGraph 的递归限制会限制工具调用次数吗?
不完全是。它限制的是图的执行步骤,而能够容纳的工具调用次数取决于图结构。应将达到限制视为未完成运行,并测试这一边界。
恢复经过人工审核的工具调用需要什么?
配置检查点,提供线程 ID,并使用相同的线程和持久化上下文恢复。审核者需要为每个被中断的操作提供决定。
HITL 会自动重试失败的工具调用吗?
不会。文档所述的 HITL 工作流会暂停以等待人工决定,然后执行或跳过经过审核的操作。它并未说明会对任意工具或模型失败进行自动重试。
应该如何测试被拒绝的工具调用?
使用无害或模拟的工具,触发中断,拒绝该操作,然后断言工具未被执行,并且运行记录了拒绝反馈。
相关文章
指南
构建支持隐私保护、工具审批与恢复的 LangGraph Agent
介绍一种实用模式:在处理敏感数据的 Agent 中使用 LangGraph 人工审核、检查点、有界运行和凭据安全工具。
指南
构建用于 API 故障诊断的有界 LangGraph Agent
构建一个 LangGraph 故障诊断 Agent,调用只读诊断工具、限制执行范围、明确呈现故障,并在执行高风险操作前暂停。
指南
使用工具调用、人工审批和执行限制构建 LangGraph 客服代理
实用的 LangGraph 客服分流模式:路由请求、调用查询工具、暂停退款以等待人工审批,并限制图执行步数。
指南
LangGraph Agentic RAG:工具调用、来源归属与有界执行
构建一个 LangGraph 文档问答代理,让它决定何时检索、评估上下文、在搜索效果不佳时重试,并返回带来源归属且不会无限执行的答案。