agents-from-scratch: a twelve-lesson agent built on one local GGUF model
Build AI agents from first principles using a local LLM - no frameworks, no cloud APIs, no hidden reasoning.
At a glance
- What is it?
- pguso/agents-from-scratch teaches agent construction by growing a single Agent class across twelve lessons, with no framework and no cloud API. The teaching sequence is the product; the code is a reference implementation, not a library.
- Who is it for?
- Adopt it if you write Python, already run a GGUF model locally, and want to see routing, tools, memory and planning expressed as ordinary code you can edit line by line. Skip it if you need a deployed agent this quarter, a supported library with versioned releases, or a cloud model behind an API key.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 52 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap this repository is aimed at
Most agent tutorials start with a framework import and end with a working demo. The reader can run the result but cannot say which part decided to call a tool, which part remembered the previous turn, or where a malformed model response would surface. This repository takes the opposite route. Its stated audience is developers who can code but feel lost with agents, people tired of being told to just use LangChain, and educators who want a clean mental model. The README is explicit about the boundary: it is not for anyone who wants the fastest demo, a SaaS starter kit, or hidden chain-of-thought. The philosophy section compresses the argument into one line, that agents are loops, state and constraints rather than personalities. Everything in the repository follows from that claim. If you accept it, the twelve lessons are a reasonable curriculum. If you wanted a component you can drop into an existing service, this is the wrong repository and the README says so.
One Agent class, twelve increments
The organising decision is that agent/agent.py is the same file throughout. Lesson 01 is text in, text out. Lesson 02 adds a system prompt. Lesson 03 introduces JSON contracts for structured output. Lesson 04 adds routing logic so the agent can choose a branch. Lesson 05 adds tools, Lesson 06 the observe, decide, act loop, Lesson 07 memory, Lesson 08 planning, Lesson 09 atomic actions, Lesson 10 the Atom of Thought dependency graph, Lesson 11 evals and Lesson 12 telemetry. Each stage modifies the class rather than introducing a new abstraction, so the diff between two lessons is the concept being taught. The README warns against skipping ahead and groups the sequence into foundation (1 to 3), agency (4 to 6), intelligence (7 to 10) and observability (11 to 12). That grouping is the honest description of the dependency structure. A reader who jumps to Lesson 10 without the routing and tool lessons has no agent to attach a dependency graph to.
What runs, and what you have to supply
Setup is three steps according to the README: pip install -r requirements.txt, download a GGUF model into the models/ folder, then run python complete_example.py. QUICKSTART.md holds the detailed version. The model is not vendored, so the repository is inert until you supply a GGUF file, and the choice of model is left to you. complete_example.py contains twelve functions, one per lesson, each demonstrating that lesson's concepts in isolation, which lets you run a single idea without assembling the full agent. The supporting modules are split by concern: agent/memory.py for the memory system, agent/planner.py for planning and atomic actions, agent/state.py for state management, agent/tools.py for tool definitions, agent/evals.py for the Lesson 11 evaluation framework and agent/telemetry.py for Lesson 12 structured logging. shared/ holds the LLM wrapper, prompt helpers and utilities. evals/golden_datasets.py holds the known-good test cases the evaluation framework runs against. The absence of a packaging file is consistent with the intent: this is a directory you clone and read, not a dependency you pin.
Structure over prompting, and what that costs
The fourth core principle states that reliability comes from constraints rather than clever wording, and Lesson 03 is where that becomes concrete: the model is asked to emit JSON under a contract, and the surrounding Python decides what to do with the parsed result. Lesson 08 extends the same idea by treating planning as data rather than as thoughts, and Lesson 10 goes further with a dependency graph of atoms. This is a real position, not a slogan, and it has a cost the README acknowledges in the same list of principles: the project describes itself as educational rather than production, teaching fundamentals rather than best practices. Nothing in the supplied material describes retry policy for a model that returns JSON that fails to parse, or what happens when a tool call raises. Lesson 09 is titled atomic actions and safe execution, so the topic is at least addressed in the curriculum, but the README does not characterise the guarantees. Treat the loop as a teaching artifact until you have read agent/agent.py and decided for yourself where the failure paths are.
The Atom of Thought detour
Lessons 07 through 10 are where the curriculum stops being a generic agent tour. Planning as data and the Atom of Thought dependency graph are specific representational choices, and they shape the second half of the course. A reader who wants a linear plan and a tool call will find Lesson 08 and Lesson 10 teaching a structure they may not adopt. That is the main editorial risk in the sequence: the first six lessons map onto what most small agents actually do, while the last four commit to a particular way of decomposing work. The repository does not present the graph as one option among several, and the README gives no guidance on when a simpler plan representation would be sufficient. Read agent/planner.py before deciding how much of Lessons 08 to 10 you intend to absorb. If the graph is not a structure you would choose independently, the value of the later lessons drops sharply, because they build on it rather than beside it.
Evals without a framework, and what that leaves out
Lesson 11 introduces regression testing against golden datasets stored in evals/golden_datasets.py, with the framework in agent/evals.py. The README frames the purpose as catching prompt regressions before deployment, which is the right instinct for anyone who has watched a wording change alter routing behaviour. Because the datasets are plain Python, comparing two runs means running the agent twice and diffing the results yourself. There is no fixture format, no scoring harness and no report generator described in the material. Lesson 12 adds structured logging for latency, success rates and traces through agent/telemetry.py, so the observability pair is self-contained rather than integrated with an external tracing backend. For a learner this is the point: you see the shape of an evaluation loop without a library hiding it. For a team already running an evaluation platform, these two lessons are the least transferable part of the repository, because adopting them means adopting the hand-rolled version.
How it differs from an agent framework
LangChain is the comparison the README itself invites, and the difference is not feature count. A framework supplies abstractions for chains, tools and memory, and you write against those abstractions. This repository supplies one Python class that you read and modify, and the abstractions are whatever the lesson happened to introduce. The practical consequence is that nothing here is versioned for you: there are no releases retrieved, so there is no changelog to check before upgrading and no compatibility promise between the lessons and your own code. The second consequence is scope. A framework will also handle streaming, retries, provider switching and deployment concerns, none of which appear in the described curriculum. The trade is legibility for coverage. If you want to understand why an agent chose a branch, the code is short enough to follow. If you want to ship one next month, you will be rebuilding the parts the framework would have given you.
Licence, maintenance and the JavaScript sibling
The repository is MIT licensed, which permits commercial use and modification provided the copyright notice and permission notice are retained; that is a description of the licence text, not legal advice, and anyone embedding the code in a product should read the LICENSE file directly. Maintenance is a live question rather than a settled one. There are no retrieved releases, so upgrades arrive as commits to main, and the last recorded push is 2026-07-25. There is a sibling project, AI Agents from Scratch in JavaScript, linked from the README, and a second repository, AI Product from Scratch, which covers prompt engineering, structured output, multi-step reasoning, API design and frontend integration in TypeScript, React and Node.js across ten lessons. That companion is the better fit if your stack is JavaScript, though the README's badge markup for the JavaScript repository is inconsistent, showing a Python badge image with a JavaScript label. The Python repository is the one with the twelve-lesson agent curriculum described here. Budget for reading rather than integrating: the cost of adoption is the hours you spend in lessons/ and agent/, and the ongoing cost is re-reading the relevant lesson when a commit lands, since there is no release channel to tell you what changed.
Editorial conclusion
Adopt it if you write Python, already run a GGUF model locally, and want to see routing, tools, memory and planning expressed as ordinary code you can edit line by line. Skip it if you need a deployed agent this quarter, a supported library with versioned releases, or a cloud model behind an API key. Before committing time, open lessons/06_agent_loop.md and agent/planner.py and confirm the loop shape and the planning representation match the way you intend to build; if the repository's Atom of Thought dependency graph is not a structure you would choose, the second half of the curriculum teaches a design you will not reuse.
Community notes