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

> Discover how the OpenMAIC director node intelligently adapts its strategy by adjusting maxAgentTurns based on agent count, optimizing dialogue pacing and preventing early termination for smoother operation.

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

---

**The director node dynamically scales its orchestration limits using the `maxAgentTurns` parameter—derived directly from the number of classroom agents—to control dialogue pacing and prevent premature termination.**

The OpenMAIC framework employs a **director node** as the central orchestrator that manages multi-agent classroom conversations. This director automatically adjusts its behavior based on how many agents participate in a session, ensuring optimal teaching interactions without over-generation or premature closure. Understanding this adaptive mechanism reveals how the system balances thoroughness with efficiency in AI-mediated education.

## Scaling Limits Based on Participant Numbers

The director's adaptive strategy centers on the **`maxAgentTurns`** parameter, which the system calculates from the length of the incoming agent configuration array. This single value propagates through three critical control mechanisms that scale proportionally with participant count.

### Constraining Agent Turns via System Prompts

The director receives explicit behavioral constraints through its system prompt to prevent excessive agent invocations. In [`lib/chat/pi/prompts.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/prompts.ts) at line 101, the template injects the dynamic limit:

```text
You may call at most ${maxAgentTurns} classroom agent turns in this server‑side loop.

```

This instruction ensures the underlying language model respects the agent count boundary, preventing the director from over-scheduling turns when many classroom agents are available.

### Computing the Tool Call Ceiling

The system calculates a hard ceiling on total tool invocations using a formula that grows with agent participation. Within [`lib/chat/pi/director-loop.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/director-loop.ts) (lines 30-33), the `runPiDirectorLoop` function determines:

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

```

For a single agent, this yields a cap of 4 tool calls (`max(3, 4)`), while four agents raise the limit to 12 calls (`max(12, 7)`). This non-linear scaling provides sufficient bandwidth for complex multi-agent coordination without allowing infinite loops.

### Orchestrating Session Termination

The director evaluates termination conditions after each tool execution to determine when to cue the user or close the session. At lines 38-39 of [`director-loop.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-loop.ts), the termination logic checks:

```ts
const terminate = sessionClosed || userCued || directorToolCalls >= maxDirectorToolCalls;

```

With fewer agents, the low `maxDirectorToolCalls` threshold triggers rapid user cueing, creating snappy interactions. Conversely, many agents unlock higher thresholds, allowing the director to gather comprehensive evidence from multiple sources before finalizing the teaching output.

## Implementation Example

To launch a director loop with adaptive strategy, calculate `maxAgentTurns` from your agent list and pass it to the orchestration function:

```ts
import { runPiDirectorLoop } from '@/lib/chat/pi/director-loop';

// Configure four classroom agents
const agentConfigs = [
  { id: 'a1', role: 'teacher', /* ... */ },
  { id: 'a2', role: 'assistant', /* ... */ },
  { id: 'a3', role: 'assistant', /* ... */ },
  { id: 'a4', role: 'assistant', /* ... */ },
];

const maxAgentTurns = agentConfigs.length; // → 4

await runPiDirectorLoop({
  body: requestBody,
  agentConfigs,
  maxAgentTurns, // Drives adaptive limits
  languageModel,
  thinkingConfig,
});

```

Inside the loop, the director automatically applies the scaled limits:

```ts
const maxDirectorToolCalls = Math.max(opts.maxAgentTurns * 3, opts.maxAgentTurns + 3);
// With 4 agents → 12 tool calls permitted

if (directorToolCalls >= maxDirectorToolCalls) {
  // Trigger user cue or session close
}

```

## Summary

- **`maxAgentTurns`** derives directly from agent count and drives all adaptive behavior in the director node according to the OpenMAIC source code.
- System prompts in [`lib/chat/pi/prompts.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/prompts.ts) constrain the LLM to respect turn limits proportional to participant numbers.
- The tool call ceiling calculation (`maxAgentTurns * 3` vs `maxAgentTurns + 3`) ensures adequate bandwidth for complex multi-agent scenarios while preventing runaway loops.
- Termination logic scales automatically, allowing brief interactions with few agents and extended evidence-gathering with many agents.

## Frequently Asked Questions

### How does OpenMAIC prevent the director from over-calling agents when many are available?

The system injects a hard limit into the director's system prompt at [`lib/chat/pi/prompts.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/prompts.ts), explicitly stating the maximum agent turns allowed. This prompt constraint, combined with the `maxDirectorToolCalls` ceiling calculated in [`director-loop.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-loop.ts), creates a dual safeguard that respects the `maxAgentTurns` parameter regardless of how many agents are configured.

### What happens if the director reaches the tool call limit before gathering sufficient teaching content?

When `directorToolCalls >= maxDirectorToolCalls`, the termination flag triggers, forcing the director to either cue the user with current progress or close the session. This design intentionally balances thoroughness with responsiveness, ensuring users receive timely feedback even if the ideal evidence threshold is not met.

### Which source files control the director's adaptive strategy in OpenMAIC?

The primary orchestration occurs in [`lib/chat/pi/director-loop.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/director-loop.ts), where limits are calculated and termination logic executes. Prompt construction happens in [`lib/chat/pi/prompts.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/prompts.ts) (line 101), while request handlers in [`app/api/chat/pi/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/chat/pi/route.ts) derive the initial `maxAgentTurns` value from incoming agent configurations.

### Can the director handle zero agents or single-agent scenarios?

Yes. When `maxAgentTurns` equals zero or one, the formula `Math.max(opts.maxAgentTurns * 3, opts.maxAgentTurns + 3)` yields a minimum viable ceiling (3 or 4 calls respectively), allowing the director to function gracefully in degenerate or single-agent classroom configurations without system failures.