AI Agents from Scratch
Build one agent step by step from a single local LLM call — no frameworks, no cloud APIs, no hidden reasoning.
- Source repo
- pguso/agents-from-scratch
- Stars
- ★ 1.1k
- Last updated
- 2mo ago
- License
- MIT
- Primary language
- Python
- FA score
- 32/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- Backend developers who can code but are lost on how agent loops, state and tools actually fit together
- Not a fit if
- Teams wanting a ready-made demo or SaaS starter kit
- Users unwilling to download a GGUF model into a local models/ folder
- Projects needing production-grade, hosted best practices
- Source review
- 32/100 · Major gaps 3 safety controls not found
What does this agent do, and when should you use it?
agents-from-scratch is a local-first educational repository that grows a single agent across 12 lessons, starting from one local LLM call and ending with memory, planning, evals and telemetry. The implementation lives in the Agent class in agent/agent.py, which gains new methods in each chapter; supporting modules include memory.py, planner.py, state.py, tools.py, evals.py and telemetry.py, with shared LLM and prompt utilities under shared/. Execution is plain Python against a local GGUF model — no OpenAI or cloud API, no API keys — and complete_example.py runs each of the 12 lessons as a standalone function. evals/golden_datasets.py holds known-good cases for regression testing. The project is explicitly framed as teaching material rather than a production framework.
The curriculum evolves one agent in order: 01 text in / text out; 02 roles via system prompts; 03 structured output enforced by JSON contracts; 04 routing-based decision making; 05 tools from tools.py; 06 the observe → decide → act agent loop; 07 short- and long-term memory through memory.py; 08 planning stored as data rather than thoughts (planner.py); 09 safe execution of atomic actions; 10 Atom of Thought dependency graphs; 11 regression testing with agent/evals.py against evals/golden_datasets.py; 12 runtime observability via agent/telemetry.py, emitting structured logs, latency and traces. Running python complete_example.py isolates each lesson; LLM traffic goes through the shared layer to a local GGUF model. Outputs are text, structured JSON, tool results, and evaluation/telemetry records.
- Backend developers who can code but are lost on how agent loops, state and tools actually fit together
- Educators and trainers who need an offline-capable walkthrough of agent architecture for a classroom or workshop
- Engineers experimenting with local GGUF models on prompts and structured JSON output
- Learners who want a concrete model for adding evals and telemetry to an existing Python project
- Curriculum designers building a staged course around agent fundamentals
How do you install or deploy this agent?
The README's quick start is three steps: install dependencies, download a GGUF model into models/, and run the example.
pip install -r requirements.txtThen place a GGUF model file into the repository's models/ directory. The README does not name a specific model or download source — that piece must be supplied by you. A detailed setup guide is provided in QUICKSTART.md.
How do you use this agent?
Run the bundled example to see all 12 lessons demonstrated. Proceed in order through the lessons; the README explicitly advises against skipping ahead.
python complete_example.pyTo study the evolving implementation, start with the Agent class in agent/agent.py and read lessons/01_basic_llm_chat.md through lessons/12_telemetry.md. For regression testing, compare agent behavior against the known-good cases in evals/golden_datasets.py using agent/evals.py.
What are this agent's strengths and limitations?
- A single
agent/agent.pyevolves across all 12 lessons, so each capability's addition is traceable to one file - Fully local: no OpenAI or cloud API, no API keys, no rate limits
- Relies on JSON contracts and explicit constraints instead of prompt cleverness, per the stated 'structure over prompting' principle
- Ships both a regression eval harness (
agent/evals.py+ golden datasets) and a telemetry module - MIT licensed, with
complete_example.pygiving a runnable demo per lesson
- Self-described as educational, not production — it does not teach deployment or best practices
- You must source a GGUF model yourself; the README names no model or download URL
- No packaging: usage means cloning the repo and running Python scripts
- No cloud or hosted-model path; switching to a remote API means rewriting the shared LLM layer
- Python only — the JavaScript variant lives in a separate repository
How does this agent compare with similar options?
The README explicitly positions the project against 'just use LangChain' and excludes frameworks by design: where LangChain abstracts models, tools and control flow, this repository keeps them as explicit Python to make the loop, state and constraints visible, trading production scaffolding for transparency.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| AI Agents from Scratch This agent | 32 · Major gaps | CLIFree | ★ 1.1k | 2mo ago | Python | — |
| AI Agents From Scratch | 28 · Major gaps | CLIFree | ★ 4.9k | 2mo ago | JavaScript | — |
| GenAI Agents Comprehensive Tutorial Collection | 25 · Major gaps | Library / SDKFree + model costs | ★ 25k | 2d ago | Jupyter Notebook | OpenAI API |
| Late | 50 · Major gaps | CLIFree + model costs | ★ 446 | 1d ago | Go | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows only local-first, no-cloud-API, no-API-key claims and a single dependency (llama-cpp-python) in requirements.txt; no permission model, tool-execution confirmation, sensitive-data handling, or rollback code is visible. least_privilege and external_effects get 1 on claims alone; user_confirmation, sensitive_data_handling, rollback have no evidence, scored 0; dependency_security gets 1 for one unpinned dependency; source_attribution gets 1 for MIT and an acknowledgments note without concrete citations.
README claims 12 lessons building one agent and the structure is self-consistent, but no code files are provided to corroborate, so self_consistency is 1; llama-cpp-python is unpinned and availability depends on local compilation and GGUF model download, dependency_availability is 1; no error handling or failure-message design is visible, failure_messages is 0.
README clearly lists target and non-target audiences, a learning path, and capability boundaries (not a framework, not production), so audience_and_scenarios and capability_boundaries are 2 each; invocation is only python complete_example.py, trigger_precision is 1; environment fit mentions only local GGUF and pip without platform differences, environment_fit is 1.
README has a clear directory structure and key-file explanations, information_architecture is 2; install notes point to QUICKSTART.md which is not in the evidence, install_notes is 1; naming stability is only described, naming_stability is 1; examples are limited to complete_example.py with no FAQ, examples_and_faq is 1; known_limitations has an 'educational not production' statement but no concrete limitation list, scored 1; LICENSE is full MIT, license is 2; no version or changelog, versioning_changelog is 0; maintenance responsibility is only a contributing guide with no maintainer commitment, maintenance_responsibility is 1.
Output usability depends on code not shown, output_usability is 1; marginal value as a teaching project exists but no comparative evidence, marginal_value is 1; cost-benefit rests only on local-run claims without quantification, cost_benefit is 1.
The lesson table and file structure are traceable, but key files (agent/*.py, QUICKSTART.md) are absent from the evidence, claim_traceability is 1; cross-source corroboration is limited to consistency among README, LICENSE, and requirements, cross_source_corroboration is 1; fact/inference separation is reasonable (explicit 'is/is not' sections), fact_inference_separation is 1.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Evidence includes only README, LICENSE, and requirements.txt; core code and QUICKSTART.md are missing, so actual behavior cannot be verified.
- llama-cpp-python is unpinned, creating dependency drift and local compilation risk.
- No evidence of user confirmation, sensitive-data handling, or rollback; do not treat as production-ready.
- Publisher identity is unverified; maintenance responsibility and update path are unclear.
FAQ
Does running it cost anything or require API keys?
Which model and hardware do I need?
models/ and install the Python dependencies from requirements.txt. The README does not specify a model name, size, or VRAM requirement, so that choice is yours.Can I use it in production?
What do the evals and telemetry lessons actually provide?
agent/evals.py with golden datasets in evals/golden_datasets.py for prompt regression testing; lesson 12 adds agent/telemetry.py for structured logging of latency, success rates and traces.Is there a JavaScript version?
ai-agents-from-scratch repository for a JavaScript counterpart; this repository is the Python implementation.