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

> Discover how the OpenMAIC director node adapts its strategy based on agent count. Learn how turn budgets, agent lists, and rules change to optimize conversations.

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

---

**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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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:

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-prompt.ts) (lines 57–60) implements this conditional logic:

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/director-loop.ts) (line 66), the maximum tool calls are calculated as:

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-prompt.ts) (lines 38–47) embeds this history:

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-prompt.ts) (lines 99–101), crowded boards trigger explicit warnings:

```typescript
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

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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

```typescript
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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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`](https://github.com/THU-MAIC/OpenMAIC/blob/main/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.