Operating & modes
You drive Embodied through the agent in your integration: build an EmbodiedAgent around your engine, policy, and a Guard, choose a deployment mode, and wire your escalation and feedback hooks. This page is the operator's reference for each control.
Deployment modes
The mode is a graduated safety dial. Move a machine up the dial as you gain confidence, and pin it at the bottom for a certified deployment.
| Mode | Behavior |
|---|---|
SIM | Training in simulation. The agent acts, escalates when unsure, and the supervisor teaches. |
SHADOW | Runs alongside your real control, suggests but never actuates. Use it to watch before you trust. |
ASSIST | Acts only on confident memory and escalates the rest. The everyday supervised mode. |
AUTONOMOUS | Acts on learned memory within the rules, still escalating the unknown. |
FROZEN | Memory locked, no learning. For a validated, certified deployment that must not change. |
agent.set_mode(Mode.SHADOW) # suggest only, never actuate agent.set_mode(Mode.ASSIST) # act on confident memory, escalate the rest agent.set_mode(Mode.FROZEN) # lock memory for a certified deployment
Rules and constraints
Under the memory sit the safety controls in the Guard. Boolean rules veto an action outright. Numeric constraints hold a threshold, for example a minimum clearance or a maximum speed. Each is either an absolute LAW or a soft PREFERENCE. A limit can be strengthened in the field but never loosened, and every veto is logged.
guard = Guard(rules=[
Rule("no advance with a human in path", tier=LAW),
ThresholdConstraint("min_clearance_m", minimum=0.5, tier=LAW),
])
# tighten in the field is allowed; loosen is rejected
guard.strengthen("min_clearance_m", 0.8) # accepted
guard.strengthen("min_clearance_m", 0.3) # rejected, cannot loosen a law
A proposed action that violates a rule, or that the agent is not confident in, is replaced by the safe fallback: stop and ask. The rule holds even if the memory is wrong, so a bad lesson cannot produce an unsafe action.
Capabilities: sensors and actuators
Declare a new sensor or actuator when the machine gains one. It augments what the machine can sense or do without discarding what it learned, the way a new sense enriches memory rather than erasing it. Only the specific decisions the new capability changes are flagged for review; everything else keeps serving. Removing a sometimes-used sensor is non-destructive too, and does not invalidate what was learned.
agent.capabilities.declare("thermometer", kind="sensor") # augments, flags only affected decisions
agent.capabilities.remove("thermometer") # non-destructive, memory kept
agent.capabilities.needs_review() # decisions to re-examine, if any
Escalation and feedback hooks
On a situation it has not learned, the agent does not guess. You choose what an escalation does by wiring a hook: stop and hold, ask a person (voice, a screen, teleop), learn from a sensor outcome, or call your own software (a server model, your LLM, any function) and learn the answer.
agent.on_escalate(ask_operator) # stop and ask a human, learn the answer agent.on_escalate(call_my_server) # or ask your own model, then remember it agent.pin_correction(situation, action) # fix a behavior instantly agent.force_escalate(situation) # override memory if your model misbehaves
Whatever the hook returns, it must reach a genuinely safe state on your hardware. That is your responsibility; see safety below.
Memory packs
The learned memory is the durable store, so moving it is a single portable file. Export after simulation, import on the device.
MemoryPack.export(store_dir, "walker.nfmem")
MemoryPack.import_("walker.nfmem", store_dir)
Bring a robot's field memory back
Export runs on the robot too, so the trip works both ways. Pull the memory a robot built in the wild back to the server, boot a sim instance warm from it, and study or improve it: replay what it learned, read the decision log to see why it acted or escalated on a given situation, keep teaching it against your simulator, or diff it against the pack you originally shipped. Then export a refined pack and send it back out. Nothing retrains from scratch; you move one file.
# on the robot, after time in the field MemoryPack.export(store_dir, "robot7-field.nfmem") # copy it to the server, then MemoryPack.import_("robot7-field.nfmem", store_dir) agent.set_mode(Mode.SIM) # replay, probe, keep teaching
Doing this across a whole fleet, curated and signed rather than by hand, is Embodied Fleet: it collects each robot's new field learnings, lets you approve what should spread, and redistributes only what you bless, with each robot's private learnings staying home.
Observability
Every decision records why it acted: served from memory, which rule vetoed it, or why it escalated, with metrics, so behavior is auditable. Use it to review what a machine learned before you move it up the mode dial.
Safety is a shared responsibility
These are safety tools, not a certified safety system, and they do not guarantee safe operation. You are responsible for training your model and policy correctly, defining and testing the rules for your machine, making sure an escalation reaches a safe state on your hardware, meeting the standards that apply to your deployment, and validating thoroughly before real-world use. Keep independent hardware safeguards such as emergency stops and motion limits, and do not bypass or weaken the rule layer. See the EULA and Terms.