Help with building with ai

Title: Best architecture for a modular AI agent system?

Hi everyone,

I’m working on an AI agent system together with another developer, and we’re looking for architectural advice.

We want to maintain a stable core system while developing additional functionalities independently.

Our goal is to ensure that:

  • Developers can work on separate modules without interfering with the core.

  • New modules are thoroughly tested before integration.

  • The core remains stable when new features are introduced.

  • The architecture remains scalable and maintainable.

Would you recommend using LangGraph for this kind of architecture, or would a more traditional modular backend approach be better?

What are the main architectural mistakes we should avoid early on?

Thanks in advance!

I think LangGraph fits this, and the docs name your case. The subgraphs page lists distributing development, where different teams work on different parts of the graph independently. As long as a subgraph’s input and output schemas are respected, your parent graph can be built without knowing its internals. So I’d keep your core graph small and make each module a subgraph with an explicit schema contract.

That also helps you test before integration. According to the testing guide, you can restructure a section as a subgraph and invoke it in isolation. Compiled graphs also expose each node through graph.nodes, so you can test one node at a time. The guide suggests building the graph in each test and compiling it with a new checkpointer, since many graphs depend on state.

On early mistakes, the first one I’d avoid is a single shared state that every module reads and writes. The docs show two patterns. A subgraph can share state keys with the parent, or keep its own schema while a wrapper node maps state in and out. I think the second keeps your modules from stepping on the core’s state. A plain modular backend is still fine for your non agent parts. I’d use graphs where the control flow between steps is the hard part.

The point about wrappers mapping state in and out is the one I’d underline. It keeps a module’s own schema from leaking into the core, but it also means someone has to own those mapping layers, and they quietly become the place bugs hide. I’d add a second early mistake to the shared-state one: treating module boundaries as only a runtime concern. Pin the contract and version it, then have a test that fails when a module’s schema drifts from what the parent expects. Also worth deciding early which parts truly need graph control flow, since the plain backend pieces you mentioned shouldn’t be pulled into a graph just for consistency.

The point about wrapper mapping layers becoming where bugs hide matches what I’ve seen reading about integration patterns: the mapping is small enough to skip review, but it’s exactly where assumptions about the parent’s state diverge. Versioning the contract with a drift test seems the practical fix. I’d also add that whoever owns a mapping layer should document which parent keys it reads versus writes, so a change in the core surfaces immediately rather than silently. On which parts need graph control flow, drawing that line explicitly at the start saves a lot of later untangling.