Maki is an open-source Python framework for building applications where several LLM agents work together. An agent is a model with a role, instructions and, optionally, tools it can call. Maki gives you the plumbing: it talks to the model, runs the tools, keeps the loop going and puts guardrails around what a tool may do.
It is MIT licensed, and it is what runs the pipeline behind this newsletter. In this course you will not use that pipeline. You will build a small, public one of your own.
What you will build
Scout is a research assistant. Given a topic, it finds a story on Hacker News, reads the page and writes a three-sentence brief. You build it in four steps:
- This chapter: check your machine is ready.
- Install Maki and run your first agent.
- Give your agent a tool so it can search.
- Build a two-step pipeline where plain code and two agents each do one job.
Scout runs on a model on your own computer, through Ollama. You need no account and no API key, and nothing you type leaves your machine except the web requests Scout makes on purpose.
When to use Maki, and when not to
Maki is a good fit when:
- you want your agents to run on local models first, and keep the option of moving one task to a hosted model later by swapping one object;
- you want several agents, each with its own role and tools, rather than one long prompt;
- you want tool access that is restricted by default. File writes and other risky actions are off until you switch them on.
Maki is probably not the right choice when:
- you only need one model call. The model provider's own library is simpler;
- you need a large ecosystem of ready-made integrations.
What you need
| Thing | Why |
|---|---|
| Python 3.10 or newer | Maki's minimum |
| Ollama | Runs the model on your machine. llama.cpp and vLLM work too, see chapter 2 |
The model qwen3.5:4b |
3.4 GB on disk. Pull it before you start, because the download is the slowest step |
| Some time | The model download is the slow part; the chapters themselves are short |
Small models make mistakes. They misspell names, miss details and sometimes get a fact wrong. Scout always prints its source link, so you can check any brief against the page. If your computer has plenty of memory, gemma4:26b (17 GB on disk) gives better answers; change MODEL at the top of a script to try it.
Check your setup
Make a folder, create a virtual environment and install Maki. The package is called maki-framework; the name maki on PyPI is a different project.
python -m venv .venv
source .venv/bin/activate
pip install maki-framework
ollama pull qwen3.5:4b
The course code is a small public repository, BowlOfData/maki-learning, with one folder per chapter. Clone it first:
git clone https://github.com/BowlOfData/maki-learning.git
cd maki-learning
In ch01_setup is a script that checks the three things that most often go wrong: Maki installed, Ollama running, and the model pulled.
python ch01_setup/check_setup.py
A ready machine prints three lines that start with ok. Any line that starts with FIX tells you what to do next. When all three say ok, go on to your first agent.