企业官网建设流程全解析

LightAgent是一个轻量级 Python 框架，支持工具调用、记忆、护栏、链路追踪与多智能体协作。当你的 Agent 能执行send_payment（付款）、delete_file（删文件）这类高风险操作时，你肯定不想让它"想干嘛就干嘛"。本教程带你用 LightAgent 内置的HumanApprovalHook，3 步把人类审核员放进执行回路：哪些工具需要人工审批、如何批准 / 拒绝 / 修改参数、以及如何在 LightFlow 工作流中做持久化审批节点。无需 Web UI、无需数据库，零额外依赖。

为什么需要"人在回路"：Agent 的审批缺口

Agent 自主性越强，风险面越大。传统做法是"全放行"或"全禁止"，都不够精细：

• 全放行：Agent 可能误调高危工具，造成资金或数据损失；
• 全禁止：功能形同虚设，Agent 失去自主执行能力。

LightAgent v0.9.6 起提供了Human-in-the-loop（人在回路）审核原语：HumanApprovalHook可以只拦截指定的工具或交接（handoff），其余操作照常自动执行。它的核心设计原则是fail-closed（失败即拦截）——只要审核员没给明确通过，动作就会被阻止。

💡 设计要点：LightAgent 不给你塞 Web UI 或队列服务，只给你"可序列化的审批请求 + 存储 + 决策对象"，审核界面由你的应用自己掌控，这正是它"轻量"的体现。

核心实现位于 review.py，官方文档见 human_review.md。

多 Agent 协作场景下（如上图的 LightSwarm），"谁有权批准 A 把任务交给 B 执行"同样是一个审批问题——HumanApprovalHook对on_handoff阶段同样生效。

审批四步走：从"待审"到"放行"

一次典型的延迟审批流程分为 4 步，全部由你掌控节奏：

Step 1：注册 Hook，圈定受保护工具

用tools参数声明哪些工具需要审核（例如付款、删文件），把它挂到 Agent 的hooks上：

from LightAgent import HumanApprovalHook, JsonReviewStore, LightAgent review_store = JsonReviewStore(".lightagent/reviews.json") approval_hook = HumanApprovalHook( store=review_store, tools={"send_payment", "delete_file"}, ) agent = LightAgent( model="gpt-4.1", api_key="your_api_key", base_url="your_base_url", hooks=[approval_hook], )

Step 2：动作被自动拦截

Agent 运行中一旦命中受保护工具，Hook 会生成一条ApprovalRequest（含工具名、参数、run_id、trace_id、源/目标 Agent 等审计元数据）写入JsonReviewStore，并阻塞该动作。你可以随时用review_store.list_pending()拉出待审列表，推给审核员界面。

Step 3：审核员做出决策

ApprovalDecision支持 4 种决策，比"通过/拒绝"强大得多：

Step 4：凭 approval_id 重跑并复用审批

审核完成后，用同一个request_id作为approval_id重跑任务即可：

from LightAgent import ApprovalDecision request = pending[0] review_store.resolve( request.request_id, ApprovalDecision.approve(reviewer_id="finance-reviewer"), ) result = agent.run("Pay invoice 42", approval_id=request.request_id)

注意两个安全细节（源码：review.py）：

1. 审批不可乱用：approval_id只有在"阶段、工具、参数、源/目标 Agent"全部与原始请求匹配时才能复用，否则会被 block 并记录approval_rejected事件——防止"一次审批，反复套娃"。
2. 审批 ID 不外泄：approval_id只存在于 Hook 内部上下文，不会转发给模型 API。

同步审核与参数改写：审核员回调模式

如果你的应用能当场做出审核决定（例如审核逻辑是预算策略而非真人），可以传入reviewer回调，Hook 会同步等待其结果：

from LightAgent import ApprovalDecision, HumanApprovalHook def review(request): if request.tool_name == "send_payment": return ApprovalDecision.edit( {"amount": min(request.arguments["amount"], 100)}, reviewer_id="budget-policy", ) return ApprovalDecision.approve() approval_hook = HumanApprovalHook( reviewer=review, tools={"send_payment"}, timeout=2, )

上面的例子里，审核"员"是一个预算策略：付款金额超过 100 就自动砍到 100 再放行。

两个关键保障：

• fail-closed：reviewer抛异常或超过timeout秒未返回，一律按拒绝处理；
• 决策宽松解析：回调也可以直接返回True（放行）、False（拒绝）或 dict，框架会自动归一化为标准ApprovalDecision（见 review.py）。

LightFlow 工作流审批：跨进程可恢复的审批节点

在 LightFlow 多步骤工作流中，审批能力进一步"持久化"：待审请求 ID 和决策都会写进 checkpoint，进程重启后依然可恢复——这对"下午提交的审批，明天才有人点同意"的场景至关重要。

from LightAgent import ApprovalDecision, JsonLightFlowStore, LightFlow flow = LightFlow(store=JsonLightFlowStore(".lightflow_runs")).step( "publish", agent=publisher, requires_approval=True, ) waiting = flow.run("Publish the report", run_id="report-42") request_id = waiting.steps[0].approval_request_id # 步骤进入 waiting_approval 状态 flow.approve( "report-42", "publish", ApprovalDecision.edit( {"query": "Publish the approved redacted report"}, reviewer_id="editor", ), ) result = flow.resume("report-42") # 从 checkpoint 恢复执行

对应的步骤状态与 trace 事件（见 lightflow.md）：

• waiting_approval：步骤在等人工决策；
• approval_approve/approval_reject/approval_edit/approval_respond：审核决策已应用。

批量审批与事后反馈：把审核做成"流水线"

批量审核：InMemoryReviewStore和JsonReviewStore提供create_batch()/resolve_batch()，适合把多条待执行动作合并到一个审核界面里一次批完（文档：human_review.md）。

Human-on-the-loop 反馈：审批不只是"事前拦截"，还可以"事后打分"。任务跑完后，用HumanFeedback把评分、标签挂到 trace 上，供评测与审计使用：

from LightAgent import HumanFeedback feedback = HumanFeedback( trace_id=result.trace_id, rating=0.9, label="correct", reviewer_id="qa-17", ) review_store.add_feedback(feedback)

这些审批事件同样会进入 trace，接入 Langfuse 等追踪平台后可在时间线上直接看到approval_required、approval_edit等节点：

常见坑与最佳实践

总结：5 分钟回顾

• HumanApprovalHook是 LightAgent 的 fail-closed 审核钩子，可精确圈定受保护的工具与 handoff 阶段；
• 4 种决策（approve / reject / edit / respond）覆盖从"放行"到"人工替代输出"的全部诉求；
• 延迟审批：JsonReviewStore持久化待审请求，approval_id复用审批，且审批严格绑定原始动作；
• 同步审批：reviewer回调 +timeout，异常即拒绝；
• 工作流审批：LightFlow checkpoint 让审批跨越进程重启；
• 事后反馈：HumanFeedback把人类判断沉淀进 trace，反哺评测。

下一步可以继续了解：护栏模板与策略 Hook 见 guardrails.md，确定性工作流的完整用法见 lightflow.md，全部审批 API 参考 human_review.md。