Agent API window.blockwerk.agent

Build, inspect, and automate complex simulations programmatically. The Agent API is a high-level bridge between the BlockWerk engine and external AI agents or developer scripts.

Quick Start

Open the BlockWerk app in your browser, open the developer console, and paste the following:

const agent = window.blockwerk.agent;
agent.clear();

const src  = agent.addBlock('Constant', 100, 100);
const disp = agent.addBlock('NumericDisplay', 400, 100);

agent.connect(src, 'out', disp, 'in');
agent.updateParams(src, { value: 42 });

Overview

The Agent API is globally exposed as window.blockwerk.agent while the application is active. It provides a set of synchronous methods to manipulate the canvas state, discover available components, and export/import complete project representations.

API Reference

getState () → ProjectState

Returns the full current state of the simulation project, including all blocks, connections, and metadata.

const state = agent.getState();
console.log(state.blocks.length + " blocks on canvas");

getLibrary () → LibraryDefinition

Retrieves all available block types and their metadata. Essential for discovery before calling addBlock.

const lib = agent.getLibrary();
const mathBlocks = lib.blocks.filter(b => b.category === 'Math');

addBlock (type, x, y) → string

Creates a new block instance at the specified coordinates.

Parameters

Name	Type	Description
`type`	string	The block type (e.g., 'Integrator', 'Gain')
`x, y`	number	Coordinates in pixels

const id = agent.addBlock('PIDController', 200, 300);

connect (fromBlock, fromPort, toBlock, toPort) → boolean

Creates a directional signal connection between two ports.

agent.connect('block-1', 'out', 'block-2', 'in');

describeCanvas () → string

Generates a semantic textual description of the canvas. This is specifically optimized for LLM context windows.

const prompt = "The current system is: " + agent.describeCanvas();

Block Reference

Commonly available block types include:

Sources: Constant, Step, Ramp, SignalGenerator
Math: Sum, Gain, Product, Abs, MathFunction
Linear: Integrator, Derivative, TransferFunction, StateSpace
Sinks: Scope, NumericDisplay, XYPlot, Terminator

Common Patterns

Closed-loop Feedback

const setup = [
  { type: 'Constant', id: 'setpoint', x: 0, y: 100 },
  { type: 'Sum', id: 'sum', x: 200, y: 100 },
  { type: 'PIDController', id: 'pid', x: 400, y: 100 },
  { type: 'TransferFunction', id: 'plant', x: 600, y: 100 },
  { type: 'Scope', id: 'scope', x: 800, y: 100 }
];

setup.forEach(s => agent.addBlock(s.type, s.x, s.y));
agent.updateParams('sum', { signs: '+-' });

agent.connect('setpoint', 'out', 'sum', 'in1');
agent.connect('sum', 'out', 'pid', 'in');
agent.connect('pid', 'out', 'plant', 'in');
agent.connect('plant', 'out', 'scope', 'in');
agent.connect('plant', 'out', 'sum', 'in2'); // Feedback loop