create_run
Initiate a new protocol run on Opentrons robots by specifying the robot IP, protocol ID, and optional runtime parameters using this tool.
Instructions
Create a new protocol run on the robot
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| protocol_id | Yes | ID of protocol to run | |
| robot_ip | Yes | Robot IP address | |
| run_time_parameters | No | Optional runtime parameter values |
Implementation Reference
- index.js:1718-1764 (handler)Handler function that executes the create_run tool: sends POST /runs to robot API with protocolId, returns run details or error.async createRun(args) { const { robot_ip, protocol_id, run_time_parameters } = args; try { const body = { data: { protocolId: protocol_id } }; if (run_time_parameters) { body.data.runTimeParameterValues = run_time_parameters; } const data = await this.makeApiRequest( 'POST', `http://${robot_ip}:31950/runs`, { 'Content-Type': 'application/json' }, JSON.stringify(body) ); const run = data.data; return { content: [ { type: "text", text: `✅ Run created successfully!\n\n` + `**Run ID:** ${run.id}\n` + `**Status:** ${run.status}\n` + `**Protocol ID:** ${run.protocolId}\n` + `**Created:** ${new Date(run.createdAt).toLocaleString()}\n\n` + `Use the run ID to control execution (play/pause/stop).` } ] }; } catch (error) { return { content: [ { type: "text", text: `❌ Failed to create run: ${error.message}` } ] }; } }
- index.js:139-150 (schema)Input schema for create_run tool defining parameters: robot_ip (required), protocol_id (required), run_time_parameters (optional).name: "create_run", description: "Create a new protocol run on the robot", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" }, protocol_id: { type: "string", description: "ID of protocol to run" }, run_time_parameters: { type: "object", description: "Optional runtime parameter values" } }, required: ["robot_ip", "protocol_id"] } },
- index.js:254-255 (registration)Switch case registration that maps 'create_run' tool calls to the createRun handler method.case "create_run": return this.createRun(args);
- index.js:1476-1504 (helper)Helper method used by createRun to make authenticated HTTP requests to the Opentrons robot API.async makeApiRequest(method, url, headers = {}, body = null) { try { const options = { method, headers: { 'Opentrons-Version': '*', ...headers } }; if (body) { options.body = body; } const response = await fetch(url, options); const data = await response.json(); if (!response.ok) { throw new Error(`API Error ${response.status}: ${data.message || JSON.stringify(data)}`); } return data; } catch (error) { if (error.code === 'ECONNREFUSED') { throw new Error(`Cannot connect to robot. Please check the IP address and ensure the robot is powered on.`); } throw error; } }