Developer Guide / ReKep Example

ReKep Plugin Development Example

It is recommended to reference ReKep's structure when developing plugins β€” it demonstrates the standard architecture of a complete external plugin.

Why We Recommend Referencing ReKep

🧱

Clear Boundaries

The main repository only concerns itself with the Driver interface; within the plugin, any SDK may be used freely.

πŸ—οΈ

Complete Structure

Manifest, Driver, runtime, deployment scripts, and tests β€” all included.

πŸ”„

Directly Portable

Swap out ReKep's name, action mappings, and runtime implementation, and you've got your new plugin.

Minimal Plugin Structure

There is no need to implement all features at once. It is recommended to first build the basic skeleton, ensure Watchdog can load it properly, then gradually add complex capabilities.

my-phyagentos-plugin/
β”œβ”€β”€ PhyAgentOS_plugin.toml ← Manifest: tells the main repo who you are
β”œβ”€β”€ README.md / README_zh.md
β”œβ”€β”€ pyproject.toml
β”œβ”€β”€ my_plugin/
β”‚ β”œβ”€β”€ __init__.py
β”‚ β”œβ”€β”€ driver.py ← BaseDriver implementation
β”‚ └── profiles/
β”‚ └── my_robot.md ← Capability profile
β”œβ”€β”€ runtime/
β”‚ └── your_runtime_entry.py ← Real robot bridge, heavy logic
└── tests/
└── test_my_driver.py
PathPurpose
PhyAgentOS_plugin.tomlDeclares driver name, entry class, and profile location
my_plugin/driver.pyThe BaseDriver subclass that Watchdog actually loads
my_plugin/profiles/*.mdCopied as EMBODIED.md at runtime
runtime/Third-party SDKs, bridge scripts, long-running processes
tests/Plugin-level smoke tests

How to Write the Manifest

[plugin]
name = "my_robot"
version = "0.1.0"
description = "My robot plugin for PhyAgentOS"

[driver]
name = "my_robot"
module = "my_plugin.driver"
class = "MyRobotDriver"
profile_path = "my_plugin/profiles/my_robot.md"

[python]
sys_paths = ["."]

[[requirements]]
path = "runtime/requirements.txt"
optional = false
The two most critical fields: driver.name determines what name Watchdog uses with --driver to find you; driver.module + driver.class determines which Python class the main repo actually imports.

Driver and Runtime Responsibility Separation

Driver Layer

Responsible for implementing the BaseDriver interface: receiving actions, converting parameters, returning results, and exposing profiles. This layer should be kept as thin as possible.

Runtime Layer

Responsible for preflight checks, dry-runs, real robot execution, and long-running tasks. Heavy dependencies and complex bridging logic should be placed here, not in the Driver layer.

The direct advantage of this separation: when issues arise, you can quickly determine whether the fault lies in "main repo protocol adaptation" or "real robot execution".

Local Development Setup

The recommended local development approach: place the plugin repository alongside the main repository, and install it via local path. 

git clone https://github.com/SYSU-HCP-EAI/PhyAgentOS.git
git clone https://github.com/baiyu858/PhyAgentOS-rekep-real-plugin.git

cd PhyAgentOS
pip install -e .

python scripts/deploy_rekep_real_plugin.py \
  --repo-url ../PhyAgentOS-rekep-real-plugin

This way you can edit plugin code while running the full pipeline through the main repo's Watchdog and Agent for end-to-end verification.

Verification Order: Preflight β†’ Dry-Run β†’ Full Pipeline

1
preflight
β†’
2
dry-run
β†’
3
full pipeline 
# 1. Preflight β€” verify runtime environment is healthy
python runtime/dobot_bridge.py preflight --pretty

# 2. Dry-run β€” don't touch the real robot, verify action parsing
python runtime/dobot_bridge.py execute \
  --instruction "pick up the red block and place it on the tray" \
  --pretty

# 3. Real robot execution
python runtime/dobot_bridge.py execute \
  --instruction "pick up the red block and place it on the tray" \
  --execute_motion \
  --pretty

# 4. Full closed loop with Watchdog + Agent
paos onboard
python hal/hal_watchdog.py --driver rekep_real --workspace ~/.PhyAgentOS/workspace
paos agent

ReKep Supports Two Action Protocols

Plugin Native Actions

real_preflight, real_execute, real_execute_background, real_scene_qa, real_longrun_start

Directly mapped to runtime subcommands β€” ideal for invoking plugin-specific capabilities.

Generic High-Level Actions

move_to, pick_up, put_down, push, point_to, open_gripper, close_gripper

Converted to natural language instructions and routed to the unified execution entry point.

When designing a new plugin, we recommend keeping both layers: one for the main repo's generic protocol, and one for the plugin's internal specialized interface.

ReKep is not the simplest plugin, but its structure most closely resembles production-grade standards. Using it as a template is significantly more efficient than building from scratch.