Core concepts

Mozaik centers on one idea: everything the model sees and produces is modeled as structured context, not loose strings scattered across your codebase.

Messages, ContextItems, and SemanticEvents

Three kinds of events can be exchanged through an AgenticEnvironment:

• Messages — plain strings for conversational input/output. Delivered through onMessage(message: string). Use them for what a human types, what one agent says to another, and any other free-form text.
• ContextItems — typed model internals. Delivered through dedicated handlers: onFunctionCall, onFunctionCallOutput, onReasoning, onModelMessage (and their onExternal* counterparts).
• SemanticEvent<T> — provider-level stream chunks during inference (type + data). Delivered through onInternalEvent / onExternalEvent. See Streaming.

When a reactive agent decides to remember a message, it wraps it as a UserMessageItem (or DeveloperMessageItem / SystemMessageItem) and appends it to its ModelContext. From that point on, the message participates in inference like any other context item. Semantic events are usually handled for live UI or telemetry; completed model output still arrives as ContextItems when the stream finishes (or when streaming is off).

SemanticEvent

A SemanticEvent<T> is a typed wrapper around incremental provider output:

• type — the provider event name (for example response.output_text.delta).
• data — the payload for that event (T is provider-specific).

During streaming, inference yields SemanticEvent instances as they arrive and the environment forwards each one: the producing agent gets onInternalEvent(event), and every other participant gets onExternalEvent(source, event). That is the same self / external split as for ContextItems.

Semantic events are not part of ModelContext by default — they represent in-flight stream data. Persist or aggregate them in your handlers if you need a replay log; append ContextItems when you want the model to reason over completed turns.

ModelContext

A ModelContext is the ordered list of ContextItems a model is asked to reason over. It is constructed and mutated explicitly — typically inside a participant in response to delivered events.

import {
  ModelContext,
  DeveloperMessageItem,
  UserMessageItem,
  InMemoryModelContextRepository,
} from '@mozaik-ai/core';

const context = ModelContext.create('project-id')
  .addContextItem(DeveloperMessageItem.create('You are a helpful assistant.'))
  .addContextItem(UserMessageItem.create('What is the capital of France?'));

const repo = new InMemoryModelContextRepository();
await repo.save(context);

You:

• Create it with an id meaningful to your app (session, project, thread).
• Append items as messages, tool results, and model output flow through.
• Persist it through a ModelContextRepository so multi-turn flows, branching, and replay are easy.

ContextItem taxonomy

A ContextItem is one atomic piece of that history. Concrete item types are aligned with the OpenResponses vocabulary.

Client items (you produce these)

Model items (the model produces these)

Together, these items form an ordered transcript you can persist, trim, transform, or share across multiple participants.

How it fits with reactive agents

Participants and ModelContext cooperate but stay decoupled. A typical pattern:

1. A participant receives an event via one of its typed handlers — for example onMessage(message) or onFunctionCallOutput(item).
2. It appends the relevant context item to its own ModelContext (wrapping a string in UserMessageItem.create(message) when needed).
3. When it decides to call the model, it passes that context to runInference along with a ModelName.
4. Inference streams ReasoningItem / FunctionCallItem / ModelMessageItem back into the environment, where every other participant — and the agent itself, through its onReasoning / onFunctionCall / onModelMessage handlers — sees them.

The Reactive Agent page shows this end-to-end.

Persistence

A ModelContextRepository defines how contexts are stored and loaded. InMemoryModelContextRepository is shipped for tests and demos:

import { InMemoryModelContextRepository } from '@mozaik-ai/core';

const repo = new InMemoryModelContextRepository();
await repo.save(context);

Implement ModelContextRepository against Postgres, Redis, or object storage so you can save after each turn and load when a user returns.

Models and inference

A model is selected by its ModelName string. Mozaik resolves the name to a provider endpoint and a model specification internally, maps the ModelContext to that provider's API, and returns typed ContextItems (and SemanticEvents when streaming). Bundled model names:

You drive inference with the runInference capability; it streams the resulting items into the environment for participants to react to:

import { runInference, ModelContext } from '@mozaik-ai/core';

const context = ModelContext.create('demo');

runInference({ model: 'gpt-5.5', context, caller: this, environment });
// → environment delivers ReasoningItem | FunctionCallItem | ModelMessageItem (and SemanticEvent when streaming)

Around inference, Mozaik also exposes:

• Tool — declare callable capabilities for the model. See Capabilities & Tools.
• StructuredOutputFormat — constrain output to a JSON Schema. See Structured output.
• Token usage helpers: TokenUsage, InputTokenDetails, OutputTokenDetails.

Call sites stay typed end-to-end from tool declaration through inference. With streaming enabled, incremental provider events arrive as semantic events before full ContextItems are assembled.