Agents from Scratch: A 12-Lesson Python Tutorial for Building Local AI Agents Without Frameworks

What This Repository Teaches and Who It Is For

Agents from Scratch addresses a specific frustration: developers who have seen agent frameworks but cannot explain what an agent actually does under the surface. The README states the project's philosophy in one sentence: agents are not personalities, they are loops, state, and constraints.

The repository targets developers who can code but feel lost with agents, people who want local models rather than cloud APIs, and engineers who want mechanical understanding rather than a working demo. The README explicitly lists who the repository is NOT for: people looking for a SaaS starter kit, people who want the fastest demo, or people who believe agents think.

That framing is useful because it sets expectations before you clone. This is an educational repository, not a production tool. The README states this directly under Core Principles: "Educational, not production. This teaches fundamentals, not best practices."

The 12 Lessons and What Each One Adds

The repository builds one continuously evolving agent across 12 lessons, each adding a new capability to the same `agent.py` file. The curriculum is:

- Lesson 01: Text in / text out (basic LLM call) - Lesson 02: Roles and behavior via system prompts - Lesson 03: Structured output via JSON contracts - Lesson 04: Decisions and routing logic - Lesson 05: Tools and external capabilities - Lesson 06: The agent loop (observe, decide, act) - Lesson 07: Memory, both short and long-term - Lesson 08: Planning as data, not as thoughts - Lesson 09: Atomic actions for safe execution - Lesson 10: Atom of Thought (dependency graphs) - Lesson 11: Evals and regression testing - Lesson 12: Telemetry and runtime observability

The README organises these into four phases: Lessons 1-3 cover LLM basics, Lessons 4-6 build agency through decisions, tools, and loops, Lessons 7-10 add intelligence through memory and planning, and Lessons 11-12 add observability. The README states clearly: do not skip ahead. The curriculum is designed to build understanding gradually.

Installing and Running the Examples

The only Python runtime dependency is `llama-cpp-python`. The full requirements.txt is a single line:

llama-cpp-python

To get started, install dependencies and download a model:

pip install -r requirements.txt

Then place a GGUF model file in the `models/` directory. The README links to the QUICKSTART.md file for detailed setup instructions. Once a model is in place, run all 12 lesson examples through:

python complete_example.py

The `complete_example.py` file contains 12 separate functions, one per lesson, demonstrating each concept in isolation. It is described as a learning reference: you study the complete examples first, then work through the individual lesson files in `lessons/` to understand each part before combining them.

A setup verification script is also included:

python setup_check.py

Repository Structure and Key Files

The repository layout is explicit about what each component does. The core implementation lives in the `agent/` directory, which contains:

- `agent.py`: the main agent class that grows across all 12 lessons - `memory.py`: the memory system - `planner.py`: planning and atomic action logic - `evals.py`: regression testing for Lesson 11 - `telemetry.py`: structured logging for Lesson 12

The `shared/` directory holds reusable utilities: the LLM wrapper, prompt helpers, and general utilities. The `lessons/` directory contains the 12 lesson markdown files, each with a heading indicating the capability added and a link from the README's table.

The `diagrams/` directory suggests visual documentation of the architecture, though the README does not describe its contents in detail. The `evals/` directory at the root is separate from `agent/evals.py` and appears to hold evaluation fixtures.

The relationship the README describes is intentional: `agent/agent.py` is the code you are learning, while `complete_example.py` provides isolated, self-contained demonstrations of each lesson concept. Study the examples before modifying the agent.

The Local-First Constraint and What It Means in Practice

The repository requires GGUF model files for the LLM. You download a model, place it in `models/`, and pass its path to the llama-cpp-python backend. There is no API key, no rate limit, and no internet dependency at inference time.

This constraint is also the main setup barrier. GGUF models vary widely in size (from a few gigabytes to dozens) and capability. The README does not specify a recommended model, which means the first-time user must choose one independently. Model quality affects whether the agent's structured output and routing steps behave as described in the lessons.

The README notes that the repository synthesizes best practices from modern agent development while deliberately avoiding complexity that obscures understanding. The explicit tradeoff is that production reliability patterns (retry logic, fallback models, provider redundancy) are out of scope. This is a teaching tool, not a deployment template.

Agents from Scratch vs. LangChain

The most common framework for building agents in Python is LangChain. LangChain provides abstractions for chains, agents, tools, memory, and retrieval, and connects to dozens of LLM providers and vector stores. It is designed for building production applications quickly by composing pre-built components.

Agents from Scratch takes the opposite approach. It provides no abstractions and connects to no providers. The README mentions LangChain by name in the target audience section, specifically listing "people tired of 'just use LangChain'" as a primary audience. The goal is to make the agent loop visible and modifiable rather than hiding it behind a framework.

The practical difference is that after working through Agents from Scratch, a developer can write a LangChain agent and understand what it is actually doing at each step. The reverse is not necessarily true. LangChain is the better choice for shipping a product; Agents from Scratch is the better choice for understanding what you are shipping.

License and Maintenance

The repository is MIT licensed. The MIT license permits use, modification, and redistribution with attribution. Contributing guidelines are documented in CONTRIBUTING.md, and the README states that contributions should maintain the gentle, progressive learning style, keep code readable over clever, and preserve the no-framework philosophy.

The repository also has a companion project, AI Agents from Scratch in JavaScript, at github.com/pguso/ai-agents-from-scratch, and a related AI Product from Scratch repository that extends the concepts to a TypeScript and React frontend with Node.js backend. These are separate repositories and are mentioned in the README's Related Projects section.

The last push was on 2026-07-25. There are no formal GitHub releases. The repository is described as educational rather than a versioned library, so release tags are not a meaningful metric for this project type.

Editorial conclusion

Agents from Scratch is the right starting point for developers who can already write Python and want to understand what an agent loop actually is at the code level, without adopting a framework first. The repository is not a production template and the README says so directly: it teaches fundamentals, not best practices. Anyone looking for a runnable multi-agent orchestrator or a hosted deployment starter will not find one here. The last push was on 2026-07-25, and the single runtime dependency is llama-cpp-python, which means you need a GGUF model file before running the first example.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pguso/agents-from-scratch on GitHub
4. README