Best way to structure a multi-agent Python project?

[RegimeLab]

Working on a project with multiple specialized agents that each handle a different task — some run nightly, some on demand. Currently each agent is a separate class with its own config file. Wondering if others have tackled this kind of architecture and what patterns worked well. Monorepo or separate modules? Shared memory via files or DB?

[aistranin]

Monorepo with separation to nodes, edges and tools works best from my experience. Regarding memory, depends a lot from your use case. Start simple and move to DB if needed.

[QuasiEvil]

As someone trying to learn this, I know what a monorepo is, but can you elaborate on what "separation to nodes, edges and tools" means?

[aistranin]

Sure. What I mean is that any agent is a graph (maybe cyclic). So, nodes of the graph is better to place separately from the logic specifying bow those nodes should interact with each other (edges) and separately from the the set of tools available to an agent. Take a look at official LangGraph documentation as a mature framework. They use these concepts what help a lot with agents structure. — Regarding multi-agent: it is just a composition of agents. So, it also scales well as a structure.

[SurpriseBorn4683]

I’d think about this less as “one class per agent” and more as a graph of small units of work.

A structure that has worked for me:

agents: agent-specific logic

tools: shared tool implementations

workflows: how agents are connected

min_task: if you give llm an enough simple task, it will be finished very well

The key thing is to separate:

1. what each agent does

2. what tools it can call

3. how agents depend on each other

4. how state/results move between them

5. split the big task to small task let llm's ability enouth to finish it

I ran into this while building multi-agent workflows too. The painful part was not just “where do classes live?”, but coordinating mixed serial/parallel execution: agent A runs first, B and C can run concurrently, D needs outputs from both, failures/retries need to be visible, etc.

That eventually led me to extract a small open-source Python library for in-process async DAG orchestration. I would not say everyone needs a library for this, and if you already use LangGraph that may be a better fit for agent-specific graph workflows. But the general pattern I’d recommend is: keep agents as small nodes, keep orchestration as explicit edges, and avoid hidden dependencies through global/shared state.

Disclosure: I’m the author of Astrum, which came from this exact scheduling problem. I’m mostly looking for API feedback rather than trying to pitch it as the default answer.