AI Agents From Scratch: A Hands-On Path From Raw LLM Calls to ReAct and AoT

What This Repository Actually Teaches and Who It Serves

The repository addresses a specific gap: developers who use agent frameworks like LangChain or AutoGPT often treat the internals as a black box. This project strips that away by building agents from first principles using local LLMs and node-llama-cpp. The intended audience is engineers who already know JavaScript and want to understand what a framework does under the hood before committing to one. The README states the philosophy directly: 'Learn by building. Understand deeply, then use frameworks wisely.' That is not a slogan; it shapes every example. The learning path starts with loading a model and making a basic prompt call, then moves through system prompts, reasoning, batch processing, streaming, function calling, memory, ReAct, and finally Atom of Thought planning. Each example has code, a CODE.md explanation, and a CONCEPT.md file, so the material is structured for study, not just copy-paste.

The Architecture: Ten Progressive Modules From Intro to AoT

The repository is organized as a sequence of directories, each representing a step in the learning path. The progression is deliberate. Intro covers model loading and token generation. Translation introduces system prompts to specialize behavior. Think pushes the model on quantitative problems to expose the limits of pure reasoning. Batch handles parallel requests, which matters when you run local models and want throughput. Coding demonstrates streaming and token budget control. Simple Agent is the turning point: it adds function calling with JSON Schema, which the README marks as 'where text generation becomes agency.' Simple Agent with Memory adds persistence across sessions. ReAct Agent implements the Reason-Act-Observe loop, and AoT Agent introduces atomic planning with structured JSON output and dependency resolution. Each module builds on the previous one, so skipping ahead likely leaves gaps. The architecture is not a library; it is a curriculum.

Mechanism: Local LLMs, Function Calling, and the ReAct Loop

The core mechanism is straightforward: you load a local LLM via node-llama-cpp, send prompts, and gradually add tool use. In the simple-agent example, you define tools that the LLM can call, using JSON Schema to specify parameters. The model decides when to invoke a tool, and the agent executes it. In the react-agent example, the pattern becomes iterative: the model reasons, chooses an action, observes the result, and repeats until it solves the problem. This is the ReAct pattern, and the README calls it 'the foundation of modern agent frameworks.' The AoT agent goes further by having the model output a structured plan of atomic operations with dependencies, which the agent then executes deterministically. That shift from free-form reasoning to structured planning is a meaningful difference, and the repository shows both approaches side by side.

Getting It Running: Commands, Prerequisites, and Model Placement

The installation is minimal: run npm install in the repository root. You need Node.js 18 or newer and at least 8GB of RAM, with 16GB recommended. The README instructs you to download models and place them in a ./models/ folder, with details in a DOWNLOAD.md file that is not included in the cleaned README. To run an example, you execute a Node script directly, such as node intro/intro.js or node react-agent/react-agent.js. There is no build step, no configuration file, and no server to start. The simplicity is intentional: each script is a standalone demonstration. However, the exact model files and download URLs are only in DOWNLOAD.md, so you must fetch that file from the repository to proceed. The examples also assume a local model, not a hosted API, except for the optional openai-intro module that shows how to call proprietary models like GPT-4.

Genuine Limitations: Hardware Demands, Scope, and Missing Production Concerns

The most obvious limitation is hardware. Running local LLMs requires significant RAM, and the README itself says 8GB is the floor with 16GB recommended. On a typical laptop with 8GB, larger models will be slow or fail to load. The repository also does not cover deployment, scaling, or integration with external APIs beyond the optional OpenAI example. It is educational, so there is no error-handling module until step 11, which is truncated in the README but suggests timeouts and retries are covered. That means production concerns like concurrency control, security, and cost management are not addressed. If you need a drop-in agent for a product, this is the wrong tool. Another limitation is that the material is JavaScript-specific, though the README points to a Python version at pguso/agents-from-scratch, which may be more suitable for Python-centric teams.

Comparison: Framework-Based Approaches vs. This From-Scratch Path

The natural alternative is a production agent framework such as LangChain or AutoGPT, which abstract away the details of tool calling, memory, and reasoning loops. Those frameworks give you ready-made agent classes, integrations with dozens of model providers, and built-in memory stores. The difference in approach is stark: a framework hides the mechanism behind a high-level API, while this repository exposes every step. For example, in LangChain you might call an AgentExecutor and not see how the ReAct loop is implemented. Here, you write the loop yourself in react-agent.js. The trade-off is time versus convenience. Using a framework gets you to a working agent faster, but you may not understand why it fails when it does. This repository is a deliberate counterweight: it slows you down to speed up your mental model. The README even frames frameworks as something to use 'wisely' after you have built your own.

Maintenance, Upgrades, and License Implications

The repository is not archived and had a push on July 24, 2026, but there are no recent releases listed, so version stability is unclear. The dependency on node-llama-cpp means the examples will track that library's API, which can change. The README does not mention a contribution guide or release cadence, so maintenance appears to be driven by the author. The license is MIT, which permits free use, modification, and distribution, including in commercial projects, with the requirement to preserve the copyright notice. This is a permissive license, so you can adapt the code for your own learning or even incorporate it into a product, though the educational nature means you would likely rewrite the examples rather than reuse them as-is. Before relying on any code, check the repository for an updated DOWNLOAD.md and verify that the example scripts still run with the current node-llama-cpp version.

Editorial conclusion

Adopt this repository if you are a JavaScript developer who wants to understand agent internals before using production frameworks, and you have a machine with at least 8GB RAM (16GB recommended) to run local models. Skip it if you need a deployable agent framework or prefer Python, though a Python version exists at pguso/agents-from-scratch. Before starting, verify your Node.js version is 18+ and download the required models into ./models/ as specified in DOWNLOAD.md, since the examples will not run without them. This is a teaching tool, not a runtime, so its value is in the code walkthroughs and concepts, not in production readiness.

Official sources

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