Where to Find the Core Orchestration Logic in the OpenMAIC Codebase

The core orchestration logic in OpenMAIC resides in the lib/orchestration directory, with the primary entry point at stateless-generate.ts and the graph definition at 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
2. Stateless Generation Loop – Handles streaming and state updates via stateless-generate.ts
3. Agent Registry – Manages configurations and runtime selection in registry/store.ts
4. Prompt Construction – Generates director-level system prompts through director-prompt.ts

Key Files and Their Responsibilities

director-graph.ts (Graph Construction)

Located at 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 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: Creates system-level prompts for the director agent that steers other agents
• 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: Implements the registry with caching, loading, and update operations
• types.ts: Defines TypeScript interfaces for agent configurations (model, temperature, voice, capabilities)
• agent-selection.ts: Manages persistence and restoration of active agents per scene

Tool Schemas and Summarizers

Supporting utilities include:

• 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 receives a StatelessChatRequest and loads active agents via registry/store.ts
2. Graph Construction: director-graph.ts assembles a StateGraph with nodes for the director and each active agent
3. Prompt Injection: prompt-builder.ts and 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:

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 to add the new node
2. Define state transitions that route director decisions to your new agent
3. Update lib/orchestration/registry/types.ts if introducing new configuration parameters
4. Modify lib/orchestration/prompt-builder.ts to handle the new agent's prompt template

Changes to 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 and the execution engine at 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 and 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. 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 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, which implements a registry pattern for loading, caching, and updating agent definitions. Type definitions in 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.

How can I customize the orchestration graph?

To customize the graph, modify 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 and agent configurations are updated in the registry.

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