How the Director Node Adapts Its Strategy in OpenMAIC Based on Agent Count

The director node in OpenMAIC dynamically adjusts its orchestration strategy by modifying turn budgets, priority-ordered agent lists, and conversational rules based on the number of participating agents.

In the THU-MAIC/OpenMAIC repository, the director node serves as the central orchestration agent that determines which child-agent speaks next during multi-agent conversations. Unlike static coordination systems, the director automatically scales its decision-making logic according to how many agents are available. This adaptive behavior is implemented across several core modules that rebuild the director's context each turn.

Building Priority-Ordered Agent Lists for Variable-Sized Groups

The director's first adaptation mechanism constructs a dynamic view of all available agents. In lib/orchestration/director-prompt.ts (lines 34–36), the system transforms the AgentConfig array into a markdown-formatted hierarchy that the underlying LLM can interpret:

const agentList = agents
  .map((a) => `- id: "${a.id}", name: "${a.name}", role: ${a.role}, priority: ${a.priority}`)
  .join('\n');

This list preserves the priority field from each agent configuration, creating an explicit ranking that guides the LLM's selection. When many agents are present, the director can leverage this hierarchy to route turns efficiently; with few agents, the list remains compact without overwhelming the prompt context.

Dynamic Opening Rules: Scaling Instructions to Group Size

The director's opening rule collapses or expands based on conversation mode and implicit agent count. The buildDirectorPrompt function in lib/orchestration/director-prompt.ts (lines 57–60) implements this conditional logic:

const rule1 = isDiscussion
  ? `1. The discussion initiator${triggerAgentId ? ` ("${triggerAgentId}")` : ''} ...`
  : "1. The teacher (role: teacher, highest priority) should usually speak first ...";

For typical multi-agent scenarios, this rule emphasizes that the teacher role (highest priority) should open the turn, establishing a clear speaking order. In single-agent or simplified configurations, the directive narrows to focus solely on that agent's participation.

Turn-Budget Scaling Through Tool-Call Limits

The director's computational budget scales directly with expected agent participation. In lib/chat/pi/director-loop.ts (line 66), the maximum tool calls are calculated as:

const maxDirectorToolCalls = Math.max(opts.maxAgentTurns * 3, opts.maxAgentTurns + 3);

This formula ensures non-linear budget growth: when maxAgentTurns increases (typically set proportional to agent count), the director receives substantially more tool invocations to coordinate complex group dynamics. Conversely, smaller groups receive tighter constraints that encourage rapid turn resolution.

Response History Tracking for Crowded Conversations

As more agents participate, the director maintains awareness of who has already contributed. The respondedList construction in lib/orchestration/director-prompt.ts (lines 38–47) embeds this history:

const respondedList = agentResponses.length > 0
  ? agentResponses.map(...).join('\n')
  : 'None yet.';

When many agents have spoken, this section grows richer, enabling the LLM to avoid redundant turns and identify gaps in participation. The director can then strategically select underrepresented agents or conclude the turn when coverage is sufficient.

Whiteboard State Awareness for Visual Collaboration

The director adapts to visual collaboration intensity through whiteboard monitoring. In lib/orchestration/director-prompt.ts (lines 99–101), crowded boards trigger explicit warnings:

if (elementCount > 5) { crowdedWarning = '\n⚠ The whiteboard is getting crowded …'; }

With many agents actively drawing, this signal helps the director route subsequent actions to organizer agents or prompt consolidation, preventing visual chaos that would impede group coordination.

Practical Implementation Examples

Configuring the Director Loop for Different Group Sizes

await runPiDirectorLoop({
  body,
  agentConfigs,
  send,
  languageModel,
  thinkingConfig,
  maxAgentTurns: agents.length * 2, // Scale budget with agent count
  maxActionsPerAgent: 5,
  // …other options
});

This pattern from lib/chat/pi/director-loop.ts demonstrates how applications can propagate agent-count awareness into the director's operational parameters.

Generating and Inspecting the Director Prompt

import { buildDirectorPrompt } from '@/lib/orchestration/director-prompt';

const systemPrompt = buildDirectorPrompt(
  agents,               // Array length determines list size
  summary,
  agentResponses,
  turnCount,
);

// Debug output reveals adapted structure
console.log(systemPrompt);
/*

# Agents

- id: "t1", name: "Teacher", role: teacher, priority: 10
- id: "s1", name: "Student-1", role: student, priority: 5
- id: "s2", name: "Student-2", role: student, priority: 5
...
Rule 1: The teacher (role: teacher, highest priority) should usually speak first …
*/

Summary

• Agent list construction in lib/orchestration/director-prompt.ts renders priority-ordered hierarchies that scale with group size.
• Dynamic opening rules collapse to simple directives for small groups or expand to structured turn-taking for large groups.
• Tool-call budgets calculated in lib/chat/pi/director-loop.ts grow non-linearly with maxAgentTurns, allocating more coordination resources when needed.
• Response tracking prevents redundant participation in crowded conversations by maintaining explicit spoken-agent history.
• Whiteboard awareness triggers reorganization prompts when visual collaboration becomes dense.

These mechanisms collectively enable the director node to operate efficiently across scenarios ranging from one-on-one tutoring to classrooms with dozens of simulated participants.

Frequently Asked Questions

How does OpenMAIC handle single-agent versus multi-agent scenarios?

The director detects implicit group size through the agents array length and isDiscussion flag. For single-agent scenarios, rules simplify to direct that agent's participation; for multi-agent scenarios, priority hierarchies and turn budgets expand to coordinate distributed participation.

What determines which agent speaks first in OpenMAIC?

The teacher role (highest priority value) receives precedence in the opening rule, as implemented in lib/orchestration/director-prompt.ts. When a specific triggerAgentId is designated for discussion initiation, that agent may override the default teacher-first ordering.

Can the director's behavior be tuned for specific group sizes?

Yes. The maxAgentTurns parameter passed to runPiDirectorLoop directly influences the maxDirectorToolCalls budget calculation. Applications can set this proportional to agents.length or any other heuristic to customize coordinator aggressiveness.

Where is the director's adaptive logic tested?

Unit tests in tests/lib/chat/pi/director-*.test.ts verify director behavior across varying agent-count scenarios, ensuring the prompt construction and loop execution respond correctly to group size changes.

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