构建支持隐私保护、工具审批与恢复的 LangGraph Agent
介绍一种实用模式:在处理敏感数据的 Agent 中使用 LangGraph 人工审核、检查点、有界运行和凭据安全工具。
摘要 · TL;DR
使用 LangGraph 的人机协同中间件暂停敏感工具调用,供人工审核或拒绝,并从检查点恢复运行。再配合严格的工具边界、凭据隔离和执行限制,构建更安全的工作流。
核心要点
- 将凭据保存在工具实现内部;只向模型传递其所需的最少参数。
- 对敏感写入或查询要求人工审核,同时允许安全的读取操作继续执行。
- 使用持久化 checkpointer 和稳定的 thread ID 恢复中断的任务。
- 限制图的执行范围,并确保工具具备幂等性,或可独立安全地重试。
- 将检查点状态和中断载荷视为敏感数据。
文章目录 (5)
注重隐私保护的 Agent 不应依赖模型自行判断工具调用是否安全。应将凭据保留在对话之外,限制每个工具可执行的操作,并在执行敏感操作前暂停以供人工审核。LangGraph 的人机协同中间件提供暂停和恢复机制;数据处理、授权和执行限制仍需由你的应用定义。
本指南将构建一个简单模式,让 Agent 能读取客户记录并请求修改数据库。这里的代码仅作示例,未经过测试。部署前,请根据你的环境核对软件包版本和工具签名。
1. 将模型上下文与凭据分开
不要把密码、API 密钥、会话 Cookie 或不受限制的数据库凭据放进提示词或工具参数。应为工具提供范围明确的操作,并让工具在执行时通过应用的机密管理机制获取凭据。模型只应看到作出操作选择所需的数据。
例如,应优先使用 find_customer_record(customer_id) 这类工具,而不是接受任意 SQL 和连接详情的通用工具。应在工具本身验证授权:用户提出请求,并不代表其有权访问所请求的记录。
人工审核是额外的控制措施,不是授权系统。审核人员应获得作出判断所需的信息,但审核界面和日志中不应展示不必要的个人数据或机密信息。
2. 为敏感操作配置审核
提供的 LangChain 人机协同文档介绍了一种中间件,可根据策略检查工具调用。匹配的调用可以中断执行;checkpointer 会保存图状态,以便之后恢复运行。文档列出的处理方式包括批准、修改参数、附带反馈拒绝,以及回复向用户提问的工具。
以下是一个示例配置。请将占位工具替换为能够执行应用访问规则和输入校验的实现。
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
agent = create_agent(
model="YOUR_CONFIGURED_MODEL",
tools=[read_customer_record, update_customer_record],
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"read_customer_record": False,
"update_customer_record": {
"allowed_decisions": ["approve", "edit", "reject"]
},
},
description_prefix="Review requested customer-data change",
),
],
# For production, use a persistent checkpointer appropriate to your stack.
checkpointer=InMemorySaver(),
)
InMemorySaver 适合原型开发,但不适合在进程重启后持久恢复。文档要求人机审核中断必须使用 checkpointer,并列出了 AsyncPostgresSaver 和 MongoDBSaver 等持久化选项。应根据检查点数据选择具备适当访问控制、保留规则和加密措施的存储方案。检查点可能包含消息和工具参数,因此即使排除了凭据,也可能包含敏感用户数据。
如果只需审核特定调用,文档还支持使用 when 谓词实现条件中断(需要 langchain>=1.3.3)。例如,可以暂停对已批准工作区之外的写入,或暂停非只读查询。不要把字符串前缀检查当作完整的 SQL 安全策略;还应在数据库和工具层强制限制安全操作。
3. 暂停、审核并恢复同一次运行
使用稳定的 thread ID,让应用能将待审核事项关联到正确的对话。妥善保护此 ID 和审核界面:仅持有 thread ID 不应就能获得批准操作的权限。
from langgraph.types import Command
config = {"configurable": {"thread_id": "conversation-123"}}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Update this customer's address"}]},
config=config,
version="v2",
)
if result.interrupts:
# Present the requested action to an authenticated reviewer.
# Resume only after recording that reviewer's decision.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Verify the request first."}]}),
config=config,
version="v2",
)
如果多个工具调用同时暂停,决策顺序必须与中断请求中的操作顺序一致。使用 reject 拒绝会产生副作用的操作。文档提醒,respond 会提供一个模拟的工具结果;它适用于回复“询问用户”类型的工具,不能用于拒绝写入操作。
4. 限制执行范围并为恢复做好设计
审核暂停本身并不能阻止模型反复请求调用工具。应为调用设置图递归限制,并将触发限制的错误作为受控停止处理。具体限制取决于工作负载;应根据模型和工具步骤的最大有效序列来设定,并测试达到边界时的行为。
config = {
"configurable": {"thread_id": "conversation-123"},
"recursion_limit": 12,
}
这个示例设置用于限制图的执行步数;它无法保证工具不会运行缓慢、输出不会过大,也不能防止外部副作用被重复触发。应为网络和数据库调用添加超时,限制工具输出,并校验输入。对于可重试操作,应使用幂等性控制,或在应用变更前检查当前状态。如果工具已成功执行,但 Agent 尚未记录结果时运行失败,直接重试可能会导致操作执行两次。
恢复时,只有在确认待处理操作及其授权仍然有效后,才能从同一个已保存检查点的 thread 恢复。如果审核等待期间用户权限或底层记录发生变化,应拒绝操作或重新验证,而不是执行过时的参数。
5. 隐私与故障检查清单
投入生产前,请确认:
- 工具实现会私下获取凭据,且不会在工具结果或错误中返回凭据。
- 每个工具都会验证用户授权,并且只接受范围最窄、确有必要的参数。
- 检查点、中断载荷、日志和审核界面均设有明确的访问与保留控制。
- 审核人员无需查看无关个人数据,也能识别操作对象及其后果。
- 拒绝操作不会执行工具,且重试不会重复产生副作用。
- 运行设有步数限制、工具超时和输出限制,并有明确的中断或失败上报流程。
关键的设计原则是:应将人工审批视为安全工作流中的一个检查点,而不是最小权限、数据最小化或工具层校验的替代品。
常见问题
LangGraph 人机协同中间件会保存暂停时的 Agent 状态吗?
它会使用 LangGraph 持久化机制,在中断期间保存状态。必须配置 checkpointer;生产部署还应选择持久化存储,并设置适当的访问和保留控制。
我应该用 respond 决策来拒绝敏感工具调用吗?
不应该。根据文档,respond 会返回模拟的成功工具结果,适用于回复 ask-user 工具等场景。要拒绝会产生副作用的操作,应使用 reject。
如何确保 LangGraph Agent 中的凭据不被泄露?
将凭据保存在工具的执行环境或机密管理层中。不要把凭据放入提示词、模型可见的工具参数、工具结果、中断消息或日志。
人工审批能防止 Agent 无限运行吗?
不能。审批中间件负责审核已配置的工具调用。执行限制、工具超时、输出限制和安全重试机制都需要另行设置。
相关文章
指南
构建具有限制的 LangGraph 工具调用代理,并加入人工审核
一种实用模式:通过明确的步骤限制、对高风险操作进行人工批准,以及可重复的测试用例,评估 LangGraph 工具调用代理。
指南
使用工具调用、人工审批和执行限制构建 LangGraph 客服代理
实用的 LangGraph 客服分流模式:路由请求、调用查询工具、暂停退款以等待人工审批,并限制图执行步数。
指南
构建用于 API 故障诊断的有界 LangGraph Agent
构建一个 LangGraph 故障诊断 Agent,调用只读诊断工具、限制执行范围、明确呈现故障,并在执行高风险操作前暂停。
指南
构建有界 LangGraph Agent,实现经 Schema 校验的提取
构建一个 LangGraph 工作流:在需要时调用工具,在规定的执行预算内停止,并返回经过 Pydantic schema 校验的结构化数据。