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

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, 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, 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

   cp .env.example .env.local

2. Enable the Pro Workbench UI

   Add the public flag to .env.local:

   NEXT_PUBLIC_PRO_WORKBENCH_ENABLED=true

3. Enable the agent runtime

   Add the server flag and database URL:

   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

   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 redirects you to the home page.

How the Entry Gate Works

The workbench entry logic lives in 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 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:

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. 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 combines both checks before rendering 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 will return false. Consequently, 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 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.

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