# How LangGraph Integration Orchestrates Multi-Agent Classroom Interactions in OpenMAIC

> Discover how LangGraph integration orchestrates multi-agent classroom interactions in OpenMAIC. Learn about its stateless StateGraph topology and real-time dialogue streaming.

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

---

**OpenMAIC uses LangGraph's Director Graph to coordinate AI agents through a stateless, single-round StateGraph topology that streams real-time classroom dialogue via Server-Sent Events.**

The THU-MAIC/OpenMAIC repository implements a sophisticated multi-agent classroom simulation using LangGraph (`@langchain/langgraph`) to manage conversational flow between AI participants. The system centers on a fixed-topology `StateGraph` called the **Director Graph**, which processes one turn per HTTP request to maintain stateless scalability while enabling complex multi-turn discussions through client-side orchestration.

## The Director Graph Architecture

At the core of OpenMAIC's orchestration lies a deliberately constrained graph topology designed for reliability and horizontal scaling.

### Fixed Graph Topology

The Director Graph follows a strict linear path: `START → director → (agent_generate) → END`. This single-round design ensures deterministic termination while supporting dynamic speaker selection. In [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts) (lines 4-9), the graph is constructed using LangGraph's `StateGraph` API with a custom `OrchestratorState` annotation that tracks messages, turn counts, available agents, and the whiteboard ledger.

The **director node** evaluates the current context to determine which agent speaks next, while the **agent-generate node** executes the selected agent's LLM call. This separation of concerns allows the system to inject decision logic between conversation turns without persisting server-side state.

### Stateless Design Philosophy

Unlike persistent multi-turn graphs, OpenMAIC's implementation in [`lib/orchestration/stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/stateless-generate.ts) (lines 406-413) treats each HTTP request as an independent graph invocation. The client serializes the entire conversation history—messages, agent configurations, and metadata—into the `StatelessChatRequest` payload. The server processes one `director → agent` cycle, returns the updated state and generated events, and immediately terminates the graph execution.

This architectural choice eliminates server-side session management, allowing requests to be handled by any available instance. The `buildInitialState` function (lines 31-48 in [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts)) reconstructs the LangGraph state object from the incoming request payload, enabling seamless horizontal scaling.

## The Director Node: Orchestrating Speaker Selection

The director node serves as the classroom moderator, implementing distinct logic paths for single-agent and multi-agent scenarios.

### Single-Agent vs Multi-Agent Modes

In **single-agent mode**, the director operates as a pure code path without LLM calls. During turn 0, it automatically dispatches the sole configured agent; subsequent turns cue the user for input. This optimization avoids unnecessary latency when only one AI participant is present, as implemented in [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts) (lines 15-34).

In **multi-agent mode**, the director employs more complex logic. On the first turn, it can dispatch a predefined **trigger agent** immediately. For subsequent turns, the director invokes an LLM to analyze the conversation context and select the next speaker, determine if the user should respond, or terminate the discussion. This decision flow appears in lines 59-78 of [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts), where the director constructs a specialized prompt describing available agents, their personas, and the conversation history.

### LLM-Based Decision Flow

When multiple agents are available, the director calls the underlying language model through the `AISdkLangGraphAdapter`. The LLM returns a structured decision indicating which `agentId` should speak next or whether to yield to the user. This implementation leverages LangGraph's conditional edge support, where the director node's return value determines whether the flow proceeds to `agent_generate` or exits to `END`.

## Agent Generation and Streaming

Once the director selects a speaker, the system transitions to the agent-generate node, which handles LLM interaction and real-time event streaming.

### Event-Driven Streaming Architecture

The `runAgentGeneration` function (lines 31-68 in [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts)) streams agent responses using LangGraph's custom stream mode via `config.writer()`. As the LLM generates content, the system emits a sequence of SSE-compatible events:

- `agent_start`: Signals that an agent has begun generating
- `text_delta`: Contains incremental text chunks as they are produced
- `action`: Transmits structured tool calls or classroom actions
- `agent_end`: Marks completion of the generation cycle

The streaming loop (lines 114-176 in [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts)) parses the LLM's structured output while simultaneously yielding delta chunks, enabling the frontend to display real-time typing animations and immediate feedback.

### AI-SDK Adapter Bridge

OpenMAIC bridges LangGraph's `BaseChatModel` interface with the Vercel AI SDK through the `AISdkLangGraphAdapter` class in [`lib/orchestration/ai-sdk-adapter.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/ai-sdk-adapter.ts). This adapter (lines 43-52) unifies access to multiple providers including OpenAI, Anthropic, and Google.

The `_generate` method (lines 80-110) implements synchronous LLM calls via `callLLM`, while `streamGenerate` yields incremental chunks from `streamLLM`. This abstraction allows the Director Graph to remain provider-agnostic, switching between models by changing configuration rather than implementation code.

## Implementation Workflow

Integrating LangGraph into the classroom simulation requires three coordinated steps: state preparation, graph compilation, and execution.

### Building Initial State

Before invoking the graph, the system constructs the initial state using the `buildInitialState` utility:

```typescript
import { buildInitialState } from '@/lib/orchestration/director-graph';
import { getModel } from '@/lib/ai/llm';

async function prepareState(request: StatelessChatRequest) {
  const lm = await getModel(request.config.provider);
  return buildInitialState(request, lm, request.config.thinking);
}

```

This function (lines 31-48 in [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts)) assembles the `OrchestratorState` object, including message history, available agents from the configuration, user profile data, and whiteboard ledger entries.

### Graph Compilation and Execution

The orchestration entry point compiles and invokes the graph for each request:

```typescript
import { createOrchestrationGraph } from '@/lib/orchestration/director-graph';

export async function runOrchestration(request: StatelessChatRequest) {
  const state = await prepareState(request);
  const graph = createOrchestrationGraph();
  const result = await graph.invoke(state);
  return result;
}

```

The `createOrchestrationGraph` function (lines 84-96 in [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts)) constructs the `StateGraph` with its fixed topology and returns a compiled graph instance. The `invoke` call executes one complete director → agent cycle, returning the updated state containing new messages and generated events (as shown in [`stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/stateless-generate.ts) lines 406-413).

## Summary

- **LangGraph Director Graph**: OpenMAIC uses a single-round `StateGraph` with fixed topology (`START → director → agent_generate → END`) to orchestrate classroom interactions.
- **Stateless Architecture**: Each HTTP request carries the complete conversation context, enabling horizontal scaling and eliminating server-side session management.
- **Dual Operating Modes**: The director node implements optimized pure-code paths for single-agent scenarios and LLM-driven decision-making for multi-agent discussions.
- **Real-Time Streaming**: The system leverages LangGraph's `config.writer()` to emit SSE-compatible events including `text_delta`, `action`, and `thinking` updates.
- **Provider Abstraction**: The `AISdkLangGraphAdapter` bridges LangGraph with the Vercel AI SDK, supporting unified access to OpenAI, Anthropic, and other providers.

## Frequently Asked Questions

### What is the Director Graph in OpenMAIC?

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 coordinates multi-agent classroom simulations. It features a fixed linear topology with two primary nodes: the **director**, which selects the next speaker based on conversation context, and **agent_generate**, which executes the selected agent's LLM call and streams the response.

### How does OpenMAIC handle multi-turn conversations with a single-round graph?

OpenMAIC maintains statelessness by having the client serialize the entire conversation history—including messages, turn counts, and agent configurations—into each HTTP request. The server processes exactly one graph cycle (director decision + agent generation) per request, returning the updated state to the client. The client then issues subsequent requests to continue the dialogue, effectively externalizing the turn management while keeping the server horizontally scalable.

### What role does the AI-SDK Adapter play in the LangGraph integration?

The `AISdkLangGraphAdapter` (located in [`lib/orchestration/ai-sdk-adapter.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/ai-sdk-adapter.ts)) implements LangGraph's `BaseChatModel` interface using the Vercel AI SDK as the backend. It provides `_generate` for synchronous LLM calls and `streamGenerate` for incremental streaming, allowing the Director Graph to switch between AI providers (OpenAI, Anthropic, Google) without modifying the orchestration logic.

### How are real-time classroom updates streamed to the client?

The system uses LangGraph's custom stream mode through `config.writer()` callbacks. During agent generation, the `runAgentGeneration` function emits structured events such as `agent_start`, `text_delta`, and `agent_end` via the writer. These events are captured in the graph invocation result and forwarded to the client as Server-Sent Events, enabling the frontend to display real-time typing indicators, agent actions, and whiteboard updates.