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

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, 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, 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, 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. 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, 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, 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. This function initializes the compaction runtime, builds the Director prompt, and drives the state machine through its transitions.

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:

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: Defines the LangGraph StateGraph structure, states, and transition logic
• lib/chat/pi/director-loop.ts: Executes the graph for generation sessions, handling tool results and state persistence
• lib/chat/pi/prompts.ts: Constructs system prompts embedding evidence and orchestration instructions
• lib/chat/pi/director-compaction.ts: Implements runtime history summarization and evidence preservation
• 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: Ensures evidence packet restoration post-compaction

Summary

• The Director Graph is a LangGraph StateGraph defined in 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, 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, 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.

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