AgentOS Workbench is a React + Vite dashboard for inspecting, debugging, and orchestrating AgentOS agent sessions. It provides a zero-config cockpit for streaming AgentOS chunks, session timelines, multi-agent coordination, evaluation benchmarks, and plan lifecycle management.
Built on @framers/agentos, the open-source TypeScript runtime for building production AI agents with cognitive memory, HEXACO personality, multi-agent orchestration, and runtime tool forging.
| Feature | Description |
|---|---|
| Session Inspector | Color-coded timeline rendering of streaming AgentOS chunks (text deltas, tool calls, tool results, workflow updates, agency updates, errors) |
| Compose | Request composer for prototyping agent turns, replaying transcripts, and testing multi-turn conversations |
| Multi-Agent Dashboard | Visualization of 6 coordination strategies (sequential, parallel, debate, review loop, hierarchical, graph DAG) |
| Adaptive Execution | Task-outcome KPI tracking, fail-open overrides, tool-exposure recovery state from the adaptive execution runtime |
| Evaluation | Benchmark runner for testing agent quality, response accuracy, and guardrail effectiveness |
| Planning | Plan lifecycle management with checkpoint history, fork/restore, and runtime-backed graph-run inspection |
| RAG Workspace | Live retrieval + demo-backed document-library fallbacks across 7 vector backends |
| Runtime Inspector | Inspect exports from generateText, generateImage, AgentGraph, workflow(), and mission() |
# 1. Clone and install
git clone https://github.com/framerslab/agentos-workbench.git
cd agentos-workbench
pnpm install
(cd backend && npm ci)
# 2. Configure the backend
cp backend/.env.example backend/.env
# Edit backend/.env and add your provider API keys
# 3. Start the backend and the workbench
pnpm dev
# Opens at http://localhost:5175# Option A: Explicit API base URL
VITE_API_URL=http://localhost:3001
# Option B: Same-origin /api/* with dev proxy
VITE_BACKEND_PORT=3001
VITE_BACKEND_HOST=localhost
VITE_BACKEND_PROTOCOL=httpAGENTOS_WORKBENCH_BACKEND_PORT=3001
AGENTOS_WORKBENCH_BACKEND_HOST=localhost
# AGENTOS_WORKBENCH_ALLOWED_ORIGINS=http://localhost:5175
# AGENTOS_WORKBENCH_ALLOWED_HOSTS=workbench.lan
AGENTOS_WORKBENCH_EVALUATION_STORE_PATH=../.data/evaluation-store.json
AGENTOS_WORKBENCH_PLANNING_STORE_PATH=../.data/planning-store.jsonThe backend has no login, and it runs with your provider keys loaded. It listens on localhost and answers browser requests only from the workbench front end (ports 5175 and 4173). It refuses a request from any other page, including an image or a link that carries no Origin header, and a request whose Host header names another site. To reach it from another machine, set AGENTOS_WORKBENCH_BACKEND_HOST=0.0.0.0, list the front end's origin in AGENTOS_WORKBENCH_ALLOWED_ORIGINS and the name other machines use for this one in AGENTOS_WORKBENCH_ALLOWED_HOSTS (an IP address needs no entry), and run it only on a network you trust.
Provider API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) should be set in the backend environment. AgentOS supports 11 LLM providers with automatic fallback chains.
AgentOS uses a three-layer cognitive architecture:
| Layer | Purpose | Configuration |
|---|---|---|
| GMI (Generalized Mind Instance) | Persona prompts, memory policies, tool permissions, language preferences, guardrail hooks | Reusable cognitive cores versioned and exported across apps |
| Agent | Product surface (labels, icons, availability) wrapping a GMI | Preserves GMI cognition and policy |
| Agency | Coordinates multiple GMIs via 6 workflow strategies | Visualized via WORKFLOW_UPDATE and AGENCY_UPDATE events |
| Method | Endpoint | Description |
|---|---|---|
POST |
/api/agentos/chat |
Send a turn (messages, mode, optional workflow) |
GET |
/api/agentos/stream |
SSE stream for incremental updates |
GET |
/api/agentos/personas |
List personas (filters: capability, tier, search) |
GET |
/api/agentos/workflows/definitions |
List workflow definitions |
POST |
/api/agentos/agency/workflow/start |
Start agency workflow |
GET |
/api/agentos/graph-runs |
List persisted runtime graph-run records |
GET |
/api/agentos/graph-runs/:runId |
Inspect a single graph-run record |
GET |
/api/evaluation/runs |
List evaluation runs |
POST |
/api/evaluation/run |
Start a new evaluation run |
GET |
/api/planning/plans |
List persisted plans |
POST |
/api/planning/plans |
Create a new plan |
See backend/docs/index.html for the generated backend route documentation.
- Local-first: all data stored in your browser via IndexedDB (no server writes)
- Stored entities: personas (remote + local), agencies, sessions (timeline events)
- Export: per-session from the timeline header, or all data from Settings > Data > "Export all"
- Import: Settings > Data > "Import..." (schema:
agentos-workbench-export-v1) - Clear: Settings > Data > "Clear storage"
pnpm dev # Vite dev server at http://localhost:5175
pnpm build # Production build (emits dist/)
pnpm preview # Preview production build
pnpm lint # ESLint
pnpm typecheck # TypeScript type checking
pnpm e2e # All Playwright test suites
pnpm e2e:chromium # Chromium only
pnpm e2e:firefox # Firefox only
pnpm e2e:webkit # WebKit (serialized for stability)
pnpm bundle:report # Bundle size analysis
pnpm bundle:check # Enforce bundle size budgets
pnpm build:check # Build + bundle report + budget enforcement| Package | Description | Links |
|---|---|---|
@framers/agentos |
Core TypeScript AI agent runtime | GitHub · Docs |
@framers/sql-storage-adapter |
SQL persistence for agent memory and sessions | npm |
| AgentOS Workbench | Visual debugging dashboard (this repo) | GitHub |
| AgentOS Docs | Guides, tutorials, and TypeDoc API reference | docs.agentos.sh |
| Wilds.ai | AI game worlds powered by AgentOS | wilds.ai |
| Guide | What |
|---|---|
| Contributing | Development setup, what CI runs, commit and pull request rules, review threads, contribution licensing |
| Agent instructions | Commands and conventions for coding agents |
| Code of Conduct | Community standards |
| Security Policy | Reporting vulnerabilities privately |
| Support | Where to get help |
- AgentOS core (
@framers/agentos) — Apache 2.0 - Workbench — MIT
·
Built by Manic Agency LLC / Frame.dev