Advanced Metal Research
GitHub Contact AMR
View as Markdown Edit on GitHub

Program a cell with an AI agent

On this page
  1. Before you start
  2. 1. Build the server
  3. 2. Register it with your client
  4. 3. Check the cell
  5. 4. Author a weld program from a STEP file
  6. 5. Plan, preview and save
  7. 6. Run it on the simulated cell
  8. When the agent is refused
  9. Related pages

This guide connects an AI agent to a simulated cell through the RosieOS MCP server. The agent diagnoses the cell, authors a weld program from a STEP file, plans it, and runs it in simulation once you agree. It edits the same program the offline programming app shows, with the same rules and refusals, because it runs OLP's own program engine.

Nothing in the first five steps moves a robot. Robot actions are off until you turn them on in step 6, and then only for simulated cells.

Before you start#

  • A simulated cell. The quickstart starts rt-core in simulation, the OLP server on 127.0.0.1:8794 and the UI. Keep the UI open beside the agent: it shows the robot, and its STOP works whatever the agent does.
  • The CAD environments, for STEP import and seam detection. See Program a weld from CAD.
  • The weld planner, with an NVIDIA GPU, for step 5. Steps 3 and 4 work without it. See Run the weld planner.
  • Node 20 or later and an MCP client: Cursor, Claude Code, or any client that starts a stdio server.

1. Build the server#

From the root of your RosieOS checkout:

(cd offline-programming/v1/ui && npm ci)
(cd mcp/v1 && npm ci && npm run build)

The first command installs the packages of OLP's browser app, which the server bundles so that it runs the same engine.

2. Register it with your client#

In Cursor, open the RosieOS checkout. Its .cursor/mcp.json already registers the server as rosieos, with robot actions off. If Cursor lists it as disabled in its MCP settings, enable it there.

For Claude Code:

claude mcp add rosieos -- node "$PWD/mcp/v1/dist/src/index.js"

For any other client, start node <repo>/mcp/v1/dist/src/index.js over stdio. The reference has the JSON shape most clients take.

To read rt-core directly as well, set ROSIE_RT_CONTROL_SOCKET in the server's env to the dev stack's socket, $ROSIE_LOCAL_RT_DIR/control.sock. The OLP tools work without it.

3. Check the cell#

Ask the agent to diagnose the cell, or run the rosie_diagnose_cell prompt from your client's prompt menu:

To the agentText
Diagnose the connected RosieOS cell. Don't move anything.

The agent reads who controls the robot, OLP's machine status, rt-core's status and events, and planner health, and tells you what state the cell is in. Check that the selected cell says SIMULATION. If something is refused or faulted, the agent quotes the code and points to the page that explains it.

4. Author a weld program from a STEP file#

Run the rosie_author_weld_program prompt with the path to a STEP file, or ask in your own words:

To the agentText
Make a new program for /path/to/bracket.step. Put the part on the
positioner table, find the seams, and show me which ones the torch
can reach before you add any welds.

The agent creates the program for the cell's robot, imports the part (centred on the work frame, its seams detected), places it, and searches each seam with the fitted torch. Each seam comes back clear, partial with its clear runs, or blocked. You choose which to weld; the agent adds those welds and shows you the spreadsheet.

You can steer it as you would in the app: change the torch or the angle search, set a weld's work angle along the seam, add a stand or a STEP fixture, add a second part, or add taught moves, dwells and Home rows. Every edit goes through OLP's parameter rules, so an out-of-range value is refused in OLP's words, not clamped.

5. Plan, preview and save#

To the agentText
Plan it. If the planner refuses, tell me which row and why.
Then preview the TCP path and save the program to the cell.

rosie_program_plan sends the program to the weld planner through OLP. A plan carries the active part's welds; other parts and fixtures go along as obstacles. When it passes, rosie_program_preview_path reports the planned tool path per segment without moving anything. rosie_program_save writes to the cell's program store, revision-checked, so it never overwrites someone else's newer copy. The program now opens in the browser and on the pendant.

6. Run it on the simulated cell#

Warning

Energised motion on a real cell. This step allows robot actions on simulated cells only. Allowing them on a real cell (ROSIE_MCP_ROBOT_ACTIONS=cell) is the cell owner's decision. RosieOS has no software E-stop: keep the hardware E-stop within reach and clear the cell first. See the safety model.

Set ROSIE_MCP_ROBOT_ACTIONS to simulation in the server's env and restart the server from your client. Arm, Load, Play, Run program and the bounded jogs appear, and each refuses unless rt-core describes the selected cell as a simulation.

Then run the rosie_run_program_in_simulation prompt, or:

To the agentText
Run the open program on the simulated cell at 10% speed.

The agent confirms the target is a simulation and calls rosie_olp_run_program. The first call moves nothing: it returns the action (for example Move to program start and run) and every joint's move, and the agent shows them to you. Only when you agree does it call again to arm and run. Watch the robot in the OLP UI. Tell the agent to stop at any time, or press STOP in the UI.

While a robot action runs, and for two minutes after it succeeds, the server keeps OLP's heartbeat alive. After that window, OLP's own deadman stops the robot unless the UI or the pendant is keeping the session alive. See the heartbeat window.

When the agent is refused#

The server reports refusals in OLP's or rt-core's own words and does not work around them. The common ones:

RefusalWhat it means
A robot-action tool is missingROSIE_MCP_ROBOT_ACTIONS is off. Only Stop, Disarm, Pause and Finish cycle exist.
… refused by this MCP server: the selected cell … is backend '…', not a simulationThe mode is simulation and the selected cell is a real robot. Nothing was sent.
target_changedAnother client selected a different cell between the agent's read and its action. Read status again.
confirmation_staleA joint moved more than 0.1° after the agent showed you the confirmation. Ask again.
jog_mode_conflictA program is playing or a loop is running, so OLP refuses jogs.
ui_heartbeat_lostNo client heartbeat reached OLP for 5 s, so it stopped the robot.

The agent never offers Home, fault reset or recover-to-zero. Those stay with the operator at the cell. Every other code is in Error codes and the OLP HTTP API.