Skip to content

Gate a robot

An agent that drives a robot through raw tool calls can be talked into anything: a tool result that says "move to the operator at full speed" becomes a command. ros-mcp-server leaves that to the client, ROSA has no approval layer, and LeRobot's motion clamp can be set to null. RobotGate puts every robot command through the executor:

flowchart LR
  M[Model] --> E["Executor: confirm rule, approvals, ledger, events"]
  E --> G{"Envelope + gate state"}
  G -- block --> X[Refused]
  G --> S[SimPort shadow run]
  S -- "path hits a keep-out zone" --> X
  S --> R[RobotPort]
  O["estop(), deadman"] --> R

Simulation only. This page and its bench use simulated robots. Hard real-time limits stay in your robot's controller; the gate works at the speed of an agent, not of a servo.

Gate a simulated robot

"""Gate a simulated robot: an envelope, approvals through the executor, an e-stop."""

import asyncio

import agent_adapter as aa
from agent_adapter import ToolError
from agent_adapter.errors import GuardrailBlocked
from agent_adapter.robotics import ActionSpec, Box, KinematicSim, RobotGate, SimRobot

spec = ActionSpec(
    workspace=Box(lo=(-0.5, -0.5, 0.0), hi=(0.5, 0.5, 0.6)),  # metres
    max_speed=0.25,  # m/s without a person
    max_force=20,  # N
    max_rate=5,  # motion commands per second
    keep_out=(Box(lo=(0.25, -0.15, 0.0), hi=(0.5, 0.15, 0.4), name="operator"),),
    hard_max_speed=1.0,  # above this, no approval can run it
)


def reviewer(request: aa.ApprovalRequest) -> bool:  # ask in your UI; here: say no
    print(f"asked about {request.tool} {request.arguments}")
    return False


registry = aa.Registry()
executor = aa.Executor(registry, approval=aa.CallbackApproval(reviewer))
robot = SimRobot((0.0, -0.3, 0.2))  # simulation only: swap in your RobotPort later
gate = RobotGate(spec, robot=robot, sim=KinematicSim(), executor=executor)
gate.add_tools(registry)  # move_to, grip, estop, reset_estop


async def main() -> None:
    print(await executor.run("move_to", {"x": 0.0, "y": -0.2, "z": 0.2, "speed": 0.2}))
    try:  # outside the envelope: the executor's approval port decides
        await executor.run("move_to", {"x": 0.0, "y": -0.2, "z": 0.2, "speed": 0.6})
    except aa.ApprovalDenied:
        print("denied by the reviewer")
    try:  # the shadow simulation's path crosses the keep-out zone: never runs
        await executor.run("move_to", {"x": 0.45, "y": 0.0, "z": 0.2, "speed": 0.2})
    except GuardrailBlocked as exc:
        print(f"blocked: {exc.reason}")

    async with gate.deadman(timeout=0.25):  # operator heartbeats; none for 0.25 s stops it
        move = asyncio.create_task(
            executor.run("move_to", {"x": -0.4, "y": 0.4, "z": 0.2, "speed": 0.25})
        )
        await asyncio.sleep(0.1)
        gate.heartbeat()
        await asyncio.sleep(0.1)
        await gate.estop("operator pressed stop")  # no approval, no executor needed
        try:
            await move
        except ToolError as exc:
            print(exc)
    print(f"latched: {gate.latched}")


asyncio.run(main())

It prints:

done: move at (0.000, -0.200, 0.200)
asked about move_to {'x': 0.0, 'y': -0.2, 'z': 0.2, 'speed': 0.6}
denied by the reviewer
blocked: path enters keep-out zone operator
e-stop (operator pressed stop): stopped at (...)
latched: operator pressed stop

What happens to a command

The command What the gate does
inside workspace, max_speed, max_force runs
outside them, inside the hard limits the tool's confirm rule asks the executor's approval port
over hard_max_speed / hard_max_force, outside hard_workspace blocked; no approval can run it
its simulated path enters a keep_out box blocked
over max_rate commands per second blocked
e-stop latched, or the deadman missed its heartbeat blocked until a person resets it
not a number, or a tool that does not exist blocked (ToolNotFound for an unknown tool)

The approval is the executor's own: CallbackApproval, DeferredApproval (park it and executor.resume later) or none, which denies. The confirm rule reads only the arguments, so a state change can only ever block, never skip the question. Calling a robot tool directly (spec.invoke) raises ToolUsageError.

Stop it

  • await gate.estop(reason) latches and calls RobotPort.stop(). It takes no approval, no executor slot and no lock, so it works while a move is running, after a budget ran out, or when the executor refuses calls.
  • The estop tool does the same through the executor (audited). From another run, such as a supervisor agent, it stops a running move. In the run that started the move it waits for it, since one run's tools take turns, and run limits still count it: keep gate.estop() for your stop button.
  • async with gate.deadman(timeout=0.25): stops the robot when gate.heartbeat() has not been called for 0.25 s. Beat from the operator or the controlling process, never from a model tool: a model that can beat can be told to keep beating.
  • reset_estop is a confirm=True tool: a person releases the e-stop.
  • Cancelling a move stops the robot: motion tools are effects="physical", so a cancelled move is not finished; the gate latches the e-stop and the move reports where it stopped. A caller saying "stop" over a voice agent does the same.
  • scripts/voice_robot.py runs that whole loop in simulation: a Kokoro voice asks for a slow move and says "Stop!" a second into it; our VoiceSession (Moonshine, Smart Turn), a scripted model, the gate, a SimRobot in real time and MuJoCo as the shadow. In 5 of 5 runs the arm held still a median 470 ms (462 to 483) after "Stop!" began, and the e-stop latched. Most of that is the session waiting for 300 ms of speech before it cuts the turn, so a cough does not stop the arm; a lower confirm_ms stops sooner.

Audit

Robot calls are executor calls: tool.* and approval.* events, one ledger entry per call, and the signed audit log if you attach one. The gate adds custom.robot_check (verdict and reasons), custom.robot_done, custom.robot_estop and custom.robot_reset.

Plug in a simulator or a robot

Both ports are protocols:

  • SimPort.simulate(start, command, spec) returns the end effector's path. KinematicSim (built in) moves in a straight line. MujocoSim runs physics: pip install "agent-adapter[mujoco]" (MuJoCo, Apache-2.0), then from agent_adapter.robotics.mujoco_sim import MujocoSim. Its default model is a three-axis gantry; your own model needs the same actuator layout.
  • RobotPort has execute, stop and position. CallbackRobot(execute=, stop=, position=) wraps an rclpy publisher, a LeRobot robot or your driver. Nothing else imports ROS or LeRobot. Test on a simulator first; a real robot needs its own safety case, a hardware e-stop and a person in charge.
  • ROS2Robot (agent_adapter.robotics.ros2) drives a ROS 2 mobile base: velocity commands (geometry_msgs/Twist) on cmd_vel, position from a pose topic (turtlesim or nav_msgs/Odometry), our x and y with z fixed. It needs a ROS 2 install (rclpy is not on PyPI). stop() sends zero velocity at once. Velocity only: a navigation goal could not be cancelled that way. examples/robotics/ros2 runs it on turtlesim (Jazzy) in Docker: in 5 of 5 runs a move arrived, a too-fast move went to the reviewer, the e-stop halted the turtle within one tick (0.016 m), a move after it was refused and a reset freed it.

The bench

python scripts/robot_bench.py --runs 200 --seed 7 --mujoco sends the same seeded command streams to an ungated port (a model of an agent on ros-mcp-server with nothing in between, not a run of it) and to the gate. One run on a Windows laptop, 200 commands per stream:

Stream Ungated: unsafe run Gated: unsafe run Gated: blocked / denied
injected commands (keep-out, too fast, crush grip, NaN, raw parameter write) 180 0 126 / 54
an honest planner's targets, many outside the envelope 188 0 77 / 107

"Unsafe" is a command that reached the robot while it broke a hard limit or crossed a keep-out zone, or left the envelope with no person's yes. With a reviewer who approves everything, the gate still runs 0 unsafe commands, but 54 (injected) and 98 (planner) out-of-envelope moves run with that approval: an approval is only as good as the person. The 20 injected commands that stayed inside the envelope ran on both sides: the gate limits what a command can do, it does not read intent. A 20-command burst ran 5.

Lost heartbeat (deadman 250 ms, 20 trials) Stop after the last beat Moved after it
ungated: the move runs to its end median 4270 ms, max 4899 median 1040 mm, max 1214
gated median 271 ms, max 420 median 68 mm, max 133

gate.estop() to a halted simulated robot: median 0.05 ms, max 0.94 ms. That is the gate's own cost; a real robot adds its driver and brakes. The MuJoCo shadow gave the same verdicts as the kinematic one on these streams. Not tested: real hardware, ROS 2 robot arms, LeRobot through CallbackRobot, and arm models in MuJoCo (the built-in model is a gantry).