# How Agent Configuration Overrides Are Applied to OpenMAIC's Initial State

> Learn how OpenMAIC applies agent configuration overrides to the initial state. Discover the merge order of defaults environment variables and request overrides for precise control.

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

---

**OpenMAIC merges server-side defaults, environment variables, and request-level `configOverrides` in [`lib/agent/runtime/build-agent.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/agent/runtime/build-agent.ts) to construct the agent's initial state, with later sources taking precedence over earlier ones.**

In the OpenMAIC framework, the initial state serves as the immutable seed for every agent session. Understanding how agent configuration overrides flow into this state is critical for customizing behavior across deployments without modifying core source code.

## The Three-Layer Configuration Merge

OpenMAIC employs a cascading merge strategy inside [`lib/agent/runtime/build-agent.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/agent/runtime/build-agent.ts). Three distinct sources contribute to the final configuration object that becomes part of the canvas initial state.

### Server-Side Defaults

The foundation consists of immutable defaults loaded from the repository's configuration directory and persisted workspace settings. The function `getAgentBaseConfig()` retrieves these values, establishing the baseline agent capabilities and provider settings.

### Environment-Derived Overrides

The runtime reads deployment-specific values from environment variables (e.g., `AGENT_TEMPERATURE`, `LLM_PROVIDER`) through `resolveEnvOverrides()`. These settings overwrite server defaults but remain subordinate to request-level inputs, allowing operators to tune systems without code changes.

### Request-Level Overrides

Client applications send per-session customizations via the `configOverrides` payload in the HTTP request body. These values always win during the merge, enabling dynamic UI controls like temperature sliders to instantly affect agent behavior.

## Implementation in build-agent.ts

The core merging logic resides in [`lib/agent/runtime/build-agent.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/agent/runtime/build-agent.ts). The `buildAgent` function executes a shallow merge where subsequent sources overwrite previous ones:

```typescript
export function buildAgent(request: AgentRequest) {
  // 1️⃣ Load immutable server-side defaults
  const baseConfig = getAgentBaseConfig();

  // 2️⃣ Apply environment-derived overrides
  const envConfig = resolveEnvOverrides();

  // 3️⃣ Extract request-level overrides
  const requestConfig = request.configOverrides ?? {};

  // 4️⃣ Merge with precedence: request > env > base
  const mergedConfig = {
    ...baseConfig,
    ...envConfig,
    ...requestConfig,
  };

  // 5️⃣ Package into the canvas initial state
  const initialState = {
    ...defaultCanvasState,
    config: mergedConfig,
  };

  return initialState;
}

```

This function returns the fully composed initial state that downstream orchestration consumes.

## Propagation to the Canvas Store

The merged configuration is injected into the static `initialState` object defined in [`lib/store/canvas.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/canvas.ts) at line 219. This object serves as the single source of truth for the agent's starting configuration, including UI layout and skill lists.

```typescript
// lib/store/canvas.ts (line 219)
const initialState = {
  ...defaultCanvasState,
  config: mergedConfig, // Injected from build-agent.ts
};

```

## Orchestration and State Initialization

When a new session begins, [`lib/orchestration/stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/stateless-generate.ts) consumes this initial state to seed the execution graph. The streaming pipeline initializes with these configuration values locked in, ensuring consistent behavior throughout the session lifecycle.

## Validation Through Testing

The precedence rules are enforced by comprehensive test suites:

- **[`tests/agent-runtime/tool-call-integrity.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/tool-call-integrity.test.ts)** verifies that request-level `configOverrides` correctly modify tool call parameters in the initial state.
- **[`tests/server/provider-config.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/server/provider-config.test.ts)** validates that environment variables override server-side YAML configurations while remaining subordinate to request payloads.

## Practical Implementation Examples

Supplying a temperature override from the client:

```typescript
await fetch('/api/agent/sessions', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    model: 'gpt-4',
    configOverrides: { temperature: 0.9 },
  }),
});

```

Setting global provider defaults via environment:

```bash

# .env file

AGENT_PROVIDER=openai
AGENT_TEMPERATURE=0.7

```

Inspecting the merged configuration at runtime:

```typescript
import { useCanvasStore } from '@/lib/store/canvas';
const { config } = useCanvasStore.getState();
console.log(config); // Final merged configuration

```

## Summary

- **Three sources feed the initial state:** server-side defaults, environment variables, and request-level overrides.
- **Precedence is strict:** request overrides beat environment variables, which beat server defaults.
- **Implementation lives in** [`lib/agent/runtime/build-agent.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/agent/runtime/build-agent.ts), where `buildAgent()` performs a shallow merge.
- **The canvas store** ([`lib/store/canvas.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/canvas.ts), line 219) receives the final configuration object.
- **Orchestration begins** with [`lib/orchestration/stateless-generate.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/orchestration/stateless-generate.ts) using this seed state.
- **Tests in** [`tests/agent-runtime/tool-call-integrity.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/agent-runtime/tool-call-integrity.test.ts) and [`tests/server/provider-config.test.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/tests/server/provider-config.test.ts) guarantee correct precedence.

## Frequently Asked Questions

### What happens if the same key exists in both environment variables and request overrides?

The request override wins. The merge logic in `buildAgent` applies `requestConfig` last, ensuring client-specified values always take precedence over deployment environment settings.

### Does OpenMAIC support deep merging of nested configuration objects?

No. The merge performed in [`lib/agent/runtime/build-agent.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/agent/runtime/build-agent.ts) is shallow. Top-level keys are replaced wholesale rather than recursively merged, simplifying the precedence model and preventing unintended partial overrides.

### How can I verify which configuration values are active in a running session?

Import the canvas store from [`lib/store/canvas.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/store/canvas.ts) and inspect the `config` property. This object reflects the fully merged state after all three layers have been applied during the initial `buildAgent` call.