治理约 13 分钟

护栏、意图与 react-rails

Java 侧在不改 agent-core-java 的前提下补的扩展：工具护栏三段链、意图匹配路由、ReAct 增强 Rail。

依据 agent-solution 0.1.3 · main@bf702bc9（2026-11-03）核实

这是什么

agent-core-ext-java 基于 agent-core-java 的公共扩展点，补了一批可复用能力，不改 agent-core-java 源码。本关挑三块讲：工具护栏、意图套件、react-rails。

它们本质上都是 agent-core 区讲过的 Rail：挂在智能体生命周期的钩子上，在调模型、调工具前后插入检查和控制。

智能体要调"写入订单系统"这类工具时，护栏决定放行、询问还是拒绝。ToolGuardrail.install 一次装好三个 Rail：

顺序	Rail	职责
1	`AllowedToolsGateRail`	白名单闸门：不在名单里的工具直接拒绝，不进入策略评估
2	`GuardrailPermissionRail`	权限引擎：按规则给出 allow / ask / deny；ask 抛出中断，等用户确认
3	`GuardrailDecisionObserverRail`	记录 allow / deny 决策，交给审计监听器

几个值得学的设计取舍：

fail-closed 安装：配置没声明启用、宿主又往智能体配置里塞了另一份权限 Rail，都直接抛错。源码注释的理由是：看起来装了但没在拦，比拒绝启动更糟。
重复安装是空操作：中断续跑会再次进入安装钩子，所以第二次安装静默返回，不要求每个宿主自己记"装过没有"。
白名单两种失败处理不同：工具不在名单里 → 拒；名单本身读取失败 → 记警告、放行给权限引擎。因为后面还有引擎兜底，读配置失败就全拒只会造成整体停摆。

三档决策 allow / ask / deny，严格程度依次升高。配置值不合法时直接报错，不会悄悄变成空值——注释里说，一个悄悄失效的决策等于一个悄悄不再守护的护栏。

agent-core-ext-intent-suite 面向 DeepAgent，把用户的话匹配到 Agent Card 的技能或自定义意图，再执行绑定的结果动作（比如委托给另一个智能体）。匹配器可以替换，生产上可以换成基于重排序模型的匹配器，匹配阈值可配置。

远端 Agent Card 的注册、A2A 委托执行和 Spring 配置在 agent-runtime-ext-java 里，意图套件本身是纯类库。

ReAct 循环容易出现"自以为完成""原地打转""出错就乱试"。react-rails 补了几类 Rail：

这些按需组合，不要求一次全开。

链接指向固定提交，仓库后续更新不影响这里的行号。

通关条件