指南OneMux

构建支持隐私保护、工具审批与恢复的 LangGraph Agent

介绍一种实用模式:在处理敏感数据的 Agent 中使用 LangGraph 人工审核、检查点、有界运行和凭据安全工具。

AI

摘要 · 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 无限运行吗?

不能。审批中间件负责审核已配置的工具调用。执行限制、工具超时、输出限制和安全重试机制都需要另行设置。

相关文章