Reactive Agents, Typed Event Handlers, and Agent Swarms: What's New in Mozaik

When we released Mozaik 3.0, we introduced an event-based architecture where participants emit, observe, and react to typed context items inside a shared agentic environment. Since then, the framework has kept moving - and the way we think and talk about it has moved with it.

This post is a tour of what's new. The headline shift is conceptual: Mozaik is now framed around reactive agents - collaborative agents that adapt to their environment and to each other in real time. Underneath that frame, the API has gotten smaller, clearer, and easier to read.

From Non-Blocking to Reactive

Mozaik agents have always been non-blocking. That's still true - capability methods stream events as they're produced, so a slow inference or tool call never holds up other participants. But "non-blocking" describes a property, not a way of thinking.

The way we now think about Mozaik agents is reactive: an agent declares which events it cares about and reacts to them as they arrive - messages from humans, function calls from its own model, reasoning traces from a peer agent, or tool outputs from somewhere else in the environment. Behavior emerges from how agents react, not from a central controller deciding whose turn it is.

A reactive agent is event-driven, collaborative, and adapts to its environment and to other agents in real time.

This shift in framing pays off in design. Once an agent is a thing that reacts, adding behavior to a system stops being about editing a pipeline and becomes about joining another participant.

Typed Event Handlers

The biggest API change since 3.0 is on the participant side. In the original release, a participant exposed a single intercept point: onContextItem(source, item). You looked at the item, decided whether it came from you or someone else, and branched accordingly.

That worked, but it pushed a lot of dispatch logic into every agent. So we replaced the single intercept with a set of typed handlers, one per event kind:

• onMessage
• onFunctionCall
• onFunctionCallOutput
• onReasoning
• onModelMessage

Each handler defaults to a no-op in the base class, so a reactive agent only writes the ones it actually cares about. The result is shorter, more declarative code - a reactive agent reads like a list of "when this happens, I do that," not like a switch statement.

Here is a full reactive agent built on top of BaseAgentParticipant. It records incoming messages, runs inference, executes its own tool calls, and keeps its local context in sync with what the model produces - all by overriding the handlers it cares about:

The Self vs. External Split

For every typed handler, there are two variants: a self handler that fires when this participant emits the event, and an external handler (prefixed with onExternal) that fires when another participant emits it.

• onFunctionCall / onExternalFunctionCall
• onFunctionCallOutput / onExternalFunctionCallOutput
• onReasoning / onExternalReasoning
• onModelMessage / onExternalModelMessage

The practical effect: a reactive agent can encode "act on my own outputs" separately from "observe others" - no more manual source === this checks. Want to build a critic that reviews a peer agent's answers? Override onExternalModelMessage. Want to feed your model's own tool calls back into a runner? Override onFunctionCall. The two concerns stop bleeding into each other.

As a concrete example, here is a passive participant that only listens to external events. It does not run inference and does not execute tools - it just watches what other participants emit and logs it. Drop it into any environment and you have a live transcript:

Plain Messages on the Bus

Conversational text used to flow through the same context-item pipeline as everything else. It worked, but it was heavier than it needed to be. Now there are two clean lanes:

• Messages - plain strings, delivered via 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 (function calls, function call outputs, reasoning items, model messages), delivered via their dedicated handlers.

The participant side mirrors this: the old InputItemSource has become InputStream, an async iterable of strings. Each yielded string fans out via onMessage to every other participant. Inference and tool runners still produce typed ContextItems, exactly as before.

The benefit is mostly clarity. When you read a reactive agent now, you can tell at a glance whether a handler is reacting to "someone said something" or to "the model produced a tool call."

A Bigger Model Lineup

The default OpenAI provider now ships a wider model lineup. In addition to Gpt54, Gpt54Mini, and Gpt54Nano, there is now Gpt55. Same OpenAIResponses runtime, same OpenResponses-aligned types - pick the model that fits the job.

From One Agent to a Swarm

The reactive frame really earns its keep when more than one agent shares an environment. We've started calling these collaborative groups agent swarms: a handful of focused reactive agents - planner, executors, reviewer, and observers - all joining one AgenticEnvironment and reacting to each other's events.

The clearest production example is baro, a Claude agent orchestrator built on Mozaik. Ten specialized participants - planner, executors, reviewer, fixer, librarian, auditor, and more - work fully concurrently on the same goal, like a team collaborating in real time instead of a single agent doing everything alone.

Adding a new role to a swarm doesn't mean editing a central controller. It means writing one more reactive agent and join()ing it to the environment. Everything else keeps working.

Composing Intelligence

Each of these changes is small on its own. Together, they shift Mozaik further toward what we wanted from the start: a framework where intelligent behavior is something you compose, not something you orchestrate.

Reactive agents make the building block explicit. Typed handlers make each agent easier to read. The self vs. external split keeps intent obvious. Plain messages keep the conversational lane clean. And the swarm pattern shows what falls out the other side: groups of agents that adapt to their environment and to each other in real time.

Miodrag Vilotijević

Co-founder @ JigJoy

Building the future of agentic systems