# How to Customize Agent Behavior with agentConfigOverrides in OpenMAIC

> Customize agent behavior in OpenMAIC using agentConfigOverrides. Override name, persona, voice, and actions to persist custom configurations for runtime materialization.

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

---

**Use `agentConfigOverrides` in OpenMAIC to override any field of an `AgentConfig`—including name, persona, voice settings, and allowed actions—by persisting custom configurations to the stage document and letting the orchestration layer materialize them at runtime.**

OpenMAIC represents each AI participant—whether a teacher, student, or assistant—as an `AgentConfig` object. While the platform ships with sensible defaults, `agentConfigOverrides` let you tailor any agent's behavior for a specific classroom by storing modified configurations in the `generatedAgentConfigs` property of the stage document. These overrides become the source of truth for prompt generation, text-to-speech, UI rendering, and action permissions.

## Understanding agentConfigOverrides

Every AI agent in OpenMAIC is defined by an `AgentConfig` that specifies its name, role, persona, allowed actions, voice configuration, and UI appearance. By default, the platform uses built-in templates, but `agentConfigOverrides` allow you to supersede any of these fields for a specific stage (classroom session).

When you supply an override, it is stored as a `GeneratedAgentConfig` object—an `AgentConfig` supplemented with metadata flags like `isGenerated` and `boundStageId`—inside the `generatedAgentConfigs` array of the stage document. According to the OpenMAIC source code in [`lib/edit/agent-roster.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/edit/agent-roster.ts), the orchestration layer reads this array to build the active roster, falling back to legacy `agentIds` only when the overrides array is empty.

## The Four-Step Override Flow

### 1. Create a GeneratedAgentConfig

Start by constructing your override using the `createAgentFromTemplate()` helper defined in [`lib/orchestration/registry/types.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/registry/types.ts). This function accepts a partial `AgentConfig` and returns a `GeneratedAgentConfig` ready for persistence.

Key fields you can override include:

- `name`: Display name for the UI
- `persona`: System prompt defining behavior
- `voiceConfig`: TTS provider and voice ID
- `color`: Hex code for UI theming
- `allowedActions`: Array of permitted action types

### 2. Persist to the Stage Document

Once created, the override must be written to the stage state. The primary client-side mechanism is the `setStageAgents` mutation in [`lib/store/stage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/stage.ts):

```tsx
useStageStore.getState().setStageAgents([teacherOverride, assistantOverride]);

```

Alternatively, you can persist via the REST API endpoint `POST /api/classroom/roster`, which is handled by [`lib/server/agent-runtime/roster-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/roster-tools.ts) and ultimately invokes the same store mutation.

### 3. Materialize the Roster

During orchestration, the system calls `materializeRoster()` (located in [`lib/edit/agent-roster.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/edit/agent-roster.ts)) to retrieve the active agent list. This function returns the `generatedAgentConfigs` array verbatim if it exists, ensuring your overrides take precedence over default templates.

### 4. Runtime Consumption

All downstream systems consume the materialized `AgentConfig` objects:

- **Prompt building**: Uses the overridden `persona` field
- **Action permissions**: Validated against `allowedActions` via `getActionsForRole()`
- **TTS playback**: Uses the `voiceConfig` settings from `lib/agent/runtime/*`
- **UI rendering**: Applies the custom `color` and `avatar` values

## Code Example: Implementing agentConfigOverrides

The following example demonstrates overriding a teacher agent's persona and voice, persisting it via the React store, and materializing it for runtime use:

```tsx
// Step 1: Build the override
import { createAgentFromTemplate } from '@/lib/orchestration/registry/types';
import { useStageStore } from '@/lib/store/stage';

const teacherOverride = createAgentFromTemplate({
  name: 'Prof. Li',
  role: 'teacher',
  persona: 'You are a friendly Mandarin‑English bilingual teacher.',
  avatar: '👩‍🏫',
  color: '#0066FF',
  allowedActions: [],
  priority: 10,
  voiceConfig: { providerId: 'zhiyu', voiceId: 'zhiyu-female' },
}, 'teacher‑override');

// Step 2: Persist to stage
useStageStore.getState().setStageAgents([teacherOverride]);

```

To update the roster from an external client:

```typescript
// Alternative: Via REST API
await fetch('/api/classroom/roster', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    stageId: 'stage‑123',
    agents: [teacherOverride],
  }),
});

```

Finally, retrieve the active configuration within orchestration logic:

```typescript
// Step 3: Materialize roster
import { materializeRoster } from '@/lib/edit/agent-roster';

const activeAgents = materializeRoster(stage); 
// Returns array containing the overridden teacher config

```

## Key Source Files for agentConfigOverrides

- **[`lib/orchestration/registry/types.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/registry/types.ts)**: Defines the `AgentConfig` and `GeneratedAgentConfig` interfaces, plus the `createAgentFromTemplate()` factory function.
- **[`lib/store/stage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/stage.ts)**: Contains the `setStageAgents` mutation that writes the `generatedAgentConfigs` array to the stage document.
- **[`lib/edit/agent-roster.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/edit/agent-roster.ts)**: Implements `materializeRoster()`, which reads stored overrides or falls back to legacy agent IDs.
- **[`lib/server/agent-runtime/roster-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/roster-tools.ts)**: Handles the `POST /api/classroom/roster` endpoint for server-side roster updates.
- **[`lib/orchestration/registry/store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/registry/store.ts)**: Consumes the materialized roster during runtime orchestration.

## Summary

- **`agentConfigOverrides`** allow fine-grained customization of any `AgentConfig` field for specific classroom stages.
- Overrides are stored in the **`generatedAgentConfigs`** array of the stage document, making them persistent and version-controllable.
- Use **`createAgentFromTemplate()`** to construct valid override objects with proper typing.
- Persist changes via **`setStageAgents()`** in the React store or the **`/api/classroom/roster`** HTTP endpoint.
- The orchestration layer invokes **`materializeRoster()`** to resolve overrides at runtime, affecting prompts, actions, voice, and UI immediately.

## Frequently Asked Questions

### What fields can I override with agentConfigOverrides?

You can override any property defined in the `AgentConfig` interface, including `name`, `role`, `persona`, `avatar`, `color`, `priority`, `voiceConfig`, and `allowedActions`. The [`lib/orchestration/registry/types.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/registry/types.ts) file defines these fields and their TypeScript constraints.

### How do agentConfigOverrides persist across page reloads?

Because overrides are stored in the **`generatedAgentConfigs`** property of the stage document (managed via [`lib/store/stage.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/stage.ts)), they are saved to the database alongside other stage state. When the classroom reloads, the orchestration layer retrieves these configurations via `materializeRoster()` and rebuilds the agent roster identically.

### What happens if no agentConfigOverrides are provided?

If the `generatedAgentConfigs` array is empty or undefined, `materializeRoster()` in [`lib/edit/agent-roster.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/edit/agent-roster.ts) automatically falls back to the legacy `stage.agentIds` lookup, loading the default built-in agents defined in the registry. This ensures backward compatibility while allowing opt-in customization.

### Can I use agentConfigOverrides from a backend service rather than the React frontend?

Yes. You can POST to the **`/api/classroom/roster`** endpoint, which is handled by [`lib/server/agent-runtime/roster-tools.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/agent-runtime/roster-tools.ts). This server-side route accepts a JSON payload containing the `stageId` and `agents` array, performs validation, and commits the overrides to the stage store, making them available to all connected clients immediately.