pguso/ai-agents-from-scratch

What is this project?

pguso/ai-agents-from-scratch is a hands-on tutorial repository that teaches you how to build AI agents from the ground up — without using any of the popular agent frameworks. Instead, it uses local language models (LLMs) running on your own computer, via a library called node-llama-cpp.

The core idea is "learn by building": you start with raw LLM calls and gradually add capabilities (tools, memory, reasoning patterns) until you've recreated what modern agent frameworks do — so you understand why those frameworks make the design choices they do.

What will you learn?

The README says you'll understand:

• How LLMs work at a fundamental level
• What agents really are (LLM + tools + patterns)
• How different agent architectures function
• Why frameworks make certain design choices

The core definition

The README gives a simple formula for an AI agent:

AI Agent = LLM + System Prompt + Tools + Memory + Reasoning Pattern

• LLM = the "brain" (the language model)
• System Prompt = the "identity" (instructions that shape behavior)
• Tools = the "hands" (functions the model can call)
• Memory = the "state" (persistent information)
• Reasoning Pattern = the "strategy" (how it thinks step by step)

The learning path (15 examples, in order)

Each example builds on the previous one. The README lists them as:

1. Intro — Load and run a local LLM; basic prompt/response cycle.
2. OpenAI Intro (optional) — Call hosted LLMs like GPT-4; learn about temperature, token usage, cost vs. control, data privacy.
3. Translation — Use system prompts to specialize an agent's behavior and control output format.
4. Think — Configure the LLM for logical reasoning; learn the limits of pure LLM reasoning and when to use external tools.
5. Batch — Process multiple requests in parallel for performance.
6. Coding — Stream responses token-by-token in real time; manage token budgets.
7. Simple Agent — The big step: function calling. Give the LLM tools it can decide to use. The README calls this "where text generation becomes agency."
8. Simple Agent with Memory — Persist facts and preferences across sessions; long-term memory management.
9. ReAct Agent — The Reason → Act → Observe loop: iterative problem solving with self-correction. The README calls this "the foundation of modern agent frameworks."
10. AoT Agent (Atom of Thought) — Break tasks into atomic planning steps with dependencies, output as structured JSON, execute deterministically.
11. Error Handling — Make LLM + tool systems resilient: typed errors, timeouts, retries with backoff, graceful fallbacks.
12. Tree of Thought — Generate multiple candidate next actions, rank and prune branches (beam search), verify the winning path.
13. Graph of Thought — Model reasoning as a DAG (directed acyclic graph): parallel source extracts → merge rules → final draft. Resolve conflicts before generating.
14. Chain of Thought — Split high-stakes decisions into explicit, auditable reasoning phases (e.g., facts-only extraction before policy application).
15. Tool Routing (embeddings) — Precompute embeddings for tool descriptions, score the user message by similarity, and pass only the top-k tools to the model to save context.

How the examples are structured

Each example folder contains three files:

• <name>.js — the working code
• CODE.md — step-by-step code explanation (line-by-line breakdowns)
• CONCEPT.md — high-level concepts, architectural patterns, real-world applications, simple diagrams

The README recommends reading both files for full understanding.

Requirements to run it

• Node.js 18+
• At least 8GB RAM (16GB recommended)
• Download models and place them in a ./models/ folder (details in DOWNLOAD.md)

Install with npm install, then run examples like:

node intro/intro.js
node simple-agent/simple-agent.js
node react-agent/react-agent.js

Companion website

There's a matching site at https://agentsfromscratch.com. It's not a replacement for the repo — it's a conceptual companion that explains why each example exists and visualizes the learning path. The recommended workflow: use GitHub for running and studying code, use the website for mental models and explanations. The README puts it as: "Think of the site as the map and this repo as the terrain."

Helper utility

There's a PromptDebugger (helper/prompt-debugger.js) that shows exactly what the LLM sees — system prompts, function definitions, conversation history, context state — useful for debugging.

Additional resources referenced

• node-llama-cpp — the library used for local inference
• Hugging Face — model hub for GGUF models
• GGUF format — quantized models for local inference

License and contribution

The README states it's an educational resource — "use and modify as needed for learning." Contributions are welcome: documentation improvements, new example patterns, bug fixes, or sharing what you built.

Author

The repo is by pguso (Patric Gutersohn), who offers freelance/contract work on AI workflows, context engineering, RAG, and local/production LLM projects (contact: pguso@gmx.de).

---

Bottom line: If you want to truly understand what happens under the hood of AI agents before using frameworks, this repo walks you through building them yourself, one capability at a time, entirely on your own machine.