From Prompt Spaghetti to Bounded Contexts: DDD for Agentic Codebases

Hello dear colleagues, nice to meet you. My name is Nikita and I am an AI portfolio architect in Siemens, Germany, and today I would like to talk about building a JNTX system through the prism of domain-driven design. Let me start from the so-called JNTX system paradox. I believe many of you have probably seen it. For instance, you decide to build a JNTX coding system. Currently, you are in month one, you have three agents, rather clean prompts, everything works good, you are shipping new features, new functionality like crazy, everything looks amazing. But six months later, you have a mess of agents, more than 3,000 token prompts. When you change something, everything is broken, you have a long deployment cycle and you can hardly debug it. And all this is mainly not about your LLMs, not about your agents, it's a problem of the whole architecture.

Okay, let's see how does it happen. After six months, your prompt dramatically increased and around 85% of your prompt is about parsing logic, it's about integration. But instead of writing this integration as a code in the Python, where you can test, version it, make a type checks, or you just wrote it in plain English and just hope that LLM somehow can execute it and everything will be good. This is the prompt spaghetti and this is how most JNTX systems end up. And the main question today for our talk, for my talk, is how to build JNTX systems that can stay maintainable as they scale. And a small spoiler, the answer will be from 2003. This answer was given by Eric Evans. He showed how it works for microservices, but let's try to apply this for our agents.

Okay, let's go, let's look deeper. The main problem with building a JNTX system is that we are thinking we are building some kind of small helpful systems which are clearly integrated or communicate with each other. But the problem is that we are actually building a distributed system with services that talk to each other through the natural language without type safety, without explicit contracts, without clear boundaries, which means that at the end of the day, we are building some kind of microservice architecture, but neglecting all basic principles. And then we are just wondering why everything is breaking and why everything is not working. Okay, let's look at this comparison. We already have around 20 years of distributed system experience, and we know how to split boundaries, how to design APIs, contracts, and this perfectly works for microservices. But for JNTX systems, we have a totally opposite picture. We have a fuzzy responsibility, doing everything. We have a natural language as an interface, as an interaction, instead of clear APIs, we have a semantic guessing, and as a result, we have a lot of cascade failures and a lot of magic happening under the hood. The good news is that patterns that solve all these problems already exist. The name of this pattern is a domain-driven design, and also a good news that domain-driven design principles and approaches work even better for agents than it was for microservices. But let's have a closer look on the four core patterns, four core principles of domain-driven design, and how we can apply it for agents. The first one, as it's obvious, is a bounded context.

It's about clear responsibility. Here you can see a so-called anti-pattern of a guard agent when in case of designing a code writing system against a contract code writing system. This agent is responsible for code review, for quality, for security checks, for test coverage. As a result, we have more than 3000 plus tokens trying to solve all existing problems. What can we propose as an alternative, what is the best practice? Try to apply bounded context, try to split this mess into a separate context, for instance, quality context, security context, and so on. Each context is responsible for a separate task. Each context provides a separate artifact. For instance, quality context answers the question whether this code is well-crafted security, whether this code is secure enough, and as an artifact, each context provides a separate artifact, for instance, quality, some kind of quality reports, security reports, and CV checks, and risk levels, and as a result, we have a significant decrease of a complexity of our initial prompt from thousands of tokens to a measurable hundred of tokens. And as a first rule, as a first outcome, we have is try to apply bounded context, one agent is one bounded context, one responsibility.

The second pattern is a contract as a schema. The problem is that without contracts, agent's output is unstructured, and every agent which receives this output can parse it and interpret it in a different way. What can we propose as an alternative? Apply contracts, apply structurized schemas, and, for instance, treat it as a pedantic model. So, for instance, a pedantic model can represent your contract, which represents this integration between contexts, which help us explicitly define the expectation from an agent's output and shape it in a structured way. Also, can give us the opportunity of benefits of self-documenting, because schema is a document, it can be automatically validated by, for instance, pedantic, it can be versions explicitly, and we don't even need any parsing logic because of this structure from day one. That's why we have a second rule. We need to stop using natural language as our API. We should use structured schemas as our contracts.

But let's look how to make this contract's production ready. To do this, we have two patterns, so-called port and adapters of hexagonal architecture and CI gates. Ports will define what our agent needs. It's in a contract. Adapter just translates external system to our domain. And it means that agent does not know about external format, because adapter just absorbs this complexity. When something changes in external system, we just need to update our adapter and the domain still stay protected and staying safe. And since our contracts are standardized and structured, we can automate pre- and post-deployment checks, tests and validations around these contracts with the help of respective CI gates. So contracts define correctness and CI gates just enforce it. Okay, the third pattern, it's a so-called anti-corruption layer. We can consider, we can treat it as a semantic firewall. The main problem is that in different contexts, in different boundaries, the same term can have different meaning, different definition. For instance, for code generation contract, function is a signature plus implementation.

For testing context, it's just a behavior contract. So we see the same word with different meanings and without translation, we will have some kind of mess and chaos. The solution is an anti-corruption layer which can translate between boundaries. It can extract only necessary information from the respective contact which needs the other receiving contact. For instance, for testing, it's a function signature and expected behavior. And as a result, we have our domains clear and, for instance, if something happens, if something changes in a providing domain, we will receive just a respective error during the respective CI gateway check. We just need to change our adapter and both of domains will stay protected and stable. So as a result, we have the third rule. The anti-corruption layer is our semantic firewall. We just need to translate explicitly, fail loudly and protect our domains.

The fourth pattern is a context map. So context map makes our integration architecture explicit. So for instance, here you can see a context map for a gigantic coding system. So we can see code generation context on the top, test and context review and documentation in the middle and deployment on the bottom with the respective relations between contexts. But the key is it's not just a diagram, it's not just a picture, it's executable code. So we need to consider our context map as a configuration with the upstream, downstream system with defining what kind of relation, what kind of pattern should be used between contexts, what adapter, what the version of the contract. This can be validated during the initialization process. It can be used to generate documentation. At the end of the day, it will enforce our integration patterns. And as an outcome, here we have the next rule that context map is our integration architecture, not just a documentation. It should be a code that can run, validate and enforce our integration.

Okay, let's see how all these four patterns work together. So as a result, we have three separate bounded contexts with clean and focused responsibilities. Adapters translate between contexts. SCL, anti-corruption layer, protect domain clarity. CI gates used to validate contracts and check semantic consistency. Every call is traced. Context map coordinates all these relationships and each boundary, each context has its own ACL, CI gate and tracing. And just to look at the picture before and after. So before we have a hundred and thousand of tokens per agent and 85 percent of this of this prompt was mainly dedicated for integration, spaghetti for integration logic and engineers spent hours just for debugging.

And afterwards, we have some kind of measurable hundreds, 500 tokens per agent where around 90 percent of this prompt is dedicated to a domain logic and type error or integration error can be easily caught through the respective CI gate or CI checks.

Let's make a summary of the main key takeaways. First of all, when you're building an agent system, you should keep in mind that you are building a distributed system. So stop treating this system like a script. Architect them like services. Next, bounded context equals clear responsibility. One agent, one domain. Just stop building agents or guard objects.

The third outcome is a schema is your contract. Stop using natural language as your API. The fourth anti-corruption layer is your semantic firewall. You need to translate between boundaries. You need to protect with the help of ACL your domains. The fifth context map is the integration architecture. You need to treat it as an executable configuration which specify, which describe and explain the whole architecture of your agents. And the sixth, please use CI gates. Please lock and trace everything, which will give you the ability to debug and to see what is happening inside your system.

Okay, the next steps. What can you do? So, of course, it's a big pass. But if you do only one thing, just you can define the contract between two agents. You can make it as a pedantic schema and try to validate, try to embed this. Validating of this pedantic schema is a part of your CI pipeline. That's it. This is the start. Everything else follows us from the first boundary. So don't wait for a perfect design. Don't wait for a management approval. And just to encourage you, to inspire you, I will leave you with this phrase that the best time to start was six months ago. The second best time is Monday. You can even put yourself as an author of this phrase. And yeah, thanks a lot. Stay tuned and looking forward for your questions. Thank you.