Quickstart

This walkthrough mirrors the example in the Mozaik README: create an AgenticEnvironment, build participants from BaseParticipant, join them, and send a message. The agent does not need a separate "start inference" call — it reacts to events like any other participant.

Full example

import {
  AgenticEnvironment,
  BaseParticipant,
  ModelContext,
  UserMessageItem,
  runInference,
  sendMessage,
} from '@mozaik-ai/core';

const environment = new AgenticEnvironment();

const human = new BaseParticipant();

class Agent extends BaseParticipant {
  private readonly context = ModelContext.create('demo');

  async onMessage(message: string): Promise<void> {
    this.context.addContextItem(UserMessageItem.create(message));
    runInference({ model: 'gpt-5.5', context: this.context, caller: this, environment });
  }
}

const agent = new Agent();

human.join(environment);
agent.join(environment);

sendMessage(environment, 'Hello', human);

A participant reacts as soon as it join()s the environment. There is no separate bus to start — the environment fans every event out to every joined participant as it is produced.

What this is doing

1. AgenticEnvironment — An event bus for messages, ContextItems, and SemanticEvent<T> stream chunks. It fans every event out to every joined participant through the matching typed handler.
2. BaseParticipant — The base class every participant extends. Every handler is a no-op, so you override only the ones you care about. A "human" is just a participant that calls sendMessage; an "agent" is one that calls runInference.
3. sendMessage(environment, message, caller) — A capability function. Other participants receive the message via onMessage. It returns immediately; delivery and every downstream reaction happen in the background.
4. runInference({ ... }) — A capability function the agent calls from its handlers. It is fire-and-forget: it returns right away while the model runs.

How the agent reacts (non-blocking)

When the human calls sendMessage, the environment delivers onMessage(message) to every other participant. A reactive agent typically overrides that handler to record the message and call runInference:

async onMessage(message: string): Promise<void> {
  this.context.addContextItem(UserMessageItem.create(message));
  runInference({ model: 'gpt-5.5', context: this.context, caller: this, environment: this.environment });
}

runInference is non-blocking. The handler returns right away, so the agent can accept another onMessage, react to other participants, or handle unrelated events while the model is still running.

When inference finishes, the runner streams ContextItems back into the environment. The agent receives them through its own handlers — onFunctionCall, onReasoning, onModelMessage — where it can record context, execute tools, or run inference again. Other participants see the same items via onExternal* handlers.

That is the core idea: capabilities produce events; handlers react to events; nothing blocks the bus.

For the complete handler set (onFunctionCallOutput, context setup, joining), see the Reactive Agent page.

What you'll need

• A ModelContext the agent appends items to (ModelContext.create('demo')).
• A ModelName for runInference (for example 'gpt-5.5'). The provider is resolved from the model name; set the matching API key — see Installation.
• For human input, call sendMessage from your UI or I/O layer when the user acts.

The capability functions and Tool definitions are covered on the Capabilities & Tools page.