Intro: Building an AI Agent From Scratch

🇬🇧 English

🇫🇷 Français

“AI agent” has become one of those words that sounds more complicated than it is. We talk about agents that reason, remember, use tools – and somewhere along the way the whole thing starts to feel like magic happening inside a black box.

I wanted to open the box.

So this series does the one thing that actually demystifies agents: build it from scratch. No frameworks, no magic. Just plain Python, and one mechanism added at a time, until a bare loop grows into a real agent that can remember, reason, and use tools.

LangGraph, CrewAI, AutoGen – they all wrap the same small handful of mechanisms: a loop, a model call, some memory, a few tools and some advanced features. That’s it. And the best way to truly understand those pieces is to write them yourself.

So let’s write them ourselves.

One rule, and why it matters

Each stage lives in its own self-contained folder under agents/, and adds exactly one new mechanism on top of the last.

That single constraint is the whole pedagogy. When something finally clicks – or breaks – there is only ever one new thing it could be. You’ll always know exactly which moving part you’re looking at, because you just added it.

Every stage ships with a post like this one, explaining why the mechanism works the way it does – not just what the code does. Written assuming you have the code open in the other window.

Where this ends up

Start with a loop that does nothing but echo. End with an agent that has:

• short-term memory,
• tool use,
• knowledge tools (search and RAG),
• error handling,
• context management (compaction),
• subagents (multi-agent),
• evals.

That’s the exact feature set the big frameworks sell you – except you’ll have built every piece by hand. The final stage puts your home-grown agent side by side with LangGraph, CrewAI, and AutoGen, so you can finally see what those frameworks are actually doing under the hood. Spoiler: you’ll recognize all of it.

The roadmap

#	Stage	What it adds
001	The Echo Loop	The bare read-act-repeat loop, no LLM yet.
002	The LLM Call	The action becomes a single stateless LLM call.
003	Conversation History	Short-term memory: a messages list carried across turns.
004	The System Prompt	A configurable persona/instructions, separate from turns.
005	The First Tool	The model can request one tool; we run it.
006	Closing the Loop	The tool’s result loops back to the model for a final answer.
007	A Toolbox, Not a Tool	A real registry: the model chooses among several tools, or none.
008	Sturdiness Before Substance	Bad JSON, unknown tools, raised exceptions – handled, not fatal.
009	Giving the Agent Knowledge	The first tools with real guts: agentic search vs. RAG over a small vector store.
010	An Agent that Manages the Context	When the history no longer fits: summarize old turns, keep recent ones.
011	Subagent - An Agent as a Tool	Multi-agent, demystified: an agent as a tool, for context isolation.
012	Trust, but Verify	Logging thought-vs-action, plus a scripted eval harness.
013	The Capstone	Everything combined, plus a comparison against the big frameworks.

The full design rationale for each stage – why it’s scoped the way it is, what it tests, and how it connects to neighboring stages – lives in ROADMAP.md.

Start here

It begins where every agent begins, stripped of everything else: a loop. Agent-001 builds the loop that everything else extends – no model, no tools, just the heartbeat. See you there.