[FEATURE] GuardrailProvider interface for pre-tool-call authorization

问题场景

在 CrewAI 中构建多 Agent 协作、需要“工具调用前”做授权判断时触发该需求。典型场景包括：禁止生产环境使用 ShellTool、按 Agent 角色限制文件路径、对每次工具调用做速率限制，或接入外部策略引擎做实时风险评分。现有 guardrail 体系（Task.guardrail / Task.guardrails）是在任务完成后校验输出，无法覆盖工具调用前的授权窗口；BeforeToolCallHook 虽然能返回 False 阻断工具执行，但缺少统一的 provider 契约，用户必须自己写原始 hook。

报错原文

[FEATURE] GuardrailProvider interface for pre-tool-call authorization

原因分析

最可能的原因是缺少标准化接口层：CrewAI 已有 BeforeToolCallHook 协议，但没有定义“工具调用前授权提供方”的标准契约，导致用户无法以可插拔方式接入任意策略引擎，只能手写 hook。Issue 提出在 hook 系统与授权逻辑之间增加 GuardrailProvider 协议（包含 GuardrailRequest、GuardrailDecision、evaluate()、health_check()），并注册为 BeforeToolCallHook，且不改动工具执行管线。讨论中进一步暴露了异步授权场景的空白：当策略需要等待外部人工审批时，如何 suspend、如何用 resolve(decision_id, outcome) 解除挂起、超时默认拒绝还是默认放行，这些在提案中尚未完全规范。

环境排查

• 确认 CrewAI 版本及是否存在 crewai.hooks.types 中的 BeforeToolCallHook 协议。
• 确认是否已使用 crewai.hooks.tool_hooks.register_before_tool_call_hook 注册自定义 hook。
• 确认 Python 版本是否支持 Protocol 与 runtime_checkable（from __future__ import annotations 的使用方式）。
• 确认当前 guardrail 是 Task.guardrail / Task.guardrails（输出后校验）还是工具调用前 hook（执行前阻断）。
• Issue 未提供操作系统、Python、CUDA、PyTorch、显卡或依赖版本，这些项无需强行对照。

解决步骤

1. 先判断你的需求是否可以用现有能力覆盖：如果只是按工具名或角色做静态阻断，可直接实现 BeforeToolCallHook 并返回 False 阻断执行。
2. 如果需要可插拔策略引擎，按 Issue 提案自行定义 GuardrailProvider 协议（name、evaluate(request) -> GuardrailDecision、health_check()），再写一个薄适配器把它注册为 BeforeToolCallHook（可优先尝试，属提案做法，非官方已发布接口）。
3. 适配器中注意 fail_closed 语义：提案示例在 provider.evaluate 抛异常时返回 False（默认拒绝）；若改为 fail_closed=False 则返回 None（放行）。
4. 如涉及人工审批或异步授权，不要把 hook 做成忙等；讨论中建议的方向是 suspend + resolve(decision_id, outcome)，并为不可逆操作设置可配置超时且默认拒绝，可逆操作可默认放行并记录审计。
5. 对挂起后有下游依赖等待的场景，Issue 中明确表示尚未解决，需自行设计流程，不要假设框架会自动处理。

验证方法

触发一次被策略拦截的工具调用，确认工具未实际执行且拒绝理由可回传到 Agent；再触发一次被允许的调用，确认执行链路不受 hook 影响。若实现了异步授权，验证超时到期时按配置执行默认拒绝或默认放行，并能通过 resolve 正确解除挂起。

参考来源

crewAIInc/crewAI #4877

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。