pguso/agents-from-scratch

This repository is an educational project that teaches how AI agents actually work by building a single agent incrementally across 12 lessons. You start with a simple text-in/text-out call to a local language model, and each lesson adds a new capability: system prompts, structured output, decisions, tools, a loop, memory, planning, atomic actions, dependency graphs, evals, and telemetry.

The core idea is "no magic": everything is explicit, readable code. You work with a single evolving agent.py file, and a separate complete_example.py shows isolated examples of each lesson. The project is designed for developers who already code but are confused by agent frameworks. You run everything locally using a GGUF model (no API keys, no cloud).

The project's philosophy is that agents are not personalities — they are loops, state, and constraints. It deliberately avoids hiding reasoning or claiming models "think." Each lesson builds on the previous, so the recommended path is to follow them in order.

The repository also includes a philosophy document, a quickstart guide, and a folder structure with separate modules for memory, planning, tools, evals, and telemetry. It is not a framework, not a chatbot demo, and not production-ready — it exists purely for learning.

Key files:

• agent/agent.py – the main Agent class that evolves across all lessons (this is the heart of the project).
• complete_example.py – 12 separate functions, one per lesson, each demonstrating that lesson's concept in isolation. Run it with python complete_example.py.
• agent/evals.py – regression testing against known-good cases (Lesson 11).
• agent/telemetry.py – structured logging for debugging and observability (Lesson 12).

The curriculum covers: foundational LLM usage (lessons 1–3), agency (decisions, tools, loops — lessons 4–6), intelligence (memory, planning, execution — lessons 7–10), and observability (evals and telemetry — lessons 11–12).

In short: if you want a mechanical, hands-on understanding of AI agents without opaque frameworks, this repo walks you through building one from scratch, locally, step by step.