Motus Agent Workbench

English | 简体中文

Motus Agent Workbench is a local-first agent project built on top of the Motus SDK. It combines a unified Python backend, session-oriented HITL flows, tool and skill runtime hosting, workflow orchestration, tracing, code preview runtimes, and a production-oriented React WebUI.

The goal is not to ship another chat wrapper. The goal is to consolidate sessions, tool execution, approvals, tracing, preview, and visualization into one reusable local agent architecture that can keep evolving into desktop, Tauri, or other UI surfaces.

This project builds on the upstream lithos-ai/motus open-source agent-serving project. Motus provides the SDK and runtime foundation; this repository focuses on the local workbench, unified backend adapters, WebUI, preview runtime, and integration layer around it.

Navigation

• Highlights for the product-level overview.
• Architecture for the backend and runtime topology.
• Quick Start for the shortest path to a working local setup.
• Who Is This For for intended users and teams.
• Roadmap for the next major directions.
• Documentation for deeper project references.

Highlights

• Session-first architecture with per-session config, history, title generation, usage, cost, and runtime state.
• Unified backend abstraction for both local and HITL session execution.
• HITL support for interrupts, resume flows, tool approval, question answering, and live telemetry.
• Workflow registry, planner, execution, cancel/terminate control, and tracing integration.
• Built-in HTML / React / Python preview runtime with Python terminal output.
• Embedded visualization support for Mermaid, structured charts, and data-analysis oriented blocks.
• React WebUI covering chat, workflow, tracing, runtime catalog, preview dock, themes, and i18n.

Screenshot

Architecture

flowchart LR
    User[User] --> WebUI[React WebUI]
    User --> APIClient[CLI / curl / external client]

    WebUI --> API[FastAPI API]
    APIClient --> API

    API --> Backend[SessionBackend abstraction]
    Backend --> Local[Local backend]
    Backend --> HITL[HITL backend]

    Local --> Chat[Chat service]
    HITL --> Chat
    Chat --> Agents[Motus agents]
    Chat --> Tools[Built-in tools + integrations]
    Chat --> Skills[skills/ runtime entry layer]

    API --> Workflow[Workflow service]
    API --> Preview[Preview runtime]
    API --> Tracing[Tracing service]

    Skills --> Vendor[vendored MiniMax skills submodule]
    Tools --> Runtime[runtime/ artifacts]
    Workflow --> Runtime
    Preview --> Runtime
    Tracing --> Runtime

Loading

Tech Stack

• Backend: Python 3.14, FastAPI, Motus SDK, uv
• Frontend: React 19, TypeScript, Vite, TanStack Query, Tailwind CSS 4
• Testing: pytest, Vitest, Playwright
• Visualization and rendering: Mermaid, ECharts, highlight.js, xterm

Repository Layout

apps/                  Entrypoints
core/                  Backend runtime implementation
core/backends/         Shared session backend abstraction
core/chat/             Sessions, history, titles, turn flow
core/preview/          HTML / React / Python preview runtime
core/servers/          FastAPI and HITL servers
core/schemas/          Shared schemas for backend and frontend
core/workflows/        Workflow registry, execution, persistence
docs/                  Stable public-facing documentation
docs/assets/           README assets and repository visuals
scripts/smoke/         End-to-end and system smoke scripts
skills/                Runtime skill entry layer
tests/                 Python tests
tools/integrations/    Tool implementations and integrations
vendor/minimax-skills/ Third-party skills submodule
web/                   React WebUI
runtime/               Local runtime artifacts, not committed

Primary docs:

• docs/project-structure.md
• docs/development-guide.md
• docs/frontend-integration-guide.md
• docs/runtime-requirements.md
• docs/open-source-release-checklist.md
• docs/open-source-audit.md

Quick Start

1. Clone the repository

Clone with submodules from the beginning:

git clone --recurse-submodules <repo-url>
cd motus_ui

If you already cloned the repository, initialize submodules once:

git submodule update --init --recursive

2. Prepare environment variables

cp .env.example .env

Common variables:

• OPENAI_API_KEY
• OPENAI_BASE_URL
• FIRECRAWL_KEY or FIRECRAWL_API_KEY
• APP_BACKEND_MODE
• MOTUS_TRACING_*

Keep real secrets in the local .env file only.

3. Install dependencies

uv sync
cd web
npm install
cd ..

4. Start the backend

uv run agent-server

Optional entrypoints:

uv run agent-hitl-server
uv run agent-tui

Typical local endpoints:

• API: http://127.0.0.1:8000/api
• WebUI: usually http://127.0.0.1:5173

5. Start the WebUI

cd web
npm run dev

Common Commands

Backend:

uv run pytest
uv run python -m py_compile apps/*.py core/**/*.py tools/**/*.py scripts/**/*.py
uv run python -m scripts.smoke.run_all

Frontend:

cd web
npm run build
npm run test
npm run e2e
npm run lint

Minimal API Example

Create a session:

curl -s http://127.0.0.1:8000/api/sessions \
  -H 'Content-Type: application/json' \
  -d '{"system_prompt":"You are a reliable assistant.","model_name":"gpt-4o"}'

Send a message:

curl -s http://127.0.0.1:8000/api/sessions/<session_id>/messages \
  -H 'Content-Type: application/json' \
  -d '{"content":"Summarize this project in one sentence."}'

Stream a turn:

curl -N http://127.0.0.1:8000/api/sessions/<session_id>/messages/stream \
  -H 'Content-Type: application/json' \
  -d '{"content":"Use tools first, then summarize the result."}'

Who Is This For

• Engineers building local-first agent applications with real session state and tool execution.
• Product teams that need approval gates, interrupt/resume flows, and HITL-ready backend contracts.
• Applied AI builders who want preview runtimes, visualization blocks, and workflow orchestration in one stack.
• Developers who prefer a Python backend with a modern React WebUI instead of stitching together multiple prototypes.

Roadmap

• Harden the desktop packaging path around the current backend and WebUI split for future Tauri delivery.
• Keep reducing large file hotspots and state coupling in both backend routers and page-level frontend controllers.
• Expand runtime catalog, workflow control, and multi-agent operations into more explicit product surfaces.
• Add stronger visual regression, smoke coverage, and release automation for public open-source maintenance.

Repository Conventions

• runtime/, release/, .venv/, node_modules/, web/dist/, coverage output, and test-results are not committed.
• Session logs, traces, uploads, preview artifacts, and debug screenshots should be treated as sensitive data.
• skills/ is the runtime skill entry layer, while tools/integrations/ contains concrete implementation code.
• vendor/minimax-skills/ is intentionally kept as a Git submodule to preserve upstream history and license boundaries.

Documentation

• AGENTS.md: contributor and coding conventions
• CONTRIBUTING.md: contribution process
• SECURITY.md: security policy
• docs/project-structure.md: codebase layout and structural guidance
• docs/development-guide.md: engineering conventions and backend/frontend boundaries
• docs/frontend-integration-guide.md: frontend contract and capability guidance
• docs/runtime-requirements.md: runtime requirements for tools, MCP, and skills
• docs/open-source-release-checklist.md: release checklist
• docs/open-source-audit.md: repository open-source audit

License

This repository is licensed under Apache License 2.0 (Apache-2.0).

The root repository follows Apache-2.0 to stay aligned with the current Motus ecosystem licensing direction and to keep reuse, modification, and redistribution straightforward for both individual and enterprise use.

Notes:

• The root repository source code and documentation are covered by the Apache-2.0 terms in LICENSE.
• vendor/minimax-skills/ is an upstream third-party submodule and keeps its own history and licensing context.