DevAgent Smart Physical Engine

Verification-first commissioning engineering for robotics and industrial automation.

DevAgent turns customer engineering files into a bounded pre-site verification workflow: it discovers what is available, normalizes engineering inputs, maps requirements to deterministic checks, runs only qualified verification paths, records evidence, detects regression, and produces FAT/readiness artifacts.

Safety boundary: DevAgent does not turn simulation, AI output, or a generated report into site qualification, functional-safety certification, or permission for real robot motion. OEM controllers, PLCs, safety PLCs, qualified site processes, live interlocks, and measured physical evidence remain authoritative.

30-second overview

If you are new to DevAgent, remember this flow:

customer engineering files
        ↓
devagent verify ./customer-project
        ↓
normalize source + Twin + requirements
        ↓
deterministic checks / qualified simulation when available
        ↓
measured evidence + PASS / FAIL / NOT_TESTED
        ↓
regression + FAT + pre-site readiness

The normal customer entry point is intentionally simple:

devagent verify ./customer-project

DevAgent is designed to fail closed. Missing information becomes a question, NOT_TESTED, or a blocked capability. It does not invent a PASS just to complete a workflow.

Two product front doors

DevAgent v2.10.0 exposes two product identities on the same deterministic authority/evidence core:

DevAgent Community — Connect AI to your robot.

DevAgent Enterprise — Verify AI and automation before it reaches production.

Community users can inspect the AI-to-robot surface with:

devagent community --help

Enterprise/customer verification continues to start with devagent verify ./customer-project. Neither front door bypasses physical qualification, interlocks, exact identity, or operator approval.

Install in 2–5 minutes

Python 3.11+ is required. A virtual environment is recommended:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install --upgrade devagent-physical-engine==2.10.0

Verify exactly what was installed:

python -c "import devagent_physical_engine as d; print(d.__version__)"
devagent --help

Expected package version:

2.10.0

The base install does not require ROS 2, Gazebo, MoveIt, CUDA, robot hardware, or an AI-provider API key.

First safe result in under 10 minutes

Start with a no-motion runtime inspection:

devagent engine status

Then inspect discovered robot/adaptor authority:

devagent discover

These commands do not command a robot. They show the installed control plane and what is or is not currently qualified. Real execution remains disabled by default.

For machine-readable inspection:

devagent engine status --json
devagent discover --json

Verify a customer project

You do not need to convert a customer project into a special DevAgent repository first. Put the engineering material you already have into one folder:

customer-project/
├── requirements.xlsx
├── PLC/
├── Robot/
├── cell.step
├── FAT_results.xlsx
├── calibration/
├── drawings.pdf
└── other customer engineering files

Run the normal workflow:

devagent verify ./customer-project

Request qualified simulation where the exact execution path exists:

devagent verify ./customer-project --simulate

Open the generated Evidence Viewer after verification:

devagent verify ./customer-project --simulate --open

For CI or automation:

devagent verify ./customer-project --json

Default locations:

Evidence database: ~/.devagent/projects.db
Results:           <customer-project>/devagent-results/

A first project does not need to be complete. Missing evidence remains NOT_TESTED, reduces scope, or produces explicit information requests. Generated devagent-results/ files do not become customer-source authority on the next run.

What gets installed — and what does not

The base Python package currently declares only normal Python runtime dependencies. Physical simulation and robot execution intentionally remain separate from pip install.

Humanoid setup system prerequisites

The DevAgent-managed Unitree G1 setup can manage the qualified user-space runtime, but it does not silently install privileged OS packages. Its setup doctor checks system tools such as:

git
git-lfs
bash
cmake
cc
make
tmux

Preview setup without installing anything:

devagent robot setup unitree_g1_29dof --dry-run

Inspect an existing runtime without changing it:

devagent robot setup unitree_g1_29dof --doctor --json

Safe progression from inspection to execution

Use DevAgent in increasing levels of authority:

1. inspect
   devagent engine status / devagent discover

2. verify customer engineering
   devagent verify ./customer-project

3. request qualified simulation
   devagent verify ./customer-project --simulate

4. review evidence / regression / FAT
   devagent-results/

5. physical execution
   only through separately qualified adapters, measured evidence,
   live interlocks, exact identity, and explicit operator approval

A simulation result never grants physical authority by itself.

Engine in action

Exact-Twin simulation in Gazebo Harmonic
_{Real DevAgent engine run with the bounded UR5e workcell, customer-cell entities, physics, and simulation state visible.}

Robot task execution Gazebo view during the bounded pick-transport-place workflow.

MoveIt motion planning RViz planning-scene view used alongside the qualified ROS 2 / MoveIt execution path.

_{Real engine screenshots — not product renders. ROS 2 Jazzy · Gazebo Harmonic · MoveIt 2 · Pilz · exact-Twin verification.}

Commissioning verification flow

Customer engineering files
        ↓
Immutable project + Twin revision
        ↓
Engineering review
        ↓
Requirements + findings + risks + changes
        ↓
Deterministic criterion mapping
        ↓
Requirement-driven verification plan
        ↓
Verification-scope authority
        ↓
Deterministic checks + qualified execution/evidence
        ↓
Evidence Graph
        ↓
PASS / FAIL / NOT_TESTED
        ↓
Change Impact + Regression
        ↓
FAT Report + Evidence Bundle
        ↓
Immutable pre-site commissioning decision

The bounded readiness decision is one of:

READY_FOR_PRE_SITE_COMMISSIONING
NOT_READY_FOR_PRE_SITE_COMMISSIONING

This means the declared pre-site engineering scope has complete, current evidence according to installed DevAgent authority contracts. It does not mean the real site is commissioned.

Evidence and generated outputs

DevAgent records lineage for requirements, Twin revisions, verification plans, requirement-to-case mappings, findings, evidence, campaigns, regressions, FAT reports, and readiness decisions.

A previous READY decision becomes stale when readiness-relevant state changes. Change impact and regression are therefore first-class rather than optional post-processing.

Typical outputs:

customer-project/
└── devagent-results/
    ├── RUN.log
    ├── SOURCE_MANIFEST.json
    ├── INTAKE_READINESS.json
    ├── SUMMARY.json
    ├── PRE_SITE_READINESS.json
    ├── FAT_REPORT.html
    └── EVIDENCE.html

Industrial robot support

The verification engine retains bounded industrial robot workflows, including the target-proven UR5e path and exact simulation-supported ABB IRB1200, FANUC CRX-10iA, and KUKA KR6 R900-2 profiles within their declared qualification scopes.

Inspect available robot profiles and doctors:

devagent robots
devagent robot doctor abb_irb1200
devagent robot doctor fanuc_crx10ia
devagent robot doctor kuka_kr6_r900_2

Generic family profiles and arbitrary customer workcells do not inherit measured authority from a reference workcell.

Unitree G1 bounded natural-language workflow

The humanoid product path separates natural-language intent from low-level authority:

natural-language task
        ↓
bounded deterministic task graph
        ↓
GEAR-SONIC locomotion / stable hold
        ↓
measured distance + balance gates
        ↓
qualified GR00T policy selection
        ↓
measured manipulation evidence
        ↓
verification / replay

Install or adopt the exact managed runtime only when you need this capability:

devagent robot setup unitree_g1_29dof --managed

Re-check readiness without motion:

devagent robot setup unitree_g1_29dof --doctor --json

Compile a bounded task without motion:

devagent robot execute unitree_g1_29dof \
  --task "Walk to the box, grasp it with both hands, and lift it." \
  --dry-run

A visualization/simulation request can then be made only in an environment with the qualified runtime:

devagent robot execute unitree_g1_29dof \
  --task "Walk to the box, grasp it with both hands, and lift it." \
  --visualize

Supported scene/task contracts remain bounded. Placement into bins, stacking, sorting, or other destination tasks are not silently approximated unless a separately qualified capability implements them.

Training output is a candidate, not motion authority. Qualification binds the exact checkpoint and execution evidence before activation can change the active registry.

Physical simulation prerequisites

pip install does not install ROS 2, Gazebo, MoveIt, OEM drivers, CUDA runtimes, robot firmware, or privileged operating-system packages.

Reference industrial simulation stack:

Ubuntu 24.04
ROS 2 Jazzy
Gazebo Harmonic
gz_ros2_control
MoveIt 2

Target-stack acceptance must run on the intended workstation. Hosted software CI must not pretend that graphical ROS/Gazebo/MoveIt or GPU humanoid execution was physically exercised when it was not.

Optional AI providers

AI is optional and advisory. Install only the provider SDK you need:

python -m pip install "devagent-physical-engine[openai]==2.10.0"
python -m pip install "devagent-physical-engine[anthropic]==2.10.0"
python -m pip install "devagent-physical-engine[gemini]==2.10.0"
python -m pip install "devagent-physical-engine[ai]==2.10.0"

Typical credentials:

export OPENAI_API_KEY="..."
export ANTHROPIC_API_KEY="..."
export GEMINI_API_KEY="..."

Provider-backed interpretation cannot grant physical truth, site qualification, functional-safety certification, or real-execution authority.

Installed CLIs

devagent             customer onboarding, verification, AI/agent workflows, robot setup/execution
devagent-commercial  project/evidence/FAT/regression/readiness control plane
devagent-physical    deterministic core + ROS/qualification tools
devagent-physical-ai optional provider-backed engineering front end

New users should start with devagent. The other entry points expose deeper engineering/control-plane functionality and are not required for the first successful onboarding path.

Architecture — learn this after the first result

DevAgent separates proposal from proof:

AI / natural language / customer intent
        ↓
proposal + interpretation
        ↓
deterministic capability / task / verification contracts
        ↓
exact source + Twin + model + adapter identity
        ↓
qualified simulation / measured execution
        ↓
evidence
        ↓
deterministic verdict
        ↓
authority gate

The important rule is simple:

AI may propose.
Deterministic contracts decide what can be attempted.
Measured evidence decides what can be claimed.
Authority gates decide what may execute.

A generated plan is not physical proof. A replay is not a new execution. An AI answer is not engineering evidence. A simulation result does not grant site qualification.

v2.10.0 / V59 drawing-to-simulation release scope

v2.10.0 — Production/Stable software

v2.10.0 adds a fail-closed Drawing-to-Simulation setup path for bounded industrial workcells. devagent robot setup-from-drawing ... lets an AI provider identify semantic entities and explicit dimension callouts from a drawing while deterministic DevAgent geometry remains the only metric authority. AI-derived or visually scaled dimensions are rejected, and missing authoritative dimensions return drawing_setup_needs_input until a named user-verified value is supplied.

The generated Twin, runtime configuration, and fixed-camera contract pass through the existing Setup Qualification authority before simulation. The new devagent robot setup-camera-verify ... gate performs a no-motion render-alignment verification: it launches the simulation scene, captures the fixed camera, obtains only a semantic image-region hypothesis from the AI provider, reads exact Gazebo geometry, and compares deterministic projection/inverse-projection results against the bounded localization authority. Camera-guided execution remains blocked unless this alignment is verified.

v2.10.0 also corrects the Gazebo camera projection contract so custom fx, fy, cx, and cy live under the SDFormat lens intrinsics block and an explicit horizontal FOV is emitted. A regression check prevents silent fallback to the Gazebo default projection from drifting the rendered image away from deterministic camera geometry.

The existing V58 setup qualification progression (blocked -> geometric -> physical -> reality_calibrated), V52 industrial-arm AI + vision execution authority, V51 Community surface, and V50 verification-first core remain intact. The qualified industrial motion acceptance remains unchanged: deterministic collision/preexecution checks, controller/FK readback, 2 mm TCP position acceptance, 0.5° orientation acceptance, and exact evidence identity remain authoritative. AI has no joint, trajectory, metric, or physical-execution authority.

The production release remains fail-closed on exact target-workstation campaign evidence for declared industrial robot configurations. Software CI, generated plans, single-run simulation, drawing completeness, setup completeness, camera alignment, or AI output alone cannot satisfy physical qualification or grant motion authority.

Physical authority remains conservative by construction: compatibility and simulation do not grant motion; hardware and site evidence cannot be skipped; external admission is required; exact identity drift invalidates qualification; and site-qualified evidence does not bypass the independent runtime approval and live-interlock gates.

Real hardware execution and measured FAT promotion remain disabled until their separate physical campaigns satisfy the required evidence contracts.

Exit codes

Project status

v2.10.0 — Production/Stable software; V59 drawing-to-simulation and camera render-alignment on the V58 setup-qualification, V52 industrial AI + vision, V51 Community, and V50 verification-first core

Production/Stable describes the bounded software workflow and runtime authority contracts. It does not claim arbitrary customer workcells, functional safety, site commissioning, real hardware manipulation, or unqualified robot/model/camera combinations are automatically qualified.

Current hard authority boundaries remain:

site_qualification = false
functional_safety_certification = false
commissioning_completed = false
real_execution_allowed = false

unless separately proven by the appropriate qualified process.

Documentation

• v2.7.0 Release Notes
• Community Production V51
• Flexible Guided Intake
• Commissioning Agent Orchestrator
• Humanoid Pip-First Setup
• Humanoid GR00T Manipulation
• Humanoid Task Orchestrator
• Humanoid High-Quality Demonstrations
• Physical AI Runtime V40
• V40 Production Gate
• Architecture
• Canonical Twin Runtime
• Measured Physical Runtime
• Commercial Project Spine
• Laptop Acceptance

Release history is available from the GitHub Releases page and versioned release-note documents in docs/.

Ownership

DevAgent Smart Physical Engine
Copyright © 2026 Tom Ha
Original creator: Tom Ha
Original project: https://github.com/tomha85/devagent-physical-engine
All rights reserved.

See repository LICENSE, NOTICE, and COPYRIGHT for complete ownership and usage terms.