Guardrails

对于 PII 脱敏这类明确的自动化规则，可以配置完就放手；但对于需要人工决策、语义判断或业务自定义逻辑的护栏，你需要把它当作一个需要持续测试、调整和维护的安全策略，而不仅仅是一次性配置。

心智模型

护栏 / Guardrails 并非单一功能，而是一套可组合的安全中间件体系。它在 Agent 执行的关键节点（输入前、输出后、工具调用时）进行拦截和校验，通过确定性规则（快速、可预测）和基于模型的检测（语义理解、更智能）两种互补方式，确保应用安全合规。其核心是“分层防御”，将多个护栏按执行顺序叠加，形成纵深防护。

二级标题及内容

• 【内置护栏】Built-in guardrails

  • PII 检测：提供内置中间件，用于检测和处理个人身份信息（如邮箱、信用卡号、IP地址）。支持多种处理策略：redact（替换为占位符）、mask（部分遮盖）、hash（哈希化）、block（检测到时报错）。
  • 人在回路：提供内置中间件，在 Agent 执行敏感操作（如发送邮件、删除数据库）前强制暂停并等待人工审批。可与 PII 检测等护栏组合使用。

• 【自定义护栏】Custom guardrails

  • Agent 前护栏：使用 before_agent 钩子，在调用开始时运行，适用于会话级别的身份验证、速率限制或关键词过滤等一次性检查。可通过返回 jump_to: "end" 直接终止本次请求。
  • Agent 后护栏：使用 after_agent 钩子，在 Agent 生成最终答案后运行，适合进行基于模型的输出质量、安全性或合规性评估。可以修改或替换最终的 AIMessage 内容。
  • 组合多个护栏：通过将多个护栏实例添加到 middleware 数组中，按顺序执行，构建分层防护体系（例如：关键词过滤 -> PII 脱敏 -> 人工审批 -> 模型安全检查）。

最佳实践

• 分层防御：组合使用确定性规则（处理已知模式）和基于模型的检测（处理语义模糊的情况），可以获得更全面的防护。
• 精确拦截：before_agent 钩子可用于在问题处理前直接终止请求，节省资源并避免不必要的模型调用。
• 输出兜底：after_agent 钩子是对抗“越狱”或模型生成不安全内容的最后一道防线，可修改或替换不安全的最终回复。