# How to Enable and Use the Agent Workbench in OpenMAIC: Complete Setup Guide

> Learn how to enable and use the Agent Workbench in OpenMAIC with our complete setup guide. Follow these simple steps to get started.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-08-31

---

**To enable the Agent Workbench in OpenMAIC, you must set two feature flags—`NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true` for the UI and `OPENMAIC_AGENT_RUNTIME_ENABLED=true` for the server runtime (plus a `DATABASE_URL`)—then start the dev server and navigate to `/workspace`.**

The **Agent Workbench** is a Pro-tier interface in the THU-MAIC/OpenMAIC repository that lets you chat with an AI agent to plan, build, and revise entire courses. It is gated behind environment-based feature flags that separate the client-side UI from the durable background runtime. This guide walks through the exact configuration required to unlock the workbench and integrate it into your workflow.

## Prerequisites and Feature Flag Architecture

OpenMAIC uses a dual-flag system to control the workbench. One flag controls whether the `/workspace` route is compiled into the client bundle, while the other controls whether the server actually starts the background agent process.

### Client-Side UI Flag

The `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED` variable is a **build-time** flag that Next.js inlines into the client bundle. When enabled, it activates the UI components and makes the `/workspace` route reachable. According to the source code in [`lib/config/feature-flags.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts), the helper `isProWorkbenchEnabled()` reads this value directly from `process.env`.

### Server-Side Runtime Flag

The `OPENMAIC_AGENT_RUNTIME_ENABLED` flag is **server-only** and requires a valid `DATABASE_URL`. As implemented in [`lib/config/feature-flags.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts), the function `isAgentRuntimeConfigured()` checks both that this flag is set to `"true"` and that the database connection string is non-empty. Without this, the durable background agent cannot execute course-building actions, even if the UI is visible.

## Step-by-Step Enablement Guide

Follow these steps to activate the Agent Workbench in your local environment.

1. **Create your local environment file**

   ```bash
   cp .env.example .env.local
   ```

2. **Enable the Pro Workbench UI**

   Add the public flag to `.env.local`:

   ```dotenv
   NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true
   ```

3. **Enable the agent runtime**

   Add the server flag and database URL:

   ```dotenv
   OPENMAIC_AGENT_RUNTIME_ENABLED=true
   DATABASE_URL=postgresql://user:password@host:5432/openmaic
   ```

   If `DATABASE_URL` is missing, the server logs an error and the workbench remains disabled.

4. **Install dependencies and start the server**

   ```bash
   pnpm install
   pnpm dev
   ```

   Watch the startup banner for the message *"Agent runtime enabled"* to confirm the background process is active.

5. **Access the workbench**

   Open your browser to:

   ```

   http://localhost:3000/workspace
   ```

   If both flags are correctly configured, the `WorkspaceEntry` component renders; otherwise, the middleware in [`app/workspace/page.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/workspace/page.tsx) redirects you to the home page.

## How the Entry Gate Works

The workbench entry logic lives in [`lib/workbench/entry-gate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/entry-gate.ts). The function `isWorkbenchEntryEnabled()` combines both checks:

1. `isProWorkbenchEnabled()` verifies the public build-time flag.
2. `isAgentRuntimeConfigured()` verifies the server flag and database connection.

Only when both return `true` does the entry gate allow access. The `/workspace` route implementation in [`app/workspace/page.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/workspace/page.tsx) invokes this gate on the server; if the check fails, it issues a redirect to `/`, ensuring users never see a broken interface.

## Using the Agent Workbench

Once enabled, the workbench presents a chat-first interface for course generation.

- **Chat interface**: Type prompts like *"Plan a beginner Python course"* to generate outlines, slides, and quizzes.
- **Material upload**: Drag and drop PDFs, videos, or audio files; the agent ingests them to enrich the course content.
- **Stage navigation**: Use the pane controls to move between generation stages (outline generation, slide creation, quiz assembly, etc.).

All interactions are backed by a **durable session** stored in the database configured via `DATABASE_URL`. This means you can pause, resume, or cancel a generation run at any point without losing progress.

## Programmatic Integration with Agent Skills

You can interact with the workbench runtime programmatically using the agent skills hook. The following example shows how to refresh the agent's skill cache after changing the material set:

```tsx
import { useAgentSkills } from '@/lib/workbench/agent-skills';

export function RefreshSkillsButton() {
  const { reload } = useAgentSkills();

  return (
    <button
      className="btn-primary"
      onClick={() => {
        void reload();  // Clears cache and refetches skills
      }}
    >
      Refresh Agent Skills
    </button>
  );
}

```

The `reload` function internally calls `invalidateAgentSkills()`, which respects the same runtime and UI flags defined in [`lib/config/feature-flags.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/config/feature-flags.ts). This ensures the operation only executes when the Agent Workbench is fully enabled.

## Summary

- **Dual-flag requirement**: You need both `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED` (client UI) and `OPENMAIC_AGENT_RUNTIME_ENABLED` (server runtime) set to `true` to use the Agent Workbench in OpenMAIC.
- **Database dependency**: The runtime flag requires a valid `DATABASE_URL`; without it, the workbench redirects to the home page.
- **Entry gate logic**: The `isWorkbenchEntryEnabled()` function in [`lib/workbench/entry-gate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/entry-gate.ts) combines both checks before rendering [`app/workspace/page.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/workspace/page.tsx).
- **Durable sessions**: All workbench interactions persist to the database, allowing asynchronous, long-running course generation workflows.

## Frequently Asked Questions

### What happens if I only enable the UI flag but not the runtime flag?

If you set `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true` but omit `OPENMAIC_AGENT_RUNTIME_ENABLED` or the `DATABASE_URL`, the `/workspace` route will be visible in the client bundle, but the entry gate in [`lib/workbench/entry-gate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/entry-gate.ts) will return `false`. Consequently, [`app/workspace/page.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/workspace/page.tsx) redirects all requests to the home page, preventing access to a non-functional interface.

### Do I need a specific database type for the Agent Workbench?

OpenMAIC supports any database compatible with its ORM, but PostgreSQL is recommended. The `DATABASE_URL` must be a valid connection string (e.g., `postgresql://user:pass@localhost:5432/openmaic`). The `isAgentRuntimeConfigured()` function specifically checks for a non-empty string; if missing, the server logs an initialization error and disables the agent runtime.

### Can I deploy the Agent Workbench in production?

Yes, provided you set the required environment variables in your production hosting platform. Ensure `NEXT_PUBLIC_PRO_WORKBENCH_ENABLED` is set at build time so Next.js includes the UI components, and set `OPENMAIC_AGENT_RUNTIME_ENABLED` and `DATABASE_URL` at runtime. The durable session architecture is designed for production use, supporting concurrent agent executions across multiple users.

### How do I customize the agent's behavior within the workbench?

You can extend the workbench by modifying the agent skills layer in [`lib/workbench/agent-skills.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/workbench/agent-skills.tsx) or by adjusting the system prompts in the course generation pipeline. Custom components can trigger reloads or session resets using the `useAgentSkills` hook, which automatically respects the feature flags to prevent errors when the workbench is disabled.