Agent Roadmap Kit: learn AI agents by building one, free
Understand agents by building one, for free
A reader of the agents series asked where they could try it themselves. The kit is the answer: six stops, each adding one working piece, that end in an assistant answering questions from your own notes, with tools, search by meaning, safety controls, tests and CI.
- What it is
- Open source software
- Role
- Author and maintainer
- Period
- 2026 to present (repository created September 2026)
- Status
- Active
- Licence
- MIT
- Topics
- AI agents
- Retrieval augmented generation
- AI education
- Software engineering
- Reproducibility
- Open source software
The problem
Reading about agents only gets you so far. The series explained tools, retrieval, safety, reliability and orchestration, but a reader could not run any of it, and the failures that teach the most only make sense when you watch them happen.
Why it mattered
The lessons in the series came from real systems, which cannot be handed to a stranger: they need private data, paid services and credentials. A reader needed the same lessons in a form that runs on a laptop, costs nothing, and still behaves like the real thing, including the ways it fails.
The context
The example is a small home kitchen in Soshanguve, Mama Dineo's Kitchen, whose notes include a menu, delivery rules, a private supplier note and a customer review with a planted instruction. Pointing the kit at a different folder turns it into an assistant for your own notes.
What I did
I designed the route and its constraints and built it with AI agents, the way the series describes: one stop per post, each adding one piece to the same assistant. A plain chat and templates; tools, an agent loop and an MCP server; search by meaning with the three retrieval bugs from the series reproduced on purpose; a policy file, a spending limit, human approval and an append only database as the one door that writes; a golden question set, regression tests and CI; and a fixed workflow beside the agent loop with a measured cost comparison.
What changed
The series went from an argument to something a reader can run in an afternoon. The kit also produced evidence the posts can point at: a small local model obeyed a planted instruction while the private data stayed out of its reach because the filter lives in code, a test run passed while the model claimed the kitchen sold pizza, and on the same questions the workflow used about three times fewer model calls than the agent loop.
Who benefited
Developers, students and practitioners who want to understand agents by building one, without a credit card, including readers in places where paid APIs are a real barrier.
What remained
A public repository under the MIT licence with a README per stop, real captured output including the bad runs, sixty seven tests that run offline with the mock, and CI on GitHub Actions.
Technical context
TypeScript run directly by Node 22, plain fetch to Gemini and Ollama, local MiniLM embeddings through Transformers.js, SQLite through node:sqlite, the Model Context Protocol SDK, node:test and GitHub Actions.
Lineage
- Came before
- The Practical Roadmap to Building With AI Agents. The six part series the kit accompanies. Each post ends with a Try it yourself section that points at its stop in the kit.
Related work
- Shares reproducibility, open source softwareUbunye Engine: portable Spark pipelines for data and MLUbunye Engine is an open source Python framework for config driven Spark pipelines. The same task folder runs on a laptop, Docker, Kubernetes or Databricks.
- Shares retrieval augmented generation, ai educationAI education: FabAcademic Unfiltered and Thabang AICo hosting FabAcademic Unfiltered with Prof. Mamokgethi Phakeng, public technical writing, and Thabang AI, a grounded assistant that cites its sources.
- Shares open source softwareTFiltersPy: Kalman and particle filters for PythonTFiltersPy is an open source Python library of Bayesian filters: Kalman, extended, unscented, ensemble and particle, behind one scikit-learn style API.
- Shares ai educationKasilam: teaching township youth to build with AIKasilam is a free community initiative in South African townships where young people learn to build with AI by shipping real sites for local businesses.
Related writing
- Shares retrieval augmented generation, software engineeringThe Practical Roadmap to Building With AI Agents, Part 3: Giving an Agent KnowledgeThe assistant on this site answers from my actual writing. Part three of six: RAG explained without the jargon, the chunking and search settings I actually use, and three retrieval bugs where the model was fine and the information was not.
- Shares open source softwareHow I Learned to Build My Own Python Libraries (From Curiosity to Real Work)creating from 1st principles
- Shares software engineering, ai agentsThe Practical Roadmap to Building With AI Agents, Part 1: From Chat to AgentMost people use AI like a vending machine. I used it like a senior engineer sitting next to me, and built this whole site that way without knowing Next.js. Part one of six: what actually separates a chat window from an agent, and how to start.
- Shares software engineering, ai agentsThe Practical Roadmap to Building With AI Agents, Part 2: Giving an Agent HandsAn agent that can only edit files makes you the courier between it and everything else. Tools and MCP fix that. Part two of six: what a tool actually is, what I connected, what it fixed in thirty seconds, and the permissions file I am not proud of.