# OpenMAIC Agent Runtime Tools: Complete Guide to Built-In Tools and Skills

> Explore OpenMAIC agent runtime tools and skills. Discover nine categories including generation, audio, and UI utilities to enhance your agent's capabilities.

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

---

**OpenMAIC provides nine categories of built-in tools and skills—generation, DSL-course, audio-deck, curriculum, material, roster, voice-clone, skill-edit, and UI utilities—exported as constant name lists and registered at runtime.**

The OpenMAIC agent runtime ships with a comprehensive toolkit that AI agents can invoke directly. These tools are organized by functional domain and exposed through exported constants in `lib/server/agent-runtime/`. When the server starts, [`lib/server/agent-runtime/skill-preload.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/skill-preload.ts) consumes these constants to build the final `AgentTool[]` array passed to the agent core. Each tool implements parameter validation via type-box schemas and executes side effects ranging from document writes to media synthesis.

## Generation Tools for Scene and Action Management

The **generation tools** handle creation, listing, duplication, and action generation for pages (scenes) within a course.

These tools are defined in [`lib/server/agent-runtime/generation-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/generation-tools.ts) and exported as `GENERATION_TOOL_NAMES`:

| Tool Name | Purpose |
|-----------|---------|
| `generate_scene` | Create a new scene/page with specified parameters |
| `list_scenes` | Enumerate existing scenes in a stage |
| `generate_actions` | Generate actionable elements for a specific page |
| `duplicate_scene` | Clone an existing scene with modifications |

```typescript
import { GENERATION_TOOL_NAMES } from '@/lib/server/agent-runtime/generation-tools';

console.log('Generation tools available to the agent:');
console.log(GENERATION_TOOL_NAMES);
// → [ 'generate_scene', 'list_scenes', 'generate_actions', 'duplicate_scene' ]

```

To invoke a generation tool via the HTTP API:

```typescript
await fetch('/api/agent/tool', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    tool: 'generate_scene',
    params: {
      stageId: 'stage-123',
      order: 1,
      title: 'Introduction',
      brief: 'Explain the basics of photosynthesis.',
      type: 'slide',
    },
  }),
});

```

## DSL-Course Tools for Stage Manipulation

The **DSL-course tools** provide course-level object manipulation as defined by OpenMAIC's domain-specific language. These are exported as `DSL_COURSE_TOOL_NAMES` from [`lib/server/agent-runtime/course-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/course-tools.ts).

Tool names are dynamically built from the DSL schema. Common patterns include:

- `create_stage` – Instantiate a new stage
- `patch_stage` – Partially update stage properties  
- `delete_stage` – Remove a stage from the course

The full enumeration depends on the DSL definition—refer to the source file for the complete list of generated tool names.

## Audio-Deck and Voice-Clone Tools

OpenMAIC provides two overlapping constants for audio synthesis: `COURSE_AUDIO_DECK_TOOL_NAMES` and `VOICE_CLONE_TOOL_NAMES`. Both are exported from [`lib/server/agent-runtime/voice-clone-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/voice-clone-tools.ts) and expose identical tool names, separated for granular permission handling.

Available audio tools:

| Tool Name | Purpose |
|-----------|---------|
| `synthesize_tts` | Generate text-to-speech narration |
| `clone_voice` | Create a voice clone from audio samples |
| `list_voices` | Enumerate available voice models |
| `delete_voice` | Remove a voice model from storage |

## Curriculum Allow-List Tool Set

The `CURRICULUM_ALLOWLIST` in [`lib/server/agent-runtime/curriculum-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/curriculum-tools.ts) does not expose individual tools but instead defines which tool identifiers the curriculum layer permits. This acts as a security gate, ensuring agents only invoke curriculum-approved operations.

## Material Tools for Asset Management

The **material tools** handle upload, listing, and lifecycle management of learning material assets. Defined in [`lib/server/agent-runtime/material-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/material-tools.ts) and exported as `MATERIAL_TOOL_NAMES`:

| Tool Name | Purpose |
|-----------|---------|
| `upload_material` | Ingest new media or document assets |
| `list_materials` | Query available materials with filters |
| `delete_material` | Permanently remove an asset |
| `update_material` | Modify metadata or replace content |

## Roster Tools for Participant Management

The **roster tools** manage student and participant enrollment. Exported as `ROSTER_TOOL_NAMES` from [`lib/server/agent-runtime/roster-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/roster-tools.ts):

| Tool Name | Purpose |
|-----------|---------|
| `add_roster_entry` | Enroll a new participant |
| `remove_roster_entry` | Unenroll an existing participant |
| `list_roster` | Retrieve enrolled participants |
| `update_roster_entry` | Modify participant status or metadata |

## Skill-Edit Tools for Custom Skill Operations

The **skill-edit tools** enable the agent to inspect and modify user-defined skills at runtime. Defined in [`lib/server/agent-runtime/skill-edit-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/skill-edit-tools.ts) and exported as `SKILL_EDIT_TOOL_NAMES`:

| Tool Name | Purpose |
|-----------|---------|
| `read_skill` | Retrieve a skill's definition and parameters |
| `patch_skill` | Apply partial updates to a skill configuration |

Example invocation to read a skill:

```typescript
await fetch('/api/agent/tool', {
  method: 'POST',
  body: JSON.stringify({
    tool: 'read_skill',
    params: { skillId: 'my-custom-skill' },
  }),
});

```

## UI and Workbench Utilities

Additional convenience utilities for presenter mode, pagination, and navigation are defined in `lib/workbench/`. These are wired into the runtime via the same registration mechanism but are **not** exposed as top-level agent tools—they serve the user interface rather than agent invocations.

## Tool Registration and Runtime Integration

All tool constants converge in [`lib/server/agent-runtime/skill-preload.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/skill-preload.ts), which orchestrates the runtime initialization:

1. Imports each constant (`GENERATION_TOOL_NAMES`, `MATERIAL_TOOL_NAMES`, etc.)
2. Maps names to concrete `AgentTool` implementations with type-box parameter schemas
3. Assembles the final `AgentTool[]` array for the agent core

Each `AgentTool` validates incoming parameters before executing side effects, ensuring type safety across document writes, media uploads, and audio synthesis operations.

## Summary

- OpenMAIC agent runtime tools are organized into **nine functional domains** with exported constants for programmatic discovery
- **Generation tools** (`generate_scene`, `list_scenes`, `generate_actions`, `duplicate_scene`) handle page lifecycle in [`lib/server/agent-runtime/generation-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/generation-tools.ts)
- **DSL-course tools** provide dynamic stage manipulation based on the DSL schema in [`lib/server/agent-runtime/course-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/course-tools.ts)
- **Audio and voice tools** (`synthesize_tts`, `clone_voice`, `list_voices`, `delete_voice`) support narration and voice cloning in [`lib/server/agent-runtime/voice-clone-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/voice-clone-tools.ts)
- **Material, roster, and skill-edit tools** cover asset management, enrollment, and custom skill operations
- **Skill-preload** ([`lib/server/agent-runtime/skill-preload.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/skill-preload.ts)) registers all tools with the agent core at startup using type-box validation

## Frequently Asked Questions

### How do I discover which OpenMAIC agent tools are available programmatically?

Import the exported constants from their respective files in `lib/server/agent-runtime/`. Each constant is a string array of tool names. For example, `import { GENERATION_TOOL_NAMES } from '@/lib/server/agent-runtime/generation-tools'` gives you the complete list of generation tools without hardcoding names.

### What is the difference between COURSE_AUDIO_DECK_TOOL_NAMES and VOICE_CLONE_TOOL_NAMES?

Both constants expose identical tool names and originate from [`lib/server/agent-runtime/voice-clone-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/voice-clone-tools.ts). They are separated to enable granular permission handling—the curriculum layer can reference one while the agent runtime references the other, allowing different access policies for the same underlying capabilities.

### Can I add custom tools to the OpenMAIC agent runtime?

Yes. Define your tool implementation following the `AgentTool` interface with type-box parameter validation, then export its name through a new constant or add it to an existing category. Import and register it in [`lib/server/agent-runtime/skill-preload.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/skill-preload.ts) to include it in the startup tool array passed to the agent core.

### How does the curriculum allow-list restrict tool usage?

The `CURRICULUM_ALLOWLIST` in [`lib/server/agent-runtime/curriculum-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/curriculum-tools.ts) contains tool identifier strings that the curriculum layer permits. Before executing a tool invocation, the runtime checks against this allow-list, rejecting any tool not explicitly authorized for the current curriculum context.