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 callsRobotPort.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
estoptool 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: keepgate.estop()for your stop button. async with gate.deadman(timeout=0.25):stops the robot whengate.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_estopis aconfirm=Truetool: 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.pyruns that whole loop in simulation: a Kokoro voice asks for a slow move and says "Stop!" a second into it; ourVoiceSession(Moonshine, Smart Turn), a scripted model, the gate, aSimRobotin 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 lowerconfirm_msstops 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.MujocoSimruns physics:pip install "agent-adapter[mujoco]"(MuJoCo, Apache-2.0), thenfrom agent_adapter.robotics.mujoco_sim import MujocoSim. Its default model is a three-axis gantry; your own model needs the same actuator layout.RobotPorthasexecute,stopandposition.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) oncmd_vel, position from a pose topic (turtlesim ornav_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/ros2runs 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).