用途:为 Hedera Agent Kit 创建 Policy(策略),即叠加在 BaseTool 生命周期上的阻断式校验规则。策略在某个阶段检查调用并抛出异常以中止执行,错误会回传给 LLM 智能体,可用于阈值、允许/阻止名单、速率限制、营业时间、合规规则等。
主要能力:策略仅对继承 BaseTool 的工具生效;直接实现 Tool 接口的工具会完全绕过策略。内置策略位于 @hashgraph/hedera-agent-kit/policies:RejectToolPolicy(relevantTools: string[]) 无条件阻止列出的工具方法;MaxRecipientsPolicy(maxRecipients, additionalTools?, customStrategies?) 限制转账/空投工具的接收方数量。
使用方式:继承 AbstractPolicy,实现 name、description、relevantTools,并覆写 shouldBlockPreToolExecution、shouldBlockPostParamsNormalization、shouldBlockPostCoreAction、shouldBlockPostSecondaryAction 中的一个或多个(默认返回 false 即放行,返回 true 触发通用阻断错误,抛出异常可自定义消息)。不要覆写 preToolExecutionHook 等 *Hook 方法,否则策略永不阻断。策略作为 AbstractHook 实例放入 Context.hooks 数组,与观察钩子共用同一生命周期,按数组顺序执行,首个返回 true 或抛出的策略生效。
适用场景:按工具方法做黑白名单、基于时间或速率限制、对归一化后的金额/接收方数量做阈值校验、在提交前检查已构建的 Transaction。多数策略放在阶段 1(开销最低)或阶段 3。
限制:策略在生命周期中同步运行,热路径上应避免 I/O;relevantTools 仅作信息用途,需在每个 shouldBlock 方法开头自行按 method 过滤;自定义工具需提供策略函数。参考资料包括 references/policy-interface.md 与 examples/max-amount-policy/。