agentworkshop

AgentWorkShop

Where AI agent teams meet the production line.

简体中文 · Documentation · Releases · Changelog · Plugin API · SDK

v0.7.70 · 14 engines · 6 field protocols (5 built-in + serial plugin) + MES REST integration (mirror & live) · data-analysis ledger with line-scoped permissions · per-call tool parameter/binding preflight · 86 host tools · 119 runtime settings · bilingual docs (简体中文 / English)

A configuration-driven platform where AI agent teams and an industrial digital twin share one runtime — agents query real telemetry, issue supervisory setpoints through human-approved write control, and every event streams live to a 3D twin.

[!IMPORTANT] Positioning: supervisory layer. AgentWorkShop is a supervisory (SCADA-adjacent) layer for production-line management, digital twins, DAQ and agent orchestration, operating at second-level soft real-time. It is not a hard real-time controller: any time-critical loop (< 10 ms, interlocks, safety, servo) must live inside the PLC. Setpoints written here are advisory — plant-side logic may veto.

FIGURE INDEX

FIG.01 closed loop · FIG.02 DAQ console · FIG.03 line operations · FIG.04 digital twin · FIG.05 dashboard · FIG.06 responsive

JUMP TO

What is this? · Highlights Interface · Architecture Quick start · Configuration & CLI Industrial stack · Usage Verification · Project layout Tech stack · Development Roadmap · License

AT A GLANCE

Supervisory layer, second-level soft real-time 14 engines · 4 entry points 6 field protocols (5 built-in + serial plugin, read + write) 7-state task machine · root queue + lease fencing Group chat jobs · scheduled tasks · HITL FTS5 + vector memory · hot-reloadable plugins SDK · CLI · TUI · external MCP · ~1100+ acceptance assertions

Documentation

Docs are bilingual — the VitePress site ships a language switcher (简体中文 / English) across every section. Deep-dive pages ship in this repo too, and the CLI copies them into the published tarball:

What is this?

AgentWorkShop started as a multi-agent software workshop — channels of coding agents with a lead-agent scheduler, a 7-state task machine, persistent memory, and four interoperable entry points (WebSocket / MCP / A2A / REST).

It grew an industrial half: a full data-acquisition and write-control stack (Modbus TCP / OPC UA), production lines with recipes and batch runs, a 3D digital-twin town, an auto-modeling lab (dataset → training job → leaderboard → gated promotion) — and the bridge that makes it unique: agents can be granted bound, permission-scoped access to real industrial nodes, query their live telemetry with physical semantics attached, and drive write operations through an interlock → human-in-the-loop → readback pipeline.

It is also extensible by design: a self-contained plugin can enhance the server (hooks, routes, agent tools, DAQ drivers, config groups) and the browser (panels, i18n) at the same time, and the same surfaces are available to ordinary programs through the SDK — see docs/plugins.md and docs/sdk.md.

The result: submit a goal like "analyze the melt temperature trend and optimize the setpoint" — and an agent team reads real sensor history, computes statistics, proposes a new setpoint, waits for your approval in the HITL panel, writes it to the PLC, verifies the readback, and reports the numbers back. End to end, verified by automated E2E.

FIG.01 — The closed loop

Goal → read → compute → approve → write → readback → report. Recorded against a running instance: real DAQ history, real write control, real HITL approval.

[!NOTE] Every figure in this README is a recording or screenshot of a running instance — not a mockup. The numbers on screen come from seeded industrial data flowing through the same code paths the product ships.

🎬 Live demo (4 min 11 s, English voice-over & captions)

Click the cover to watch the full demo. Real PLC simulator, real serial-port enumeration, real agent-team execution — no cuts, no fakes.Scenes: dashboard → live DAQ → governed write & read-back → serial protocol plugin → agent team execution → closed-loop trend → 3D digital twin.

Highlights

Agent team runtime

Industrial stack

Governance, configuration & extension

Digital twin

The interface

Every panel below is the real UI, at 1440×900, recorded from a running instance.

FIG.02 — DAQ console

Acquisition, end to end. Node inventory and health under a live gauge band, trends that fill as samples land, an alarm strip that only holds what is actually unacknowledged, and a tailing event stream.

FIG.03 — Line operations

Lines, products, recipes, batches. Starting a line gates acquisition through its recipe window and tags every sample with product/recipe/run; control nodes expose SET vs ACT through the same calibration path they write with.

FIG.04 — Digital twin

The twin is the same event bus, rendered. Equipment, channel territories, alarms and live values — an adaptive quality ladder (DPR / shadow / bloom, wall-clock FPS budget) keeps it honest on modest hardware.

FIG.05 — Dashboard

One screen for the whole workshop. Channels, agents, tasks, DAQ throughput and alarms — read from the same state the API serves, not a separate metrics store.

FIG.06 — Responsive

Desktop → tablet → phone. The instrument rail collapses to an icon rail, then to an off-canvas drawer; page headers stack, dense tables become scrollable ledgers with a pinned identity column.

Architecture

flowchart TB
    subgraph FE["Frontend — Nuxt 4 / Vue 3"]
        UI["Workshop UI · 3D Twin · Dashboards"]
        WS["AEP client — seq resume"]
    end
    subgraph SRV["Server — Nitro / h3"]
        REST["REST /api/workshop/**"]
        HUB["WS Hub — AEP v1"]
        A2A["A2A JSON-RPC"]
        MCP["MCP Server"]
        subgraph RT["Runtime"]
            MGR["AgentChannelManager"]
            SCH["SchedulerLoop — lead supervision"]
            TE["TaskEngine — 7-state machine"]
            AR["AgentRuntime × N"]
            MEM["AgentMemory — FTS5 + vector"]
            BUS["Event bus (ManagerBus) — per-channel seq + ring"]
        end
        subgraph IND["Industrial"]
            DAQ["DAQ gateway — per-node edge runtimes"]
            DCW["DCW gateway — write control"]
            BR["Bus — inproc / MQTT"]
            TSDB["TSDB — SQLite / Timescale"]
        end
        subgraph HB["Harness adapters — 14 engines"]
            MOCK["mock · claude — in-process"]
            OMP["omp — RPC subprocess"]
            CDX["codex — app-server"]
            DSH["dsh · qwen · hermes — ACP"]
            OC["opencode — serve"]
            FAM["gemini · copilot · cursor · crush · goose · pi — headless CLI"]
        end
        DB[("SQLite — channels · agents · tasks
messages · memories (FTS5) · events")]
    end
    UI <--> WS
    WS --> BUS
    REST & A2A & MCP --> MGR
    MGR --> SCH & TE & AR
    AR --> MEM
    AR --> MOCK & OMP & CDX & DSH & OC & FAM
    MGR & TE & MEM & BUS --> DB
    DAQ <--> BR --> TSDB
    DCW --> BR
    DAQ & DCW --> BUS

The agent × machine bridge (the part worth reading the source for):

agent ──binds to──▶ node (daq: auto / dcw: manual)
  │                    │
  │  my_industrial_nodes  ◀── semantic card: meaning · unit · safe range · recipe window
  │  daq_query             ◀── TSDB history, stats + physical semantics
  │  dcw_control           ──▶ interlock (safe range ∩ recipe window)
  │                           ──▶ HITL approval (manual mode, 180 s timeout)
  │                           ──▶ PLC write → readback check → ACK + write history
  ◀── result text with numbers the agent can cite

Quick start

Prerequisites

node -v   # ≥ 23.4.0  (needs built-in node:sqlite)

Real-agent harnesses require their CLI on PATH — omp, codex, dsh, opencode, gemini, qwen, copilot, cursor, crush, goose, pi or hermes (any subset; each channel can mix harnesses). mock and claude (SDK) run in-process and need no PATH CLI. The dashboard "execution engines" panel shows per-engine readiness with a green/grey dot; entries for uninstalled engines link to their official install pages. Optional DAQ infrastructure (MQTT broker + TimescaleDB) auto-starts via Docker when reachable (docker compose up -d).

Option A — install from npm (recommended)

npm install -g agentworkshop     # → `aw` / `agentworkshop` on PATH
aw start                         # → http://localhost:3001

The published tarball ships a prebuilt production bundle (.output/), so an npm install boots straight away — no build step, no build tools. On first launch everything initializes into the config root ~/.AgentWorkShop: the default config.yml, a generated .env holding a random session secret, runtime-settings.json, a docker-compose seed, prompts/, commands/, plugins/ (seeded from the SDK examples, disabled by default) and an empty data/ directory. All runtime data (SQLite, JSON repos, backups, logs) lives there too — config and data stay with the install, not the working directory.

Prefer a one-off run without installing globally?

npx agentworkshop start          # no global npm install required

npx still creates ~/.AgentWorkShop — running without a global install is not the same as leaving no trace on disk.

Option B — from source

git clone https://github.com/kingdol666/AgentWorkShop.git && cd AgentWorkShop
pnpm install
pnpm dev          # → http://localhost:3000  (port from config.yml)

Production from source:

pnpm build        # nuxt build → .output/
pnpm start        # port from config.yml → server.prod.port

In a source checkout the config root is the project's .AgentWorkShop/ folder (runtime overrides, data, project-level commands), while config.yml / .env stay at the checkout root, version-controlled as the factory defaults.

Updating

aw update                              # check + self-update the global install
aw update --check                      # only report; nothing is installed
npm install -g agentworkshop@latest    # manual equivalent

Releases follow semver. aw start verifies the config root on every launch and migrates the legacy pre-home data/ layout into it (newest file wins), so data survives upgrades. SQLite schema migrations run server-side at boot. Current version: v0.7.70 — see Releases.

Your first agent × line session (~2 minutes)

1. Sign in — register in the sidebar (or POST /api/users/register).
2. Build a line — Line Operations → create a line, add DAQ nodes (e.g. daq-temp-tc) and control nodes (e.g. dcw-temp-sp), create a product + recipe, hit Start. Live values start flowing.
3. Create a team — Agent Workshop → pick a lead + workers, deploy into a channel.
4. Bind nodes — open the agent's detail panel → bind the DAQ node (auto) and the control node (manual = needs your approval).
5. Submit the goal — "Analyze the last 5 minutes of melt temperature; if deviation from 182 °C exceeds 1 °C, correct the setpoint (wait for my approval)."
6. Approve — the agent reads real history, computes the mean, requests the write → approve in the HITL panel → watch the setpoint change and the goal close with a numeric report.

Configuration & CLI — config-driven by design

One runtime, one source of truth. config.yml declares defaults; runtime-settings.json inside the config root carries runtime overrides; environment variables and CLI flags sit on top. Every editable key is described once in shared/config/schema.json (type, range, enum, live-vs-restart) and surfaced through the same descriptors in both the UI and the CLI.

config.yml (defaults)  <  .AgentWorkShop/runtime-settings.json (runtime)  <  env vars / CLI flags

The config root is ~/.AgentWorkShop for a global install (npm i -g) — wherever you run aw from — and <repo>/.AgentWorkShop in a source checkout (with config.yml / .env staying at the checkout root as version-controlled factory defaults). AW_HOME redirects it; AW_MODE=home forces the global shape.

Live settings, persisted, hot-reloaded

• The Settings → Runtime config tab renders every editable key from the descriptors — change server ports, theme, API timeouts, locale or the approval gate, hit save.
• live keys apply instantly (theme, title, timeouts, approval gate, DAQ sampling cadences, TSDB query buckets…) over a server-sent event stream — no reload, no restart.
• restart keys (ports, hosts) persist to disk and take effect on the next launch of the matching mode (aw dev / aw start).
• One channel for every writer: the UI, the CLI and the server's file watcher all converge on the same settings file, so a change made anywhere shows up everywhere.

Example — retune the acquisition and query cadences live:

aw config set daq.sampling.defaultIntervalMs 2000   # new nodes sample every 2 s
aw config set daq.sampling.minIntervalMs 500        # per-node floor (create/patch clamp)
aw config set daq.query.defaultBucketMs 3000        # TSDB reads default to a 3 s bucket
aw config set daq.query.minBucketMs 500             # query floor (samples/line query/agent tool)

Agent tool descriptions are re-rendered with the current values on every injection, so an LLM always sees the floor and default that will actually apply to its daq_query calls.

The aw CLI

Global flags: --help/-h · --version/-v · --json (machine-readable) · --root <dir> · --debug.

Exit codes: 0 success · 1 runtime error · 2 usage error. With --json, failures come back as an envelope carrying { ok: false, error: 'unknown-command' \| 'no-project' \| 'usage' \| 'internal' \| … }, so automation can branch without parsing stderr.

Command registration

Commands are plain modules exporting { meta, run }. Drop one into a scanned directory and it's live on the next invocation — no registry bookkeeping, convention over configuration:

aw register <file|url|npm:pkg> copies a command into the right scope (--global for user scope); aw help lists everything that's registered.

// ~/.AgentWorkShop/commands/hello.mjs
export const meta = { name: 'hello', group: 'Custom', summary: 'Say hi', usage: 'aw hello [--name <n>]' }
export async function run(argv, ctx) {
  console.log(`Hi ${argv.flags.name ?? 'AW'} — mode: ${ctx.mode}`)
}

The industrial stack in detail

Data acquisition (DAQ)

• Six protocol drivers: Modbus TCP, Modbus RTU-over-TCP (serial gateway), OPC UA, MQTT, HTTP/REST, plus the serial-bridge built-in plugin (direct RS-232/485: Modbus RTU framing + ASCII line protocol, write side with same-address readback verification, serial enumeration/probe API and a frontend panel) — connection pools, classified error messages, per-driver connection tests; the driver registry accepts plugin-registered protocols of any kind (with self-describing metadata, the frontend forms render with zero changes).
• Per-node edge runtimes: independent sampling cadence, publish cadence, in-flight mutex per node — one slow driver never blocks its neighbors. Sampling and query defaults/floors are driven by the live daq.sampling.* / daq.query.* settings.
• Pipeline: driver → queue (in-process or MQTT, offline buffer on disconnect) → consumer with out-of-order defense → three-way fan-out: WS live push (gated), TSDB batch write, device-twin writeback.
• Robustness: TSDB single-in-flight writes with bounded retries, buffer backpressure with drop counters, real loss metrics exposed on daq.controller frames.
• Alarms: recipe-scoped monitoring windows with 2% hysteresis + 3-tick debounce; alarm/offline transitions are instant (safety first).
• Querying is batch-scoped by default: daq_query resolves the node's active run and filters by that batch's run_id + recipe_id, so an agent reading evidence always sees the recipe currently running — never a mix of the previous batch. The effective scope (run=<id> 配方「name」(recipe_id)) is printed in the result header and restated per node at the end, and the same ids can be fed straight back into daq_query or aml_dataset_build; pass scope: 'all' (or an explicit recipe_id / run_id / product_id) for cross-recipe comparison and history review. Lines that are not running stay unfiltered, so historical data remains queryable.

Write control (DCW)

• Engineering-unit writes: linear calibration (scale/offset) PLC↔physical, readback verification with deadband tolerance, ACK states and write history.
• Interlock: with a line running, the active recipe's parameter window replaces the node's global safe range for that node.
• HITL: manual-mode bindings suspend the write for user approval (deduped per agent+node; re-validation at approval time — permission is re-checked when you click approve).

Recipe & batch

Line → Product → Recipe → Run. Starting a run applies recipe params node-by-node (each write verified), gates acquisition per line, and tags every sample with line/product/recipe/run — per-product data isolation with five-dimension queries (line × product × recipe × time × node).

AML — auto-modeling lab

The modeling half of the loop: /aml builds datasets out of tagged telemetry, submits training jobs to a uv-managed Python runtime, ranks runs on a leaderboard, and promotes a model only when it clears the configured gates (NRMSE, rollout NRMSE, validation/test gap, minimum rows and runs). Promoted models are referenced by id, so an MPC or shadow-twin controller can consume a versioned artifact instead of a vague "latest".

• Agents do the same work through 14 tools (aml_dataset_build, aml_job_submit, aml_job_status, aml_leaderboard, aml_model_promote, aml_model_find, aml_training_plan_*, …) — submit a goal and let the team train and report.
• The Python runtime bootstraps itself with uv into an ./aml asset root inside the config root; dataset/artifact/metadata paths, disk quota, job timeout, concurrency and retention are all settings (16 in the aml group), not constants.
• Governance defaults are conservative: cross-recipe datasets are refused unless explicitly allowed, and every job is attributed.
• Hybrid twin × MPC core: AML also owns the hybrid twin plane — SceneContract / PhysicsModelManifest / TwinSnapshot / ObjectiveProfile / VirtualTrial / RecommendationCertificate on top of a grey-box physics core with a bounded PyTorch residual, UQ/OOD screening and all-trajectory hard-constraint gates. Channels opt in through the hybrid_twin profile, which injects twelve profile agent tools (twin_provider_catalog, twin_scene_discover/compile/freeze, twin_physics_spec_draft/validate/compile, twin_scene_read, twin_snapshot_create, twin_trial_run, mpc_optimize, twin_gate_evaluate) plus the general twin_calibration_request; a trial is virtual by design (candidateExecuted=false) and a recommendation is only certified when gates and benefit pass. Server-side strategies are safe_small_step (insufficient data) and precise_search (model cleared gates). Plan + acceptance record: docs/aml-hybrid-twin-mpc-integration-plan.md, docs/aml-hybrid-twin-implementation-acceptance.md.
• Any-scene modeling loop: the loop is not tied to a bundled scene. Bind nodes → twin_scene_discover infers control/state/disturbance/target/guard semantics with evidence → twin_scene_compile drafts a SceneContract → you confirm → twin_scene_freeze freezes it (immutable versions) → twin_physics_spec_draft proposes a skeleton PhysicsSpec (one first-order relaxation equation per state, τ/gain as calibratable prior-boxed parameters) that you refine → validate/compile (whitelisted AST, no arbitrary code) → aml_job_submit { job_kind: 'hybrid_residual' } runs without any code: the built-in reference trainer calibrates physics parameters (stage A), fits a 3-member bounded residual ensemble (stage B) and reports conformal q90 coverage (stage D) — the calibrated spec is written back and shared by evaluation, prediction and trials.
• Model-backed twin & continuous calibration: twin_trial_run / mpc_optimize accept a model_id — the rollout is then driven by the trained hybrid model (calibrated physics + residual-ensemble ONNX, ModelBackedHybridProvider) with UQ coverage and member disagreement coming from training artifacts, and a dataset whose line/product/recipe doesn't match the scene is rejected (TWIN_MODEL_SCENE_MISMATCH). Calibration requests are consumed by a 60 s worker that re-submits hybrid_residual retraining candidates automatically; promotion still goes through HITL + Twin Gate (AML_TWIN_WORKER_DISABLED=1 turns the worker off).
• Two-mode optimization loop: aw ships two channel templates — chtpl-aml-training-default (modeling face: 22 tools, no plant writes, no MPC) and chtpl-aml-optimization-default (acting face: snapshot/trial/gate/MPC/Bayesian search plus optimization_explore, the governed micro-write that pairs every setpoint with its response read-back in an optimization_explorations ledger). The faces are mutually exclusive per channel; optimization channels instantiate either in exploration mode (governed small steps, no model required) or aml mode (boundModelId required — a gate-cleared model must be bound before the acting face unlocks).
• Twin provider plugin SDK (hot-loaded): an industrial scene's physics core / scene packs / objectives / solvers register through ctx.twin into the Twin Provider Registry (registerPhysicsProvider / registerScenePack / registerObjectiveProfile / registerTrainingAdapter / registerSolverAdapter, plus listProviders / getProviderHealth / resolveProvider / validateProvider / retireProvider / isRegistryAvailable). Twin tools resolve providers via SceneContract.physicsProfileId (falling back to the bundled twin-injection-default), so swapping scenes changes neither tools nor channels; a hot reload stages a new generation and drains the old one while trials and MPC hold leases, so in-flight work is never invalidated and retireProvider only unloads at zero references. The bundled injection provider ships through that same external contract (server/plugins-builtin/twin-injection-default/), and plugins live in the usual scopes with no restart for disable/reload. Field tables and a runnable example: docs/plugins.md → "Hybrid-twin provider plugins"; SDK surface: docs/sdk.md §4.10.

Usage

Authentication

Email + password login issues a bearer token (multiple tokens per user, individually revocable).

# register
curl -X POST http://localhost:3000/api/users/register \
  -H 'content-type: application/json' \
  -d '{"email":"you@example.com","password":"secret","name":"you"}'

# every workshop call
curl http://localhost:3000/api/workshop/channels \
  -H 'authorization: Bearer <token>'

Line-level permissions

Industrial data is gated per production line with three states, managed by an admin in the built-in Permissions page (/permissions, admin-only in the sidebar):

• admin / editor roles are unrestricted (operations roles).
• Regular users default to none — they see no line data until granted.
• Enforcement lives in the data plane: list endpoints filter by grant, write/dispatch endpoints return a human-readable 403, and Agent↔node bindings validate the line grant (DAQ needs read-only+, DCW needs operate).
• Plugins get the same surface via ctx.permissions (lineMode / visibleLineIds / listGrants / setGrants) plus a permissions:changed lifecycle hook; the SDK REST client exposes client.permissions.overview() / client.permissions.set(...).

Execution modes

Prefix the task description (or pick in the composer UI):

Scheduled tasks

Any task can also be attached to a schedule so a channel keeps working when nobody is watching:

# create a schedule: patrol the line every 30 minutes
curl -X POST http://localhost:3000/api/workshop/schedules \
  -H 'authorization: Bearer <token>' -H 'content-type: application/json' \
  -d '{"channelId":"<id>","name":"line-patrol","title":"Line patrol","description":"Read all DAQ nodes on line 1 and post a drift summary to channel memory.","mode":"interval","intervalMs":1800000}'

The four entry points

Task state machine

SUBMITTED ─▶ ASSIGNED ─▶ WORKING ─▶ WAITING ─▶ COMPLETED
    │            │           │           │
    └────────────┴───────────┴──▶ CANCELED / FAILED ─▶ (retry ≤ 3 or cancel)

Verified end-to-end

Every claim above is backed by a suite you can re-run. The acceptance suites drive a production instance over real simulated plant protocols (Modbus TCP/RTU, OPC UA, MQTT, HTTP + an MQTT/Timescale pipeline) with real engine CLIs, and assert on the database, the event stream and the HTTP API — not on mocks. Two 2026-09-24 waves are archived: the baseline matrix (~1100+ real assertions, v0.7.45 production build, isolated AW_HOME, real browser) in docs/audit/e2e-2026-09-24-full-coverage.md, and the follow-up feature wave (real PLC node simulator + injection-molding AgentTeam closed loop, FIFO multi-goal, scheduled tasks, collaboration; the report records each result, including environment- or credential-limited failures and SKIPs) in docs/audit/e2e-2026-09-24-all-features.md.

The historical v0.7.20 acceptance baseline — 156 assertions, 0 failures — is archived in docs/audit/e2e-2026-09-07.md. Perf probing: scripts/_dbg-render-perf.mjs.

Project layout

AgentWorkShop/
├── bin/ · cli/                 # aw CLI — command registry · built-in commands · config engine
├── app/                        # Nuxt 4 frontend (srcDir)
│   ├── pages/                  # / · /workshop · /workshop/agents · /workshop/teams
│   │                           # /workshop/channel-templates · /workshop/schedules · /workshop/w/:id
│   │                           # /town · /daq · /daq/:id · /dcw · /dcw/:id
│   │                           # /aml · /operations · /monitor · /logs · /permissions
│   │                           # /plugins · /users · /tokens · /settings
│   ├── components/workshop/    # timeline · lanes · task board · memory panel · 3D town
│   └── stores/composables/     # Pinia + AEP client
├── server/
│   ├── api/                    # REST + WS + A2A + MCP routes
│   ├── services/workshop/
│   │   ├── runtime/            # manager · scheduler-loop · task-