# Where to Find the Core Orchestration Logic in the OpenMAIC Codebase

> Discover the core orchestration logic in the OpenMAIC codebase. Find key files like stateless-generate.ts and director-graph.ts within the lib orchestration directory.

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

---

**The core orchestration logic in OpenMAIC resides in the `lib/orchestration` directory, with the primary entry point at [`stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/stateless-generate.ts) and the graph definition at [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts).**

OpenMAIC implements a multi-agent conversation system using LangGraph to coordinate state machines across multiple AI agents. Understanding the exact location and interaction of these orchestration components is essential for developers looking to extend agent behaviors or debug conversation flows.

## Overview of the Orchestration Architecture

The orchestration layer follows a modular pipeline architecture. **State management** and **agent coordination** are decoupled from the application layer through a dedicated library structure.

According to the OpenMAIC source code, the orchestration system combines four distinct subsystems:

1. **Graph Execution Engine** – Built on LangGraph `StateGraph` in [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts)
2. **Stateless Generation Loop** – Handles streaming and state updates via [`stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/stateless-generate.ts)
3. **Agent Registry** – Manages configurations and runtime selection in [`registry/store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/registry/store.ts)
4. **Prompt Construction** – Generates director-level system prompts through [`director-prompt.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-prompt.ts)

## Key Files and Their Responsibilities

### director-graph.ts (Graph Construction)

Located at [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts), this file defines the **LangGraph state machine** that drives multi-agent conversations. It constructs a `StateGraph` where nodes represent the "director" agent and each active participant agent.

The graph manages transitions between agent turns, ensuring the director maintains oversight while delegating specific tasks to specialized agents.

### stateless-generate.ts (Generation Engine)

The file [`lib/orchestration/stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/stateless-generate.ts) serves as the **stateless generation entry point**. It constructs the initial graph state, injects the active agent list, and initiates the streaming loop.

This module handles:
- Streaming response iterators
- State updates between conversation turns
- Agent coordination timing

### Prompt Construction Layer

Two files manage prompt generation:

- **[`director-prompt.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-prompt.ts)**: Creates system-level prompts for the director agent that steers other agents
- **[`prompt-builder.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/prompt-builder.ts)**: Constructs structured, type-safe prompts for individual agents with proper context injection

These utilities ensure the director receives sufficient context to make routing decisions while individual agents receive task-specific instructions.

### Agent Registry and Selection

The `lib/orchestration/registry/` subdirectory contains the **agent configuration system**:

- **[`store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/store.ts)**: Implements the registry with caching, loading, and update operations
- **[`types.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/types.ts)**: Defines TypeScript interfaces for agent configurations (model, temperature, voice, capabilities)
- **[`agent-selection.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/agent-selection.ts)**: Manages persistence and restoration of active agents per scene

### Tool Schemas and Summarizers

Supporting utilities include:

- **[`tool-schemas.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tool-schemas.ts)**: Exposes whiteboard actions and state-context schemas available to the orchestrator
- **`summarizers/*`**: Utilities that condense conversation history, whiteboard state, and action contexts for efficient prompt injection

## How the Orchestration Pipeline Works

The orchestration follows a deterministic execution flow:

1. **Initialization**: [`stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/stateless-generate.ts) receives a `StatelessChatRequest` and loads active agents via [`registry/store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/registry/store.ts)
2. **Graph Construction**: [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts) assembles a `StateGraph` with nodes for the director and each active agent
3. **Prompt Injection**: [`prompt-builder.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/prompt-builder.ts) and [`director-prompt.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-prompt.ts) generate textual instructions based on current state
4. **Execution Loop**: The stateless engine runs the graph, streaming chunks through an async iterator while updating shared state
5. **Agent Routing**: The director node determines which agent speaks next, with transitions handled by the LangGraph runtime

## Practical Example: Running the Orchestrator

To invoke the orchestration engine from application code, import `StatelessGenerate` and the registry utilities:

```typescript
import { StatelessGenerate } from '@/lib/orchestration/stateless-generate';
import { getDefaultAgents } from '@/lib/orchestration/registry/store';

// Generate a multi-agent response for a classroom scene
async function runOrchestration(request: StatelessChatRequest) {
  // Retrieve default agent list (teacher, student, narrator, etc.)
  const agents = await getDefaultAgents();
  
  // Attach agents to the request configuration
  request.config.agentIds = agents.map(a => a.id);
  
  // Execute the orchestrator - returns a streaming iterator
  const stream = await StatelessGenerate.run(request);
  
  for await (const chunk of stream) {
    // Process each generated chunk (e.g., forward to UI)
    console.log(chunk);
  }
}

```

This pattern demonstrates how the registry abstracts agent definitions while `StatelessGenerate.run()` encapsulates the entire graph execution lifecycle.

## Extending the Orchestration Layer

To customize the orchestration graph—such as adding a new agent type or modifying routing logic:

1. Edit [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts) to add the new node
2. Define state transitions that route director decisions to your new agent
3. Update [`lib/orchestration/registry/types.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/registry/types.ts) if introducing new configuration parameters
4. Modify [`lib/orchestration/prompt-builder.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/prompt-builder.ts) to handle the new agent's prompt template

Changes to [`stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/stateless-generate.ts) are typically unnecessary unless modifying the initialization protocol or streaming behavior.

## Summary

- The **core orchestration logic** lives in `lib/orchestration/` with the graph definition at [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts) and the execution engine at [`stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/stateless-generate.ts)
- **Agent management** flows through the registry subsystem in `lib/orchestration/registry/`
- **Prompt construction** is handled by specialized builders in [`director-prompt.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-prompt.ts) and [`prompt-builder.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/prompt-builder.ts)
- The system uses **LangGraph StateGraph** to coordinate multi-agent conversations with a director-agent pattern
- Entry point for execution is `StatelessGenerate.run()` which returns an async iterator for streaming responses

## Frequently Asked Questions

### What is the entry point for the OpenMAIC orchestrator?

The primary entry point is `StatelessGenerate.run()` defined in [`lib/orchestration/stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/stateless-generate.ts). This static method accepts a `StatelessChatRequest`, initializes the graph state, and returns an async iterator that yields streaming message chunks.

### How does OpenMAIC manage multiple agents?

OpenMAIC uses a **director-agent pattern** implemented via LangGraph. The [`director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/director-graph.ts) file constructs a `StateGraph` where a central "director" agent coordinates specialized agents (teachers, students, narrators). The director determines turn-taking and task delegation while the registry system in `lib/orchestration/registry/` manages agent configurations and lifecycle.

### Where are agent configurations stored?

Agent configurations reside in [`lib/orchestration/registry/store.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/registry/store.ts), which implements a registry pattern for loading, caching, and updating agent definitions. Type definitions in [`lib/orchestration/registry/types.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/registry/types.ts) specify the structure for model parameters, voice settings, and capability flags. Runtime selection of active agents per scene is handled by [`agent-selection.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/agent-selection.ts).

### How can I customize the orchestration graph?

To customize the graph, modify [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts) to add or remove nodes and edges. Each node represents an agent (including the director), and edges define the routing logic between them. After modifying the graph structure, ensure corresponding prompt templates exist in [`prompt-builder.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/prompt-builder.ts) and agent configurations are updated in the registry.