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

> Discover the OpenMAIC Agent Workbench, a chat-first workspace that lets AI plan build and revise courses in real time. Explore the pro interface for AI course generation.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: deep-dive
- Published: 2026-09-09

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.

```bash

# 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:

```bash
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:

```tsx
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/use-workbench-session.ts)** – Contains `useWorkbenchStream` for SSE handling and `useStageFreshnessSync` for incremental document updates.
- **[`lib/workbench/agent-skills.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.