# OpenMAIC Outline Generation Entry Point: Where It Starts and How It Works

> Discover the OpenMAIC outline generation entry point. Learn how the generateOutlineTool function in curriculum-tools.ts orchestrates the outline creation workflow for your agent.

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

---

**The entry point for the outline generation process in OpenMAIC is the `generateOutlineTool` function in [`lib/server/agent-runtime/curriculum-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/curriculum-tools.ts), which receives tool requests from the agent runtime and orchestrates the entire outline creation workflow.**

OpenMAIC is a generative AI curriculum development platform developed by THU-MAIC. The outline generation capability sits at the heart of its course creation pipeline, converting user briefs into structured learning materials. Understanding where this process originates helps developers extend the tool or debug generation issues.

## The Server-Side Entry Point: [`lib/server/agent-runtime/curriculum-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/curriculum-tools.ts)

The definitive entry point for outline generation resides in the agent runtime's curriculum tooling layer. This is where the **`generate_outline`** tool is implemented and where all outline creation requests converge.

When the OpenMAIC Workbench or any client interface initiates outline generation, the agent runtime routes the request to this specific handler. The function signature and implementation pattern follow the standard tool contract used throughout the codebase.

```typescript
// lib/server/agent-runtime/curriculum-tools.ts
export async function generateOutlineTool(params: {
  courseId: string;
  brief: string;
}) {
  // 1️⃣ Build the outline based on the brief
  const outline = await outlineBuilder.build(params.brief);

  // 2️⃣ Create a new stage and one scene per outline item
  const stage = await stageStore.createStage(params.courseId, outline);

  // 3️⃣ Persist the outline envelope
  await documentStore.saveOutline(stage.id, {
    outlines: outline,
    generationComplete: false,
    producer: 'generate_outline',
  });

  return { stageId: stage.id, outline };
}

```

This function performs three critical operations: it constructs the outline structure from the user's brief, instantiates a new stage with associated scenes for each outline element, and persists the partial result to enable recovery and progress tracking.

### Why This Location Matters

The [`curriculum-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/curriculum-tools.ts) file serves as the **central coordination point** for all curriculum-related operations in OpenMAIC. By consolidating outline generation here, the system maintains:

- **Consistent error handling** across all generation attempts
- **Unified persistence patterns** for document storage
- **Observable progress states** that the UI can monitor
- **Reusable outline building logic** that other tools can invoke

## How the Entry Point Is Triggered

Outline generation does not occur in isolation. The flow originates from user interaction in the Workbench interface and traverses through the agent system before reaching the entry point.

### Step 1: Client-Side Tool Invocation

Developers or curriculum designers trigger generation through conversational interfaces or direct API calls. The client uses the agent tool system with the registered `'generate_outline'` identifier:

```typescript
// In a Workbench conversation script
await agent.tool('generate_outline', {
  courseId: 'course-123',
  brief: 'Create a 5‑slide outline for an introductory AI lecture',
});

```

### Step 2: Agent Runtime Routing

The agent runtime receives this tool call, resolves the handler by name, and dispatches to `generateOutlineTool`. This routing layer handles authentication, parameter validation, and rate limiting before the entry point executes.

### Step 3: Stage and Scene Creation

Inside the entry point, the `stageStore.createStage()` call establishes the structural foundation. Each outline item becomes a scene, enabling fine-grained manipulation and individual generation of content blocks later in the workflow.

## Supporting Files in the Outline Generation Flow

While [`curriculum-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/curriculum-tools.ts) contains the primary entry point, several adjacent files participate in the complete process:

| File | Role in Outline Generation |
|------|---------------------------|
| [`lib/server/agent-runtime/curriculum-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/curriculum-tools.ts) | **Primary entry point** – implements `generateOutlineTool`, orchestrates building, staging, and persistence |
| [`components/generation/outlines-editor.tsx`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/generation/outlines-editor.tsx) | UI component displaying generated outlines and regeneration triggers |
| [`components/workbench/chat/tool-progress.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/components/workbench/chat/tool-progress.ts) | Progress visualization for `generate_outline` execution in conversation context |
| [`tests/workbench/tool-presentation.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/workbench/tool-presentation.test.ts) | Automated verification that outline generation invokes correctly and renders results |

These components demonstrate the entry point's integration into the broader OpenMAIC architecture. The separation between server-side orchestration and client-side presentation follows the framework's design principles for maintainable generative workflows.

## Extending the Entry Point for Custom Behavior

Developers modifying OpenMAIC's outline generation should focus on [`curriculum-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/curriculum-tools.ts) as the primary interception point. Common extension patterns include:

- **Pre-processing hooks** – modifying the brief before `outlineBuilder.build()` executes
- **Custom outline builders** – injecting alternative `outlineBuilder` implementations for specialized domains
- **Post-persistence actions** – adding side effects after `documentStore.saveOutline()` completes

Since the entry point returns both `stageId` and the constructed `outline`, downstream consumers can immediately reference the created resources without additional lookups.

## Summary

- The **outline generation entry point** in OpenMAIC is `generateOutlineTool` located in **[`lib/server/agent-runtime/curriculum-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/curriculum-tools.ts)**.
- This server-side function receives `generate_outline` tool requests, builds outlines from briefs, creates stages with per-item scenes, and persists the envelope.
- Client interfaces trigger the flow via `agent.tool('generate_outline', {...})`, with the agent runtime handling routing to the entry point.
- Supporting UI components and tests in `components/generation/` and `tests/workbench/` complete the observable end-to-end process.

## Frequently Asked Questions

### What parameters does the OpenMAIC outline generation entry point accept?

The `generateOutlineTool` function accepts an object with `courseId` (string) and `brief` (string) properties. The `courseId` associates the generated outline with an existing curriculum, while the `brief` provides the natural language instructions that shape the outline structure.

### Can the outline generation entry point be called directly without the agent runtime?

While technically possible within server-side code, the intended architecture routes all calls through the agent runtime to ensure proper authentication, logging, and progress tracking. Direct function imports bypass these safeguards and are not recommended for production use.

### How does OpenMAIC handle failures during the outline generation entry point?

The entry point delegates error handling to the agent runtime's standard tool execution wrapper. If `outlineBuilder.build()` throws or `stageStore.createStage()` fails, the error propagates to the runtime, which surfaces appropriate messages to the client and leaves no partial stage data in an inconsistent state due to the atomic persistence pattern.