# Director Graph in OpenMAIC: Orchestrating Multi-Agent Workflows with LangGraph

> Discover the Director Graph in OpenMAIC, the LangGraph StateGraph that orchestrates multi-agent workflows by managing state, aggregating evidence, and invoking tools for the Director agent.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: deep-dive
- Published: 2026-09-11

---

**The Director Graph is the central LangGraph StateGraph that manages OpenMAIC's multi-agent orchestration, handling state transitions, evidence aggregation, and tool invocation for the Director agent.**

The Director Graph serves as the core orchestration engine within the THU-MAIC/OpenMAIC repository, coordinating the lifecycle of the Director agent—the primary coordinator that manages Teacher, Student, and Whiteboard agents. Implemented in [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts), this deterministic state machine transforms raw UI interactions into structured LLM-driven dialogues while maintaining session consistency through compaction and refetch mechanisms.

## State-Machine Definition and Workflow Orchestration

The Director Graph declares named states that represent distinct phases of the orchestration lifecycle. According to the source code in [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts), the graph defines states such as `cue_user`, `read_scene`, and `close_session`, enforcing deterministic transitions between these nodes.

Each state corresponds to a specific operational phase:

- **Cue user**: Initiates interaction loops awaiting user input
- **Read scene**: Processes UI snapshots and selected elements
- **Close session**: Terminates the session after flushing pending evidence

The graph validates that transitions follow the defined edges, preventing invalid state jumps during multi-agent execution.

## Evidence Handling and Aggregation

The Director Graph aggregates UI evidence into structured *Director-scene evidence* consumable by downstream agents. When users interact with the interface, the graph collects scene snapshots and selected-element packets through the compaction runtime.

In [`lib/chat/pi/director-compaction.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/director-compaction.ts), the `createDirectorCompactionRuntime` function manages this evidence pipeline. The runtime ensures that even after history compaction, critical UI evidence remains accessible to the Director agent, maintaining context across long-running sessions.

## Prompt Construction for the Director LLM

At each state transition, the Director Graph constructs precise system prompts via `buildDirectorPrompt` in [`lib/chat/pi/prompts.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/prompts.ts). This function feeds the current state and accumulated evidence into a template that includes:

- Concise orchestration instructions
- Historical UI event logs
- Tool specifications required for the next turn

The prompt builder ensures the Director LLM receives only relevant context, preventing context window overflow while preserving decision-critical information.

## Tool Wiring and Inventory Management

The graph strictly controls which tools are visible to the Director agent at each step. According to [`tests/lib/chat/pi/director-tool-wiring.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/lib/chat/pi/director-tool-wiring.test.ts), the implementation explicitly excludes tools like `web_search` from the Director's inventory while exposing orchestration-specific tools such as `cue_user` and `close_session`.

This selective tool visibility prevents the Director from invoking inappropriate actions during specific workflow phases, ensuring that only the Teacher or specialized agents execute knowledge-retrieval operations.

## Compaction and Refetch Mechanisms

When UI history exceeds configured thresholds, the Director Graph triggers compaction routines to summarize past events while preserving necessary evidence. The `shouldCompact` method in the compaction runtime checks history size against `maxHistorySize` limits (defaulting to 10,000 tokens).

After compaction, the graph executes a refetch step to restore essential packets, ensuring the Director maintains a consistent view of the session state. This mechanism is validated in [`tests/lib/chat/pi/director-compaction-refetch.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/lib/chat/pi/director-compaction-refetch.test.ts), which confirms evidence integrity across compaction cycles.

## Executing the Director Graph

The typical entry point for running the Director Graph is `runPiDirectorLoop` in [`lib/chat/pi/director-loop.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/director-loop.ts). This function initializes the compaction runtime, builds the Director prompt, and drives the state machine through its transitions.

```typescript
import { runPiDirectorLoop } from '@/lib/chat/pi/director-loop';
import { buildDirectorPrompt } from '@/lib/chat/pi/prompts';
import { createDirectorCompactionRuntime } from '@/lib/chat/pi/director-compaction';

// Build the LLM prompt for the Director
const prompt = buildDirectorPrompt(
  "You are the orchestrator of a multi-agent session.",
  [{ name: 'teacher', tools: [{ name: 'cue_user' }] }],
  [],
  4,
);

// Initialize compaction runtime
const compaction = createDirectorCompactionRuntime({
  maxHistorySize: 10_000,
});

// Execute the Director Graph
await runPiDirectorLoop({
  prompt,
  compaction,
  // callbacks for UI evidence and state storage
});

```

### Manual Compaction Triggering

For long-running sessions, developers can manually invoke compaction when history grows large:

```typescript
import { createDirectorCompactionRuntime } from '@/lib/chat/pi/director-compaction';

const runtime = createDirectorCompactionRuntime({
  maxHistorySize: 5_000,
});

// Add UI evidence
runtime.addEvidence({ type: 'snapshot', data: {/* scene data */} });

// Trigger compaction when limits exceeded
if (runtime.shouldCompact()) {
  const summary = runtime.compact();
  console.log('Compacted history:', summary);
}

```

## Key Source Files in the Director Graph Architecture

The Director Graph implementation spans several critical files within the THU-MAIC/OpenMAIC repository:

- **[`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts)**: Defines the LangGraph StateGraph structure, states, and transition logic
- **[`lib/chat/pi/director-loop.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/director-loop.ts)**: Executes the graph for generation sessions, handling tool results and state persistence
- **[`lib/chat/pi/prompts.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/prompts.ts)**: Constructs system prompts embedding evidence and orchestration instructions
- **[`lib/chat/pi/director-compaction.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/director-compaction.ts)**: Implements runtime history summarization and evidence preservation
- **[`tests/lib/chat/pi/director-tool-wiring.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/lib/chat/pi/director-tool-wiring.test.ts)**: Validates tool inventory constraints and exclusion rules
- **[`tests/lib/chat/pi/director-compaction-refetch.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/lib/chat/pi/director-compaction-refetch.test.ts)**: Ensures evidence packet restoration post-compaction

## Summary

- The **Director Graph** is a LangGraph StateGraph defined in [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts) that serves as the central orchestration engine for OpenMAIC's multi-agent system.
- It manages **state transitions** through deterministic nodes including `cue_user`, `read_scene`, and `close_session`.
- The graph handles **evidence aggregation** via the compaction runtime in [`lib/chat/pi/director-compaction.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/chat/pi/director-compaction.ts), ensuring UI context persists across long sessions.
- **Prompt construction** occurs through `buildDirectorPrompt`, feeding state and evidence into the Director LLM with strict context windows.
- **Tool wiring** explicitly filters agent capabilities, excluding tools like `web_search` from the Director while exposing orchestration primitives.
- **Compaction and refetch** mechanisms prevent context overflow while maintaining session integrity through the `shouldCompact` and `compact` methods.

## Frequently Asked Questions

### What type of graph structure does the OpenMAIC Director Graph use?

The OpenMAIC Director Graph implements a **LangGraph StateGraph**. This structure defines named states and deterministic edges that control the flow between orchestration phases such as user cueing, scene reading, and session closure.

### How does the Director Graph prevent context window overflow during long sessions?

The graph utilizes a **compaction runtime** (`createDirectorCompactionRuntime`) that monitors history size against `maxHistorySize` thresholds. When exceeded, the `compact` method summarizes historical events while preserving critical evidence packets, followed by a refetch step to restore necessary context for the Director agent.

### Which tools are excluded from the Director agent's inventory?

According to [`tests/lib/chat/pi/director-tool-wiring.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/lib/chat/pi/director-tool-wiring.test.ts), tools such as **`web_search`** are explicitly excluded from the Director's tool inventory. The graph only exposes orchestration-specific tools like `cue_user` and `close_session` to prevent inappropriate invocation during workflow phases reserved for specialized agents.

### What triggers the `close_session` state in the Director Graph?

The `close_session` state triggers when the Director agent invokes the corresponding tool, typically after completing the pedagogical workflow or when the user terminates the interaction. The graph ensures all pending evidence is flushed via the compaction runtime before finalizing the session termination.