# Understanding the `buildInitialState` Function in OpenMAIC Orchestration

> Discover how OpenMAIC's buildInitialState function creates the initial state for LangGraph orchestration, converting client requests into execution contexts with messages, config, and models.

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

---

**The `buildInitialState` function constructs the initial state object that powers LangGraph orchestration for single chat requests, translating raw client requests into fully-formed execution contexts containing messages, configuration overrides, and model instances.**

In the OpenMAIC repository, the orchestration layer uses LangGraph to manage multi-agent conversations. When a `StatelessChatRequest` arrives at the server, the system must transform this raw input into a structured state that the director graph can process. The `buildInitialState` function in [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts) performs this critical translation, ensuring the graph receives all necessary data to route execution correctly while maintaining stateless chat behavior.

## Core Responsibilities of `buildInitialState`

The function performs four essential tasks to prepare the orchestration context.

### Generate Per-Request Agent Configuration Overrides

`buildInitialState` extracts any `agentConfigs` supplied in the incoming request and constructs a map named `agentConfigOverrides`. This ensures newly created agents inherit specific configurations for the current request without persisting server-side state. According to the source code in [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts), this logic occupies lines 101 through 118.

### Capture Discussion Context

When requests include a discussion topic or prompt, the function stores these values under the `discussionContext` field. This makes the contextual information available to the director node during the generation flow, as implemented in lines 121 to 126.

### Preserve Incoming Director State

For multi-turn conversations, `buildInitialState` reads any previously produced director state from `request.directorState`. It extracts the `turnCount`, past `agentResponses`, and `whiteboardLedger` to maintain conversation continuity across requests. This state preservation logic appears in lines 128 through 145 of the source file.

### Assemble the Full State Payload

Finally, the function returns a complete object matching the `OrchestratorState.State` interface. This payload includes:

- **Static fields**: `messages`, `storeState`, `availableAgentIds`, `languageModel`, `thinkingConfig`, `discussionContext`, `triggerAgentId`, and `userProfile`
- **Runtime tracking**: `currentAgentId`, `turnCount`, `agentResponses`, `whiteboardLedger`, `shouldEnd`, and `totalActions`

The assembly of this comprehensive state object occurs in lines 150 to 166.

## Function Parameters and Return Type

`buildInitialState` accepts three specific inputs to construct the orchestration state:

- **`request: StatelessChatRequest`** — The raw client request containing messages, store data, and configuration settings
- **`languageModel: LanguageModel`** — A pre-instantiated LLM instance that the graph invokes during generation
- **`thinkingConfig?: ThinkingConfig`** — Optional per-request reasoning settings that modify agent behavior

The function returns an object strictly typed as `OrchestratorState.State`, which serves as the immutable initial context for the LangGraph execution.

## Integration with the Orchestration Pipeline

After constructing the state, the system feeds it directly into the orchestration graph's streaming method. In [`lib/orchestration/stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/stateless-generate.ts), the execution flow follows this pattern:

```typescript
const initialState = buildInitialState(request, languageModel, thinkingConfig);
const stream = await graph.stream(initialState, { /* streaming options */ });

```

This integration demonstrates how `buildInitialState` acts as the bridge between HTTP request handling and graph execution, ensuring `createOrchestrationGraph` receives properly initialized state before processing begins.

## Practical Implementation Examples

### Basic State Construction

The typical usage pattern involves creating the state and immediately starting the graph stream:

```typescript
import { buildInitialState } from './director-graph';
import { createOrchestrationGraph } from './director-graph';

// Assume `request` is a StatelessChatRequest from the client
// and `languageModel` is an instantiated LLM.
const graph = createOrchestrationGraph();

const initialState = buildInitialState(request, languageModel, request.thinkingConfig);
const stream = await graph.stream(initialState, {
  // optional streaming callbacks
});

```

### Debugging State Output

During development, you can inspect the produced state structure:

```typescript
console.log('Initial orchestration state:', JSON.stringify(initialState, null, 2));

```

### Runtime Agent Configuration Overrides

To override specific agent behaviors for a single request:

```typescript
request.config.agentConfigs = [
  {
    id: 'my-special-agent',
    name: 'Special Agent',
    // any other AgentConfig fields
  },
];
const state = buildInitialState(request, lm);
console.log(state.agentConfigOverrides['my-special-agent']);

```

## Summary

- **`buildInitialState`** translates raw `StatelessChatRequest` objects into structured `OrchestratorState.State` contexts for LangGraph execution.
- The function handles agent configuration overrides, discussion context preservation, and multi-turn state continuity without server-side persistence.
- Located in [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts) (lines 99-166), it serves as the critical bridge between HTTP request handling and graph-based orchestration.
- The resulting state contains both static configuration data and runtime tracking fields required by the director and agent nodes.

## Frequently Asked Questions

### What is the primary purpose of `buildInitialState` in OpenMAIC?

The function creates the initial execution context for LangGraph orchestration, converting incoming chat requests into properly typed state objects. It ensures the orchestration graph receives all necessary data including messages, model instances, and configuration overrides before processing begins.

### Where is the `buildInitialState` function located in the OpenMAIC codebase?

The function is defined in [`lib/orchestration/director-graph.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/director-graph.ts) between lines 99 and 166. This file also contains the `createOrchestrationGraph` function that consumes the state produced by `buildInitialState`.

### How does `buildInitialState` support multi-turn conversations?

The function reads `request.directorState` to extract conversation history including `turnCount`, previous `agentResponses`, and the `whiteboardLedger`. It incorporates these values into the new state object, allowing the orchestration graph to continue conversations seamlessly across discrete HTTP requests.

### Can `buildInitialState` modify agent behaviors for specific requests?

Yes. The function processes per-request agent configurations from `request.config.agentConfigs` and maps them into `agentConfigOverrides`. These overrides apply only to the current request execution, enabling dynamic agent behavior without modifying persistent server configurations.