What Is the OpenMAIC Agent Workbench? A Deep Dive into the Pro Interface for AI Course Generation

The OpenMAIC Agent Workbench is a chat-first, durable workspace introduced in OpenMAIC v1.0.0 that enables an LLM-driven agent to plan, build, and revise entire courses while you watch or steer the process in real time.

The OpenMAIC Agent Workbench represents the "Pro" side of the THU-MAIC/OpenMAIC repository, transforming static course creation into an interactive, streaming dialogue with an AI agent. Unlike traditional interfaces that require manual assembly, this workbench provides a persistent environment where agents execute skills, stream progress updates via Server-Sent Events (SSE), and incrementally sync course state while maintaining full revision history.

Core Architecture and Components

The workbench exposes a three-pane interface: a left navigation rail for folders and conversations, a central chat pane for agent narration, and a right-side course pane displaying the evolving classroom. These UI elements rest on five core technical pillars implemented in the lib/workbench/ directory.

Conversation Pane and Event Streaming

The conversation pane functions as a fold over the event log, streaming the agent’s turn-by-turn actions without querying course data directly. It consumes the control-plane event stream via the useWorkbenchStream hook attached to /api/agent/sessions/:id/events. This hook establishes an EventSource connection that receives SSE frames including caught_up, stage_freshness, media-ready, and tool-execution events defined in WORKBENCH_EVENT_TYPES. The implementation folds incoming frames into the UI state and handles replay logic for session catch-up.

Course Pane and Manifest Diff Sync

The course pane maintains a live view of generated content (slides, quizzes, simulations) through incremental synchronization rather than full document refreshes. The useStageFreshnessSync hook polls /api/stages/:id/freshness to retrieve revision metadata, diffs the manifest against the local state, and refetches only changed scenes via GET /api/stages/:id/scenes?ids=. This minimize-bandwidth approach resides in lib/workbench/use-workbench-session.ts alongside the streaming logic.

Durable Sessions and Agent Runtime

Server-backed sessions survive restarts, support cancellation, and accept mid-stream steering instructions. The control plane routes events through /api/agent/* endpoints covering sessions, owner-events, materials, and skills. The server-side implementation lives in lib/server/agent-runtime/ and manages the LangGraph orchestration graph that drives the multi-agent planner.

Built-in Skills System

The agent invokes approximately twenty pre-packaged capabilities ranging from curriculum planning to PPTX import and media generation. Skill metadata is defined in lib/workbench/agent-skills.ts starting at line 10, with UI helpers skillDisplayLabel and skillTitle surfacing human-readable names. The runtime dynamically loads these definitions to populate the agent's available toolset.

Pluggable Storage Layer

The workbench operates in two modes: browser-only storage or PostgreSQL-backed persistence. When NEXT_PUBLIC_PERSISTENCE is enabled, the system uses the @openmaic/storage abstraction wired through lib/persistence/server-auth.ts. This allows the workbench to scale from local prototyping to production deployments without code changes.

How the Workbench Works Under the Hood

The OpenMAIC Agent Workbench coordinates client and server state through a precise five-phase lifecycle:

1. Session Bootstrap – On initialization, useWorkbenchStream fetches session metadata from /api/agent/sessions/:id to obtain the prompt, status, and stage ID (lines 22-48 in use-workbench-session.ts).

2. Event Streaming – The client subscribes to all WORKBENCH_EVENT_TYPES via SSE, processing frames for stage freshness updates, tool executions, and media completion (lines 84-96).

3. Replay and Catch-Up – Upon attachment, the client replays the full event log from the server. The caught_up event signals transition to live streaming, while side-effects like audio/video generation are processed during replay (lines 98-112).

4. Freshness Synchronization – The stage manifest (containing revision numbers for each scene) is fetched and diffed. Only scenes with changed revisions are re-downloaded, ensuring sub-second UI updates during agent operation (lines 125-138).

5. Write-Side Baseline – After each successful save, recordWriteBaseline stores the current manifest as the write baseline around line 200. This enables conflict detection and the "aggregate-save veto" mechanism that prevents overwriting concurrent changes.

Enabling and Running the Workbench

The OpenMAIC Agent Workbench is disabled by default and must be enabled at build time. You must set two environment variables to activate the Pro interface and its server-side runtime.

# Enable the Pro workbench UI

echo "NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true" >> .env.local

# Enable the agent runtime server

echo "OPENMAIC_AGENT_RUNTIME_ENABLED=true" >> .env.local

After enabling flags, bootstrap the application:

git clone https://github.com/THU-MAIC/OpenMAIC.git
cd OpenMAIC
pnpm install
pnpm dev

Navigate to http://localhost:3000 and click the Pro button on the home page to launch the three-pane interface. Click "New Session" to initialize a durable agent run and watch the course construction begin.

Integrating Workbench Hooks

Below is a minimal Next.js page demonstrating how to consume the workbench APIs:

import { useWorkbenchStream, useStageFreshnessSync } from '@/lib/workbench/use-workbench-session';
import { useAgentSkills } from '@/lib/workbench/agent-skills';

export default function WorkbenchPage({ sessionId, stageId }) {
  // Attach to agent event stream
  const { events, status } = useWorkbenchStream(sessionId);
  
  // Keep course content synchronized
  const { scenes, loading } = useStageFreshnessSync(stageId, { bootstrapDocument: true });
  
  // Display available agent capabilities
  const { skills } = useAgentSkills();
  
  return (
    <div className="workbench">
      <aside>
        {skills.map(s => (
          <div key={s.id}>
            {s.title || s.name}: {s.description}
          </div>
        ))}
      </aside>
      <main>
        <div className="chat">Status: {status}</div>
        <div className="stage">
          {loading ? 'Syncing...' : scenes.map(scene => <Scene key={scene.id} data={scene} />)}
        </div>
      </main>
    </div>
  );
}

Key Source Files and Implementation Details

Understanding the following files provides complete visibility into the workbench's operation:

• lib/workbench/use-workbench-session.ts – Contains useWorkbenchStream for SSE handling and useStageFreshnessSync for incremental document updates.
• lib/workbench/agent-skills.ts – Defines skill metadata, loading logic, and UI display helpers (skillDisplayLabel, skillTitle).
• lib/server/agent-runtime/ – Houses the durable session implementation, event generation, and skill execution engine.
• packages/@openmaic/storage/ – Storage abstraction supporting browser memory, PostgreSQL, and S3 backends.
• lib/orchestration/ – LangGraph orchestration graph defining the multi-agent planning logic.
• components/workbench/ – React components rendering the three-pane layout (conversation, stage view, navigation).

Summary

• The OpenMAIC Agent Workbench is a Pro-tier interface enabling real-time collaboration with an LLM agent for course generation.
• It uses Server-Sent Events (/api/agent/sessions/:id/events) to stream agent actions and manifest diffing to synchronize course state efficiently.
• Durable sessions persist across browser refreshes and support mid-session steering via the agent runtime in lib/server/agent-runtime/.
• The system requires NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true and OPENMAIC_AGENT_RUNTIME_ENABLED=true to activate.
• Core hooks useWorkbenchStream and useStageFreshnessSync in lib/workbench/use-workbench-session.ts manage the client-side data layer.

Frequently Asked Questions

How does the OpenMAIC Agent Workbench differ from the standard interface?

The standard interface provides manual course editing tools, while the Agent Workbench introduces a chat-first, agent-driven paradigm. The workbench maintains durable server sessions, streams agent reasoning in real time, and allows you to steer the AI with follow-up instructions rather than manually building each slide or quiz.

What infrastructure is required to run the workbench with persistent sessions?

While the workbench can run entirely in the browser for testing, production deployments require PostgreSQL (enabled via NEXT_PUBLIC_PERSISTENCE) and the agent runtime server activated with OPENMAIC_AGENT_RUNTIME_ENABLED=true. The storage abstraction in @openmaic/storage handles the backend specifics without requiring changes to the workbench code.

How does the freshness sync mechanism minimize bandwidth usage?

Instead of downloading the entire course document on every update, the useStageFreshnessSync hook polls /api/stages/:id/freshness to obtain revision metadata. It compares this manifest against the local baseline and issues targeted GET /api/stages/:id/scenes?ids= requests only for changed scenes, reducing payload sizes by 90% or more during active agent generation.

Can I customize or extend the skills available to the agent?

Yes. The skill registry in lib/workbench/agent-skills.ts defines approximately twenty built-in capabilities, but the agent runtime supports dynamic skill loading. You can modify the skill definitions in this file or extend the runtime in lib/server/agent-runtime/ to register new tools, which will immediately surface in the UI via the useAgentSkills hook and skillDisplayLabel helpers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}