Skip to content

guides

Intended Documentation

Physical-AI Quickstart

Five minutes from sign-up to your first verified Authority Token for a physical action — cobot pick, AGV move, drone takeoff, or surgical primitive.

beginner4 min readimplemented

Physical-AI Quickstart#

Five minutes, no robot required. You'll classify a structured agent goal, mint a short-lived Authority Token bound to your robot's identity, and verify the wire format your edge / firmware team will integrate against.

What you'll have at the end#

  1. An Intended tenant + API key (shared with the digital business-process flow)
  2. Your first OIL v2 classification on a structured agent goal
  3. Your first physical Authority Token — RS256-signed, sub-second TTL
  4. The verifier wire format your controls/firmware team can integrate against

Prerequisites#

Python 3.10+ or ROS2 Humble+ or curl. A robot is not required — the example uses a JSON snapshot of work-cell state so you can run the loop on a laptop.

1 — Get an API key#

Sign up at console.intended.so/register. If you already have a tenant from the digital flow, the same API key works here.

bash
export INTENDED_API_KEY=mrt_xxxxxxxxxxxxxxxxxxxx
export INTENDED_API_URL=https://api.intended.so
export INTENDED_ACTOR_IDENTITY=cobot-east-3

ACTOR_IDENTITY should ultimately be the IEEE 802.1AR DevID of your robot. For the demo, any stable string works.

2 — Run the reference cobot#

bash
git clone https://github.com/intended-so/intended.git
cd intended/examples/physical-ai/pick-and-place

pip install "git+https://github.com/intended-so/intended.git@main#subdirectory=packages/intended-python"

python agent.py goals/pick-workpiece.json

Expected output:

GOAL: pick-workpiece workpiece-A4-7 (ros2:action:moveit_msgs/Pick)
  CLASSIFY oil_code=OIL-1502 confidence=0.97 safety_bit=true
  ► EXECUTING pick-workpiece workpiece-A4-7
    token (truncated): eyJhbGciOiJSUzI1NiIs…

Now run the malformed goal — it fails closed without ever contacting the cloud, the safety property your team will want to verify:

bash
python agent.py goals/malformed.json
# ✖ DENIED — falling back to safe-default: stop
#   reason: malformed-goal: 'schema'

Simulate an emergency stop. Edit work_cell_snapshot.json, set safety/emergency_stop.value to true, re-run a valid goal — the cloud denies with clauseId: deny-on-emergency-stop.

3 — Inspect what just happened#

The token is an RS256 JWT verifiable against https://api.intended.so/.well-known/jwks.json. Decode the body to see the physical claims:

json
{
  "iss": "https://api.intended.so",
  "sub": "cobot-east-3",
  "aud": "intended-edge-verifier",
  "intended": {
    "version": 2,
    "oilCode": "OIL-1502",
    "actorIdentity": "cobot-east-3",
    "deadlineMs": 200,
    "expiresAtMs": 1735689600200,
    "safeDefault": "hold-position",
    "safetyBit": true,
    "safetyCitations": ["OIL-2903", "OIL-2904", "OIL-2906"],
    "dagNodeId": "pick-workpiece"
  }
}

Pull the audit entry for the same token:

bash
curl -H "Authorization: Bearer $INTENDED_API_KEY" \
  "$INTENDED_API_URL/v1/physical/audit/<jti-from-token>"

4 — What this maps to in your stack#

Your componentWhat you do
Robotics platform (ROS2)Drop in intended_ros2 ament package — see ROS2 integration. Gives you a ~/classify_and_authorize service.
Industrial PLC (TwinCAT / Studio 5000 / TIA Portal)Mediator pattern in C++ industrial controls.
Real-time motion controller (Rust)Link the intended-verifier crate — see Rust safety-critical firmware for the wire spec + reference verifier code.
ML perception / planning (Python)Python ML pipelines — same SDK as the example above.
Existing safety PLC + busStays exactly where it is. Intended sits above your safety stack, not in place of it. PLC migration patterns shows the layering.
Customer PhysicalStateProviderYou implement this against your safety bus (FSoE / PROFIsafe / Pilz PSS / OPC-UA Safety / ROS2 QoS). We never read your PLC tags directly.
Safety caseExtend the template in Safety-case writing. Our verifier is your G1.2.2.1 evidence; your assembly's safety case is yours to author.

What we DO NOT do#

  • We do not replace your safety PLC. E-stop chain, light curtains, presence scanners stay. We sit above.
  • We are not currently SIL-2 / PLd certified. The verifier is buildable today; third-party assessment is sales-funded when a customer's regulatory posture demands it.
  • We do not write your safety case. We provide the certified primitive + the GSN template; you author the assembly's case.
  • We do not provide platform-specific adapters (ABB, FANUC, KUKA, UR, Boston Dynamics, etc.). Partner / community work against the same SDKs.

Next#

Physical-AI Quickstart | Intended