企业官网建设流程全解析

LightAgent 从 v0.7.5 起内置了轻量级Guardrails 安全护栏层，帮助你在 Agent 运行前拦截危险输入、在执行前确认敏感工具、在返回前自动脱敏输出。本文带你从零理解三道防线的配置方法与内置模板。

为什么需要 LightAgent 安全护栏？

Agent 会调用大模型、执行工具函数、返回最终答案——每一步都可能出问题：

• 用户输入里可能夹带隐私数据（邮箱、API Key、银行卡号）
• 模型决策可能触发高危工具（转账、删文件、写数据库）
• 最终输出里可能泄露内部机密信息

Guardrails 就是在这些关键节点上加的"检查站"。它默认关闭，配置后才生效，不影响agent.run()的原有行为。

Guardrails 的三道防线

LightAgent 把安全检查拆成三个阶段，每个阶段都可以挂自定义函数或内置模板：

输入护栏：在模型看到之前就拦住

输入护栏在模型请求发出之前运行，能阻止这次运行或改写用户输入：

from LightAgent import LightAgent, GuardrailDecision def block_secrets(query, context): if "api_key" in query.lower(): return GuardrailDecision(False, reason="请勿将密钥发送给模型") return True agent = LightAgent( model="gpt-4.1", api_key="your_api_key", base_url="your_base_url", input_guardrails=[block_secrets], ) response = agent.run("hello")

💡 输入被拦截时，agent.run()返回以[LA-GUARDRAIL]开头的错误信息，不会发起任何模型调用。

工具护栏：敏感操作先确认再执行

工具护栏在参数解析之后、函数执行之前触发，适合转账、删文件等高危场景：

def block_large_transfers(tool_call, context): if tool_call["tool_name"] == "transfer_money": amount = tool_call["arguments"].get("amount", 0) if amount > 1000: return "超过 1000 元的转账需要审批" return True

输出护栏：最终答案的最后一道脱敏

输出护栏对非流式响应在返回前检查，可改写或阻止输出：

def redact_internal_notes(output, context): return GuardrailDecision( True, value=output.replace("INTERNAL_ONLY", "[redacted]") )

内置模板：四行代码搞定生产级防护

LightAgent 内置了四个常用护栏模板，直接导入即可组合使用：

from LightAgent import ( LightAgent, high_risk_parameter_guardrail, output_redaction_guardrail, privacy_input_guardrail, sensitive_tool_confirmation_guardrail, ) agent = LightAgent( model="gpt-4.1", api_key="your_api_key", base_url="your_base_url", input_guardrails=[privacy_input_guardrail()], tool_guardrails=[ sensitive_tool_confirmation_guardrail(["transfer_money", "delete_file"]), high_risk_parameter_guardrail({ "amount": lambda value: float(value or 0) <= 1000, }), ], output_guardrails=[output_redaction_guardrail()], )

所有模板均支持传入自定义正则patterns和拦截reason，可以叠加使用。

护栏返回值速查

每个护栏函数接收(value, context)两个参数，返回以下任意形式：

被拦截的操作统一返回[LA-GUARDRAIL]错误字符串，方便上层逻辑统一捕获处理。

用 trace 追踪每一次拦截

开启trace=True后，每次护栏拦截都会记录guardrail_block事件，便于审计与调试：

result = agent.run("my api_key is abc", result_format="object", trace=True) # result.trace 中包含 {"type": "guardrail_block", "stage": "input", ...}

如果项目接入了 Langfuse 等追踪平台，可以直观看到每次模型调用的完整输入输出，以及护栏触发的拦截记录，排查问题一目了然。

相关文档与源码

• 官方 Guardrails 文档：docs/guardrails.md
• 护栏实现源码：LightAgent/guardrails.py
• 核心运行时集成：LightAgent/core.py
• 单元测试示例：tests/test_guardrails.py

📌 Guardrails 是完全可选的配置项。不设置时 Agent 行为与 v0.7.5 之前完全一致，你可以按业务需求渐进启用，从输入拦截开始，逐步加上工具确认和输出脱敏。