Bedrock护栏别只盯模型：工具调用还有三道检查点

在Strands代理中，Amazon Bedrock Guardrails不能只接在模型输入和回答上。可把独立的ApplyGuardrail调用封装为HookProvider，分别在BeforeInvocationEvent检查代理入口、在BeforeToolCallEvent检查待执行的工具参数、在AfterToolCallEvent检查工具返回值。

模型级护栏围绕模型调用生效，但代理还会执行工具、读取外部数据并与其他系统交互。AWS的Strands实施示例 把检查放在上述三个生命周期事件中：入口内容可在模型处理前拦截，危险参数可在实际操作前取消，违规工具结果可在回到代理前替换。

三道检查分别拦在哪里

第一道是BeforeInvocationEvent。回调从event.messages中提取待评估的用户文本，在模型推理或工具执行开始前送检；触发阻断策略时，可清除原消息并换成固定提示，避免被拦内容继续进入上下文。

第二道是BeforeToolCallEvent。此时模型已经选定工具，并在event.tool_use中给出name与input，但工具尚未执行。回调应先验证参数结构，再把需要语义判断的文本送入护栏；任一检查失败，都通过event.cancel_tool取消调用。转账、发信、删除或修改数据等有副作用的操作，必须在这里完成阻断。

第三道是AfterToolCallEvent。回调读取event.result中的工具返回值，对准备交给代理、用户或下游系统的文本执行OUTPUT检查。若策略要求阻断，应重建不含原文的错误结果，不能把违规内容附在异常消息、调试字段或审计记录中继续传递。

最小代码骨架：一个HookProvider共用一次调用

最小实现只需一个GuardrailHook。构造函数创建bedrock-runtime客户端并保存guardrail_id、guardrail_version及可选的tool_names；register_hooks依次把validate_inbound、validate_tool_input和validate_tool_output注册到三个事件；三个回调共用check_text。

check_text的核心调用为client.apply_guardrail，参数包括guardrailIdentifier、guardrailVersion、source和content。文本块可组织为content=[{"text":{"text":text}}]；入口文本和工具参数使用INPUT，工具返回文本使用OUTPUT。创建Agent时，再通过hooks=[guardrail_hook]注册实例。

ApplyGuardrail独立调用指南 说明该API无需调用基础模型即可评估内容，并允许在应用流程中分别指定INPUT或OUTPUT；响应action可以是NONE或GUARDRAIL_INTERVENED，发生干预时，outputs可能包含掩码后的内容或配置的阻断消息。

因此，check_text不宜只返回一个模糊的布尔值。更稳妥的返回结构应保留action、outputs、检查点和异常类别：阻断策略丢弃原内容，匿名化策略使用处理后的outputs，NONE才允许原内容继续流转。不同工具风险差异较大时，可建立多个Hook实例，并通过tool_names限定各自覆盖范围。

内容护栏不能替代结构校验和业务授权

BeforeToolCallEvent中应先执行确定性校验。JSON Schema或类型模型负责必填字段、数据类型、枚举、长度、数值范围及额外字段；URL、邮箱和业务编号交给严格解析器或正则规则。Guardrails评估内容是否触发已配置策略，但不会替工具证明参数符合调用契约。

业务授权必须留在可信的应用层或工具层。即使“删除订单123”没有触发内容策略，也不代表当前主体拥有该订单或具备删除权限。租户隔离、资源归属、操作范围、审批状态和幂等控制都应依据可信身份与服务端数据判断，不能采信模型在参数中自报的角色或授权结论。

还要注意示例骨架的覆盖边界。调用前回调若只遍历input第一层的字符串值，嵌套对象和数组中的文本不会自动送检；调用后回调若只拼接result.content中带text字段的内容块，也不会检查其他载荷。生产实现应按工具契约递归提取目标文本、限制序列化长度，并为文件、二进制数据和特定结构化字段配置相应扫描规则；未被提取的数据只能标记为未检查，不能视为通过。

把策略干预与API故障分开处理

GUARDRAIL_INTERVENED属于成功响应中的策略动作，不应直接归类为服务故障。处理逻辑还要结合outputs和具体策略：调用前的阻断应取消工具，调用后的阻断应丢弃原结果；敏感信息匿名化则应明确使用处理后的内容，而不是一律返回通用错误。

ApplyGuardrail API参考 把guardrailIdentifier、guardrailVersion、content和source列为必填项，并列出AccessDeniedException、ResourceNotFoundException、ServiceQuotaExceededException、ThrottlingException、ServiceUnavailableException、InternalServerException和ValidationException等错误。权限不足、资源不存在和请求验证失败通常需要立即告警并停止；限流、内部错误或暂时不可用可在预设次数内退避重试。

重试耗尽后的开放或关闭策略应与工具风险绑定。工程上，写入、对外发送数据或访问敏感资源的工具宜失败关闭；低风险只读工具若允许降级，也应明确记录该次检查未完成。日志可保存检查点、工具名、护栏版本、请求关联标识、action和异常类别，但不应原样保存尚未脱敏的参数或返回值。

测试矩阵必须观察工具是否真的执行

测试不能只看代理最终回答，还要确认工具是否实际执行、原始返回值是否继续传递，以及审计记录能否还原阻断位置。至少覆盖以下组合：

• 正常入口与违规入口：确认违规内容在模型处理前被替换或阻断。
• 正常参数、顶层违规字符串、嵌套违规字符串、缺失字段和错误类型：确认工具只在结构与内容检查均通过后执行。
• 正常结果、触发策略的文本结果、嵌套文本和非文本结果：确认违规原文不会继续传递，未覆盖的数据类型不会被误记为通过。
• 无权主体与越权资源：确认内容护栏放行时，业务授权仍能拒绝操作。
• 错误护栏版本、权限不足、限流和服务不可用：确认告警、有限重试及失败开放或关闭策略符合工具风险。
• 按tool_names分流：确认每个Hook只处理目标工具，同时所有工具仍受结构校验与业务授权约束。

生产配置应固定已发布的护栏版本，把DRAFT留给测试，并在策略或版本变化后重跑矩阵。验收标准不是“模型回答经过过滤”，而是入口文本、真实动作参数和外部返回数据都在跨越下一道信任边界前完成对应检查；内容合规、结构合法和主体有权需要分别成立。