I don’t remember the last time I had so much fun building something. The process felt less like writing software and more like assembling a cognitive entity — giving it personality, skills, memory, and the ability to learn and evolve.
At times it felt like Frankenstein — but instead of a monster, I was creating a team: the best Business Analysts, Product Owners, Project Managers, and Resource Managers, rolled into agents that never sleep, always learn, and are eager to help. It was magical, and honestly, humbling.
But then came the real challenge: how do you move beyond proofs of concept and demos, and integrate a multi-agent solution into a real production platform?
This article is the overview of how I approached that challenge in building Mezzoic’s Agent helper. It introduces the architecture I used, the problems I ran into, and the principles I found essential.
In this series, I dive deeper into each of those problem areas:
Together, these pieces are about one thing: turning multi-agent systems from fragile experiments into a real domain workforce inside your architecture.
Challenge: Keep the Architecture Simple
The magic of multi-agent systems is easy to capture in a demo. The hard part is making them work inside a real production system.
With Mezzoic, I started from a simple idea: if we already have a solid domain architecture with domain services, why not extend them into domain agents? Services represent bounded areas of expertise in the product, accounting, quoting, scheduling. Agents can be thought of as the experts that live inside those domains, capable of reasoning and acting just like the people on a project team.
That shift, from domain services → domain agents → domain workforce, became the foundation of the design.
But here’s the key: I didn’t want to rip up a working system just to experiment with agents. I wanted agents to act as extensions, not modifications, of the core. This is the idea of applying the Open/Closed Principle from SOLID design to your architecture:
Keep the platform closed to modification (stable, proven, secure).
Keep it open to extension (agents can plug in on top).
This is my golden rule of don’t break what’s already working.
The way to achieve that in practice is by wrapping existing APIs with MCP servers. MCP provides a protocol, much like REST, but tailored for agents. It turns APIs into discoverable, intent-driven tools that agents can actually use.
👉 I dive deeper into this in the article From APIs to Agent Tools, but at the overview level the principle is simple: Don’t redesign your backend for agents. Extend it with MCP.
Architecture Overview
Mezzoic mutli agent solution uses the agent swarm model for orchestration. Instead of a single supervisor agent delegating tasks, agents collaborate more fluidly, each equipped with the tools it needs to step in and act. This makes the system more resilient but it also means tool design must be clear to avoid collisions. Each agent is a domain expert, and in the Mezzoic context, that means there’s a dedicated Project Manger, Product Owner, Business Analyst and People Manager agent that you interact with.
The color coding is meant to differentiate between what’s new and what exists. Blues are new agent focused, purple are the MCP server extensions to your backend and Yellow are existing systems you’re leveraging.
👉 you can read some more about it in my in depth article, From APIs to Agent Tools
Challenge: Understanding and Managing Context
Context is everything.
The biggest challenge by far, is context, it is the new skill we have to master to make Agents and GenAI work. Context is the power and the achilles heel of agents. Get it right and your users will love the agent, get it wrong and they’ll get frustrated pretty quickly.
Context is what the model receives, instructions, tools, history, responses, it defines the agents personality, skills and reliability.
The challenge I faced were:
Running up against the token limit, LLMs limit the context window, and when the data you pull is content heavy, context fills up really quickly.
Producing effective prompts and descriptions
Creating easy to use tools that don’t require elaborate and hard to follow instructions.
Managing context so I give the agent enough context to be helpful and consistent.
The solution was to treat context as a first-class architectural concern. It wasn’t an afterthought; it became the core design problem.
What worked:
Summarization & focus → keep only what’s relevant, collapse old threads into summaries.
Specialized agents → each agent carries only the prompts and tools it needs, minimizing clutter.
Semantic & episodic memory → facts (preferences, roles) and experiences (what worked last time) stored outside the prompt, retrieved when needed.
Async/event-driven updates → keep the agent focused without drowning it in stale data.
Iterating on Prompts and tool descriptions until the LLM understood and could sucessfully accomplish the use cases we have.
👉 Read more in Deep Dive #2: Context Is Everything
Challenge: Security & Trust
The concern with adding agents is that they might bypass existing controls — giving users unintended powers or introducing a shadow security model.
Solution: leverage the existing API security model.
In Mezzoic, agents are simply extensions of existing domain services. That meant I could lean on the security model I already trusted. The APIs already implement Mezzoic’s governance and security requirements. and agent tools just wrap those APIs and can’t circumvent them.
Agents don’t need special powers; they need to respect the same policies as the rest of the system.
What worked:
OAuth OBO → agents act strictly on behalf of users.
Narrow scopes & short-lived tokens → tools stay limited and time-boxed.
Egress allow-lists → agents only reach approved MCP servers.
Auditability → every call is logged: who did what, when, via which tool.
👉 Read more in Deep Dive #3: Security & Trust
Extending Mezzoic with agents taught me three big lessons:
Keep the architecture simple (KISS) → agents should extend the system, not complicate or replace it.
Context is everything → the reliability and personality of agents depend more on context management than on the model itself.
Security & trust must be inherited → agents don’t need a new security model; they need to respect the one you already trust.
Those principles turned Mezzoic’s agents from fragile demos into a domain workforce: specialists that collaborate, stay within policy, and scale with the platform.
This article gave the overview. The real detail lives in the deep dives:
Together, these form a blueprint for moving beyond proofs of concept and into production-ready multi-agent systems.
