DEV Community: Miodrag Vilotijević

Why Agent Frameworks End Up As SDK Wrappers - And How To Overcome It

Miodrag Vilotijević — Thu, 16 Apr 2026 07:48:43 +0000

Today, most frameworks for building AI agents are missing something fundamental. If you look closely at the language they use, you'll notice a pattern: their domain models are anemic. They give you abstractions like "agent", "tool", "step", but they don't actually model the thing that matters most - context. Because of that, developers are left on their own to deal with problems like:

context window overflow
context bloating
loss of structure across multiple model calls
messy handling of tool outputs and reasoning

And where does all of that logic end up? In your application layer.

The Hidden Cost: Polluting Your Domain

Instead of focusing on your actual domain (finance, healthcare, internal tooling, etc.), you start writing code like:

guessing what the model "needs to see" next
use your own way and schema to persist context
load context with schema which is not most efficient way to do it
and so on...

This is not your domain. It's not even context engineering. In the absence of the right abstractions, developers are pushed to reimplement core LLM concepts themselves - while mixing them with their own domain logic. And this is where complexity arises. We experienced these issues firsthand. That’s what pushed us to address them—so engineers like us can extract more from LLMs and open up new possibilities.

The goal with Mozaik is simple:

Enable developers to use a rich domain model for handling context in agentic applications.

So instead of letting LLM concerns leak into your domain, you can:

keep your domain logic isolated and aligned with best practices
use standardized building blocks to build your own context model
don't spend time reinventing the wheel
and hopefully, enjoy the process

At the same time, this is a space we're actively learning in. LLMs are still evolving, and we want to both learn and share what we discover while working on these problems.

Starting Point: OpenResponses

We didn't start from scratch.

Our starting point is the OpenResponses specification, published by companies like OpenAI, OpenRouter, Vercel and others in January this year. Their goal is to standardize how we work with LLM providers. They define a shared structure that reflects how models actually operate.

At its core:

Context is composed of context items.

These include:

Client-created items

user message
developer message
function call output

Model-generated items

reasoning
function call
model message

They also introduce an important idea:

Model-generated items are state machines that can be streamed with semantic events.

Those are the fundamental building blocks of the OpenResponses specification and how major LLM providers implement them. For a deeper dive, you can check: https://www.openresponses.org/

Our Take on This

OpenResponses gives us the source of truth for how LLMs work today. These building blocks should not be ignored. But the specification itself is not enough. Developers still need a way to work with it in practice.

Enter Mozaik

Our approach is to take this specification and turn it into a rich object domain model. The goal is not to abstract everything away, but to:

make context explicit
make it composable
make it persistent
make it evolvable across multiple steps

With our base implementation, developers can:

build structured context from typed items
manage model-generated items (reasoning, function calls, outputs)
persist context
restore it and continue execution

All without leaking context engineering concerns into their core domain logic.

Where This Leads

We see this as a starting point.

By introducing a richer domain model for context, new opportunities open up:

better strategies for context compression
smarter handling of long-running interactions
clearer debugging and observability
more predictable and controllable multi-agent systems

Basic Example

Here's a minimal example of building and storing context using Mozaik:

const contextRepository = new InMemoryContextRepository()

const message = UserMessage.create("Tell me a joke about birds")
const developerMessage = DeveloperMessage.create(
  "You are a joke teller. You will be given a joke and you will need to tell it to the user.",
)

const projectId = `pr-${crypto.randomUUID()}`

const context = Context.create(projectId)
  .addItem(developerMessage)
  .addItem(message)

await contextRepository.save(context)

const model = new GPT54Model()
const generatedItems = await model.call(context)
context.addItems(generatedItems)
await contextRepository.save(context)

const restoredContexts = await contextRepository.getByProjectId(projectId)
console.log(restoredContexts)

This uses an in-memory repository, but in real applications you can plug in your own persistence layer.

You can find more working examples in the GitHub repository:

github.com/jigjoy-ai/mozaik-examples

Final Thought

The industry is moving fast. But if we keep ignoring context as a core primitive, we'll keep rebuilding the same fragile systems. Mozaik is our attempt to fix that - by giving context the place it actually deserves. And this is just the beginning. We're excited to see where this journey takes us.

If you like what we’re building, give Mozaik a ⭐ on GitHub.

jigjoy-ai / mozaik

Mozaik is a TypeScript library for building, managing, and evolving LLM context.

Mozaik

Mozaik is a TypeScript library for building, managing, and evolving LLM context.

Instead of focusing on agents themselves, Mozaik provides a structured way to model, manipulate, persist, and restore the context that drives language model behavior. It implements a clean object model aligned with the OpenResponses specification, enabling developers to work with LLM inputs and outputs as composable, typed entities.

With Mozaik, you can:

Structure interactions as ordered context items (messages, reasoning steps, function calls, etc.)
Append and evolve context across multiple model calls
Persist and reload context from storage
Manage context size and avoid overflow
Build complex workflows through context composition, not ad-hoc prompt strings

Mozaik treats context as a first-class primitive, making it easier to design scalable, maintainable, and provider-agnostic LLM applications.

📦 Installation

yarn add @mozaik-ai/core

API Key Configuration

Make sure to set your API keys in a .env file at the…

View on GitHub

With this MCP, Notion is becoming a vibe-coding platform turning its pages into applications. Its two-way binding enables users to generate applications and store data in Notion databases, with Notion acting as the backend for collecting and fetching data.

Miodrag Vilotijević — Wed, 25 Mar 2026 16:04:31 +0000

Notion MCP Challenge Submission 🧠

Miodrag Todorovic

Mar 25

Vizion: Vibe-coding without leaving Notion. Write it in Notion. Click a button. Get a live React app — with two-way sync.

#devchallenge #notionchallenge #mcp #ai

Comments

3 min read

From Monolith to Microservices: How Bounded Context Improves AI-Driven Development

Miodrag Vilotijević — Fri, 20 Mar 2026 17:44:03 +0000

Introduction

When we first launched our vibe coding platform, the architecture started as a single monolithic application. Initially this approach allowed us to move quickly and ship features fast.

But as the platform grew, the warning signs appeared.

The codebase became increasingly complex, new features were harder to implement, and development velocity began to slow down. What once felt manageable started to evolve into a tightly coupled system that was difficult to reason about.

To solve this, we made a strategic decision: refactor the platform from a monolith into a microservices architecture.

In this article we explain:

Why monolithic architectures struggle in AI-driven systems
How Domain-Driven Design (DDD) helps define system boundaries
Why bounded contexts are critical for AI agents
How we split our platform into eight microservices

This architectural shift significantly improved both developer productivity and AI agent performance.

Understanding Domain-Driven Design

The concept of Domain-Driven Design (DDD) was introduced by Eric Evans in the influential book Domain‑Driven Design: Tackling Complexity in the Heart of Software.

Although the book was published in 2003, its ideas remain extremely relevant today. Many modern architectural patterns—including microservices—are heavily inspired by DDD principles.

DDD focuses on one core idea:

Software architecture should mirror the structure of the business domain. Instead of organizing systems purely around technical layers, DDD encourages teams to structure software around real business capabilities and concepts.

While doing domain distillation, we detected the 6 main bounded contexts that can act as independent services: project planning, AI coding, project deployment, version control, observability, account and billing.

The Monolith vs Microservices Debate

For years developers have debated a fundamental architectural question:

Should applications remain monolithic, or should they be broken into microservices?

Monoliths have advantages:

Simpler deployments
Easier early development
Fewer distributed systems challenges

However, as systems scale, monoliths often become harder to maintain. Large codebases accumulate complexity and eventually turn into what developers often call a "Big Ball of Mud."

Today the conversation has evolved even further. We are no longer building systems only for human developers. We are building systems that AI agents interact with, modify, and reason about. And this introduces a new challenge.

Why Monolithic Architectures Confuse AI Agents

AI agents rely heavily on clear context boundaries.When a system grows into a large monolithic repository:

Domain concepts overlap
Terminology becomes ambiguous
Architectural boundaries blur

This makes it harder for AI systems to correctly interpret intent. For example, an AI agent might receive a command such as:

Create a project.

In a large monolith, the term project might refer to several different things:

A planning workspace
A source code repository
A deployment environment

Without clear boundaries, the AI agent must guess the meaning. And guessing leads to errors. This is why architectural clarity matters even more in AI-driven development environments.

What Is a Bounded Context?

A Bounded Context is a central concept in Domain-Driven Design. It defines a clear boundary within which a specific domain model applies and terminology has a single meaning.

Inside a bounded context:

Language is consistent
Concepts are clearly defined
Domain logic belongs only to that context

This creates a shared understanding between:

Developers
Domain experts
AI agents

Each context effectively becomes its own mini-world with well-defined rules.

Why Bounded Contexts Improve AI Development

In large software systems, the same word can mean different things in different domains. While building our AI coding platform, we encountered this problem quickly. Consider the word project.

When both meanings existed in the same codebase, confusion spread. Not only for engineers—but for AI agents operating within the platform. By introducing bounded contexts, we ensured that each domain defines its own terminology and behavior. This dramatically improved the reliability of both human workflows and AI-generated development tasks.

Our Microservices Architecture

After refactoring the platform using Domain-Driven Design principles, we divided the system into eight bounded contexts, each implemented as a separate microservice.

This allowed each domain to evolve independently while maintaining clear system boundaries.

Project Planning Context - manages planning activities. Within this domain we store: tasks, projects, agent which generate tasks...
AI Coding Context - this is where development actually happens. AI coding agents operate in this domain and perform tasks such as: writing code, committing changes, managing development workflows.
Project Deployment Context - manages the infrastructure and pipelines required to deploy software built by AI agents.
Version Control Context - while platforms like GitHub provide robust version control, we chose to build a lightweight internal system optimized specifically for AI-driven development workflows.
Observability Context - collects events and analytics from across the platform.
Account and Billing Context - manages user accounts, platform credits, payments.
API Gateway - acts as the central entry point into the platform.
Platform UI - provides the user interface that connects all services together.

Avoiding the Big Ball of Mud

Without clear architectural boundaries, complex systems eventually degrade into tightly coupled codebases that are difficult to maintain. Developers often describe this situation as a "Big Ball of Mud."

Symptoms typically include:

Spaghetti code
Increasing bugs
Slower development cycles
Poor onboarding experience
Confusing system behavior

For AI-driven platforms, the consequences are even worse because agents lose the contextual clarity required to generate reliable code.

By organizing our platform around bounded contexts and microservices, we achieved several key benefits:

Clear domain ownership
Faster feature development
Better system scalability
Improved AI agent performance
More maintainable architecture

Final Thoughts

As AI agents become increasingly involved in software development, architecture design must evolve alongside them. Bounded contexts and microservices are no longer just about scaling engineering teams—they also help AI systems reason about complex software platforms. For us, adopting Domain-Driven Design and microservices architecture transformed a growing monolith into a scalable platform designed for the future of AI-assisted development.

Multiple models are in play on any large project. Yet when code based on distinct models is combined, software becomes buggy, unreliable, and difficult to understand.

— Eric Evans

Why a Single Interface for Multiple LLM Providers Is a Bad Design Decision

Miodrag Vilotijević — Thu, 19 Mar 2026 06:29:02 +0000

Don't write frameworks for dummies.

That sentence stuck with me while reading Domain-Driven Design: Tackling Complexity in the Heart of Software. I didn't fully understand it at first - but after building (and then redesigning) an AI orchestration framework, I do now.

Where We Started

When we began building a framework for orchestrating AI agents, one of the first features we introduced was a unified request interface across multiple LLM providers.

At first, it felt like a great design decision.

One interface.
Multiple providers.
Clean abstraction.
Simple.

But that simplicity turned out to be misleading.

The Problem with "Unified" Abstractions

Over time, cracks started to show:

All models looked the same to developers

By flattening everything into a single interface, we erased the differences between models. Developers stopped thinking about capabilities and limitations - which is exactly what they should be thinking about.

Adding new models became harder, not easier

New models come with new capabilities, parameters, and behaviors. A "unified" interface either ignores those features, or becomes bloated trying to support everything. Neither is good design.

The ubiquitous language was wrong

The API didn't reflect the domain. It reflected our attempt to simplify it. That meant the language of the library didn't express real model capabilities.

We enabled misuse by design

The worst part: the abstraction allowed developers to make mistakes easily - and only discover them at runtime.

For example:

passing reasoning_effort="high" to a model that doesn't support reasoning.

The system didn't prevent it. It allowed it.

That's not just a bad developer experience - it's a failure in design. The abstraction wasn't helping developers. It was hiding the truth.

The Redesign

So we changed direction.

Instead of forcing a unified interface, we started modeling each LLM separately, along with its capabilities and constraints.

Why This Is the Right Move

Advanced users can extract more value

Power users are no longer limited by a lowest-common-denominator API.

Models are not the same - and that matters

Treating them as identical leads to misuse. Embracing differences leads to better outcomes.

Invalid configurations are caught early

Instead of runtime surprises, errors are surfaced immediately.

Better developer experience (DX)

Clear APIs, explicit capabilities, fewer hidden assumptions.

Most importantly: the library expresses domain knowledge correctly
The design now reflects reality - not an oversimplified version of it.

Looking Forward

We're not done yet.

We haven't fully committed the redesign - but we've started moving in this direction, and the changes will roll out in the next versions of Mozaik.

The goal is simple:

make model capabilities explicit
prevent invalid usage early
and let developers actually use the power of each model instead of hiding it

This is still evolving, and we'll likely learn more (and fix more mistakes) along the way.

But one thing is already clear:

We're no longer trying to hide the complexity of LLMs. We're designing for it.

Source:

Why a Single Interface for Multiple LLM Providers Is a Bad Design Decision

Why unified LLM abstractions fail and how modeling each LLM separately improves developer experience. A lesson in Domain-Driven Design.

jigjoy.ai

How to Build an Autonomous AI Agent That Executes Terminal Commands

Miodrag Vilotijević — Sun, 15 Mar 2026 18:54:33 +0000

What Makes an Agent Autonomous?

An autonomous agent is an agent that can make independent decisions to accomplish tasks-without constant human guidance.

But how do we measure the level of autonomy an agent has?

The answer lies in the variety of tasks an agent can perform on its own.

Consider an agent that has a single tool-the ability to write files. That's one degree of autonomy. It can create content, save it, and that's about it.

Now consider an agent with access to a terminal. Suddenly, the possibilities explode:

List files in any directory
Read and write files
Execute scripts and programs
Install packages
Interact with git repositories
Make network requests
And much more...

This is a high degree of autonomy-which, as we'll discuss, comes with both incredible power and important security considerations.

This is basically the idea behind modern coding tools like Claude Code—or even better, OpenClaw.

The Core Concept: Tool Execution Loop

The main thing we need to enable is an implementation for executing tools in a loop.

I'll use a library I built for this- @mozaik-ai/core - a TypeScript framework for orchestrating AI agents.

With Mozaik, we can easily equip an agent with tools. So we just need to create a terminal tool for executing commands.

Creating the Terminal Tool

First, let's define the terminal class that will give our agent the ability to execute shell commands:

import { spawn } from "child_process"

export class Terminal {

    runCommand(command: string, cwd: string): Promise<CommandResult> {
        return new Promise((resolve) => {
            const [cmd, ...args] = command.split(" ")
            const process = spawn(cmd, args, { cwd, shell: true })

            let stdout = "", stderr = ""

            process.stdout?.on("data", (data) => stdout += data.toString())
            process.stderr?.on("data", (data) => stderr += data.toString())

            process.on("close", (code) => {
                resolve({
                    success: code === 0,
                    stdout: stdout.trim(),
                    stderr: stderr.trim(),
                    exitCode: code ?? -1,
                })
            })
        })
    }
}

Now we define the tool that will give our agent the ability to execute shell commands:

The tool is straightforward: it takes a command string, executes it using Node.js's child_process module, and returns the output.

const terminal = new Terminal()
const tools: Tool[] = [
    {
        name: "run_command",
        description: "Run a command in the terminal.",
        schema: {
            type: "object",
            properties: {
                command: { type: "string", description: "The command to run in the terminal." },
                cwd: { type: "string", description: "The current working directory." },
            },
            required: ["command", "cwd"],
        },
        async invoke({ command, cwd }) {
            console.log(`Running command: ${command} in directory: ${cwd}`)
            console.log("--------------------------------")
            const result = await terminal.runCommand(command, cwd)
            return result
        },
    },
]

Attaching the Tool to an Agent

Now we attach the terminal tool to our agent:


agent.ts
const request: MozaikRequest = {
    model: "gpt-5-mini",
    tools: tools,
}
const userRequest = `Analyze the github respository and update the README.md file with a high level description of the project.`

const task = `You are a terminal agent. 

You can run commands in the terminal to help the user with their request. 
Do not ask any questions to the user. Just run the commands and return the result.

Tools:
- run_command: Run a command in the terminal. You can use this tool to run any command in the terminal.

User Request:
- ${userRequest}
`

const agent = new MozaikAgent(request)
const result = await agent.act(task)

Watching the Agent Work

Let's give the agent a task and watch it work. Below you can see what happens step by step - the terminal commands the agent autonomously executes to get the job done.

const userRequest = `Look at this folder and tell me in one sentence what it does 
                    — like you're explaining it to someone who has never written a line of code.`

The agent breaks it down on its own. It runs two commands to get the job done. The first command lists the files in the current directory, and the second command reads README.md to figure out the purpose of the project.

We can see which commands the agent executed to get the job done. No instructions on how to do it. Just the goal—and the agent figures out the rest.

Now, let's give the agent a more complex task:

const userRequest = `Analyze this directory and write 
                    a detailed description of the project 
                    in a file called purpose.md.`

We see the agent executed multiple commands to get the job done, and finally wrote the purpose.md file with the description of the project.

Security Considerations

With great autonomy comes great responsibility. Terminal access is powerful—but it can also be dangerous if not properly controlled.

The balance between autonomy and safety is a spectrum. Start with tighter controls and expand as you build confidence in your agent's behavior.

Final Thoughts

Building an autonomous agent with terminal access is surprisingly straightforward—the core pattern is just a tool execution loop.

What makes these agents powerful isn't the complexity of the implementation, but the emergent capabilities that arise from giving an LLM access to a shell.

The agent doesn't need to be explicitly programmed for every scenario. Give it a goal, give it tools, and it will find a way.

GitHub Repo:

jigjoy-ai / terminal-agent

A minimal AI-powered terminal agent that can execute shell commands and interact with the local system to automate tasks and workflows.

@mozaik-ai/terminal

A small terminal-agent project that lets an AI act as a terminal operator. It exposes a tool for running shell commands programmatically and returning structured results (stdout, stderr, exit code). The agent is built on top of Mozaik AI core primitives and is intended for automation tasks where an AI needs to inspect the repository, run commands, and modify files.

Key points

Project name: @mozaik-ai/terminal
Purpose: Provide a terminal tool that an AI agent can use to run commands in a shell and capture results.
Language: TypeScript (Node.js)
Entry point: src/index.ts

Features

Run arbitrary shell commands via a typed tool (run_command)
Captures stdout, stderr, and exit code
Simple Terminal class that spawns child processes and returns CommandResult objects

How it works (high level)

src/index.ts wires up a MozaikAgent with a single tool: run_command
The tool schema requires { command, cwd } and invokes Terminal.runCommand
Terminal.runCommand uses child_process.spawn (with shell…

View on GitHub

Source:

Building an Autonomous Agent That Can Run Terminal Commands

Learn how to build an autonomous AI agent with terminal access. Discover how tool-equipped agents can execute shell commands and accomplish complex tasks.

jigjoy.ai