Rail：在执行过程中设卡

为什么需要 Rail

大模型会提出要调用什么工具，但它不知道这一刻库存有没有变、这个人有没有权限、算出来的结果是不是已经过期。提示词可以提醒它，却不能保证它照做。

Rail 解决的就是这个问题：在智能体执行过程的固定位置插入你写的代码，由代码而不是模型来决定能不能继续。

openJiuwen 源码里对三者的分工说得很直白：

在哪里插：13 个事件

一个 Rail 就是一个类，覆写哪个方法，就挂在哪个事件上。事件落在三层循环上：

源码AgentCallbackEvent 枚举agent-core/openjiuwen/core/single_agent/rail/base.py:478@fbe6a0d9

两个容易记错的地方：

• BEFORE_TOOL_CALL 是工具触碰外部系统前的最后一个钩子。 要拦写操作，就放这里。
• AFTER_REACT_ITERATION 只在整轮成功时触发，任何中途退出的路径都不会触发，不能拿它兜底。

能做什么：控制动作

挂上钩子之后，Rail 通过上下文对象 ctx 或返回决策来影响执行：

ctx 上还有两个较少用到的请求：request_model_continue（要求模型再迭代一轮）和 request_context_rebuild（重建本次模型请求的上下文窗口）。

源码BaseInterruptRailagent-core/openjiuwen/harness/rails/interrupt/interrupt_base.py:46@fbe6a0d9

一道授权门长什么样

贯穿案例：客户询单，智能体查库存、算出可承诺交期，然后要调用 create_order 写入订单系统。问题是，算交期用的库存快照可能已经过期。这时不能让订单写进去。

继承 BaseInterruptRail，只需要实现一个方法：

import json
from openjiuwen.harness.rails.interrupt.interrupt_base import BaseInterruptRail


class PromiseGateRail(BaseInterruptRail):
    """写订单前检查：引用的交期计算结果是否仍然有效。"""

    def __init__(self, promise_store):
        super().__init__(tool_names=["create_order"])  # 只拦这个工具
        self._store = promise_store

    async def resolve_interrupt(self, ctx, tool_call, user_input, auto_confirm_config=None):
        args = json.loads(ctx.inputs.tool_args)
        if self._store.is_stale(args["promise_id"]):
            # 不执行工具，把这段话当作工具结果还给模型
            return self.reject(tool_result="交期计算结果已过期，库存已变化，请重新计算后再下单。")
        return self.approve()


await agent.register_rail(PromiseGateRail(store))  # 注意 await

要点：

• 判断依据（结果是否过期）来自你的业务系统，是确定的。不要让模型自己判断自己。
• reject 之后工具不会执行，模型收到的是你写的拒绝说明，它可以据此重新取数、重新计算。
• 如果想转人工，把 reject 换成 self.interrupt(request)，智能体会挂起等待答复。

动手：装一道 Rail

下面的模拟器里有三个任务，每个任务都要你选一个钩子和一个动作，然后看执行时间线怎么变。

四个不报错的坑

Rail 的麻烦之处在于：装错了通常不会报错，只是悄悄不生效。

一、register_rail 漏写 await。 它是协程。漏写时 Rail 根本没装上，智能体照常运行。模拟器里有一个开关可以亲自体验。

二、after 钩子在失败时也会触发。 after 事件写在 finally 里：模型调用失败、甚至即将重试时，AFTER_MODEL_CALL 照样触发。所以在 after_model_call 里要先看 ctx.exception，不能假设一定有响应。唯一的例外是工具调用即将重试时会跳过 AFTER_TOOL_CALL。

源码@rail 装饰器agent-core/openjiuwen/core/single_agent/rail/base.py:1065@fbe6a0d9

三、在 DeepAgent 上，事件走两条路。 DeepAgent 外层包着一个内层 ReActAgent，模型调用、工具调用这类事件由内层触发，BEFORE_INVOKE 这类由外层触发。框架用三个集合决定每个事件的回调注册到哪一层。源码文档提醒：新增事件如果没放进任何集合，回调一次都不会跑，只有一条警告日志。

源码_BRIDGE_EVENTS 等三个集合agent-core/openjiuwen/harness/deep_agent.py:166@fbe6a0d9

四、priority 数值越大越先。 默认 50，BaseInterruptRail 是 90。同一个数还决定 init 的先后，所以"我的钩子要排在它后面"和"我初始化时它的工具得已经在"是同一个问题。

小结

• Rail 把约束同步地插进执行过程，位置由 13 个事件决定。
• 拦写操作放 BEFORE_TOOL_CALL；处理失败放 ON_*_EXCEPTION；校验结果放 AFTER_TOOL_CALL。
• 判断依据要来自确定性的来源，Rail 只提供拦截点。
• 装完一定要用测试断言它真的生效了。