How to Customize Agent Behavior with agentConfigOverrides in OpenMAIC

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

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 and ultimately invokes the same store mutation.

3. Materialize the Roster

During orchestration, the system calls materializeRoster() (located in 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:

// 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:

// 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:

// 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: Defines the AgentConfig and GeneratedAgentConfig interfaces, plus the createAgentFromTemplate() factory function.
• lib/store/stage.ts: Contains the setStageAgents mutation that writes the generatedAgentConfigs array to the stage document.
• 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: Handles the POST /api/classroom/roster endpoint for server-side roster updates.
• 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 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), 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 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. 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.

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