Ready to see what I’ve been building? 👀
Many of you have told me you like how I structure my projects with good software practices.
But I know it’s not always easy to extract that structure, since most of my projects are pretty specific.
A cookiecutter designed to build Agent APIs in a structured and robust way from the very beginning.
None of my agentic systems live in isolation. If you check my projects, you can easily notice that they always connect to the world through an API.
And since that’s exactly what happens in production systems … it felt the perfect place to start!
I also put together a video (see above 👆) to make everything clearer.
Let’s begin!
First steps
⭐ Check out the cookiecutter repo … and don’t forget to drop a star if you haven’t yet!
The first thing you need to do is to to install the cookiecutter library.
pip install -U cookiecutterNext, you can use the cookiecutter to spin up a new project:
cookiecutter https://github.com/neural-maze/agent-api-cookiecutter.gitAfter this, you’ll be asked to fill in a few details about your project … and that’s it!
Understanding the structure
The structure might look a little intimidating at first (especially if you’re just starting out), but don’t worry. Once you dive in, it all makes sense.
At the project root, you’ll find some common files I use across all my projects, like:
Dockerfile / docker-compose for containerization
A comprehensive README (seriously, invest time here!)
A Makefile with commands to build, start, and stop the app
pyproject.toml (this template assumes you’re using
uv)data/ for datasets and documents your app needs
notebooks/ for explanations, experiments, and prototypes
static/ for images, GIFs, and videos
tests/ for—you guessed it—tests
But here’s the truth:
The real magic happens in the src/ folder.
That’s where all your application logic lives.
And if you peek inside, you’ll see the structure isn’t random.
It follows a Clean Architecture approach.
In particular, we have three main layers:
Domain Layer
This is the heart of your system. The place where you define core entities and logic.
Examples are:
Base classes for agents
Prompts (as plain strings)
Tools (as raw Python functions)
Utility functions.
…
⚠️ Keep this layer framework-agnostic. No references to specific agent libraries or databases here! Just pure logic.
Application Layer
Here’s where we define what the system does. Its use cases.
In the cookiecutter, you’ll see some placeholders to give you ideas on how to structure your own:
A chat service, that generates a response to a user query
An evaluation service, that scores or validates responses
A service for document ingestion (and indexing), if you’re implementing a RAG system
A service for resetting the memory of your Agentic System
…
Infrastructure Layer
Finally, we have the integrations. The “plumbing” of your system.
This is where you’ll connect to the outside world:
API (I included a starter implementation)
Databases
Monitoring tools
LLM provider clients
MCP Clients
…
The beauty of this setup?
You can swap MongoDB for Qdrant or OpenAI for Claude, and everything still works—seamlessly.
Why?
Because your Domain and Application layers don’t care about the specific infrastructure. They’re built to be independent, and that flexibility makes scaling or changing tech a lot easier.
Next Steps
Now that the cookiecutter’s public, I’m kicking off a series of example builds.
I’ll take the template and layer in custom code to turn it into a RAG Chatbot, a Realtime Agent, or a reasoning Multi-Agent System.
Which one should I build first?
Drop your pick (and any thoughts) in the comments!
