pguso/ai-agents-from-scratch: build a local ReAct agent with node-llama-cpp

What pguso/ai-agents-from-scratch is for

Most introductions to AI agents start with a framework import. The README of this repository states the opposite intent: understand what happens under the hood before using production frameworks, and its stated philosophy is "Learn by building. Understand deeply, then use frameworks wisely." The subject is the layer between a language model and an agent: how a prompt becomes a tool call, how a loop decides to act again, how state survives between sessions.

It is aimed at developers who already write JavaScript and want the mechanics rather than an abstraction. The README lists Node.js 18+, at least 8GB RAM (16GB recommended), and local model files placed in ./models/, with details in DOWNLOAD.md. There is a Python version of the same tutorial at a separate repository, so the choice between them is a language choice, not a feature choice.

The repository also points to a companion site, agentsfromscratch.com, described as a conceptual companion rather than a replacement, and the README suggests using GitHub for running and modifying code and the site for mental models. That split matters: the explanation of why an example exists may live outside the repository you cloned.

The learning path from raw inference to a ReAct loop

The examples directory is numbered, and the numbering is the curriculum. It begins at examples/01_intro with model loading and a basic prompt and response cycle, moves through system prompts, reasoning prompts, batch processing and streaming, and only reaches function calling at examples/07_simple-agent. The README marks that step plainly: "This is where text generation becomes agency!"

From there the sequence adds one capability at a time. examples/08_simple-agent-with-memory covers persisting facts and preferences across sessions. examples/09_react-agent implements the Reason, Act, Observe cycle the README calls "the foundation of modern agent frameworks." Later directories go further into planning and reasoning structures (AoT, tree-of-thought, graph-of-thought, chain-of-thought) and finish with examples/11_error-handling, which the README says introduces a typed error taxonomy with stable codes spanning validation, LLM, tools and workflow, plus timeouts and retries. There is also examples/15_tool-routing-embeddings, which the README does not describe in detail.

The dependencies in package.json are three: dotenv, node-llama-cpp and openai. Everything else in the agent logic is written in the repository itself. That is the whole architectural claim: the agent loop is code you can read, not a dependency you configure.

Installing it and running the first example

Installation is a single npm command from the repository root. The README gives no build step and no global tooling, so the expectation is a normal Node.js project layout.

npm install

Before anything runs, the model files have to exist. The README states that models are downloaded and placed in ./models/ and that DOWNLOAD.md holds the details; it does not name the models in the README itself, so read that file first and confirm the files land in the right directory.

The first script to try is the introduction, which the README lists under Run Examples. It loads a local model and completes one prompt and response cycle, so it is also the cheapest way to find out whether your hardware and your model file agree with each other.

node intro/intro.js

Once that prints a response, the agent examples follow. The README's own run list includes the simple agent and the ReAct agent:

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

The OpenAI example is separate and optional. It reads a key from the environment, and .env.example in the repository root contains exactly one variable to copy into a .env file:

OPENAI_API_KEY=your_api_key_here

That example is the only part of the tutorial that needs network access and an account. Everything else is built around node-llama-cpp and local weights.

Where this repository will frustrate you

The package.json is the clearest signal of what this is not. The test script is the npm default, echo "Error: no test specified" && exit 1, the description and keywords fields are empty, and the license field says ISC even though the repository ships a LICENSE.md and the project is listed as MIT. If you wire this into a dependency graph or an automated pipeline, that mismatch is the first thing to resolve.

The hardware requirement is the second. Local inference means the model must fit in memory, and the README's floor of 8GB with 16GB recommended is a real gate, not a formality. On a laptop with integrated graphics and limited RAM, the later examples are slow enough that the learning loop breaks down: you spend the session waiting rather than reading code. The README offers no fallback path for that case beyond the optional OpenAI example.

There is also no release history and no versioning beyond the package's 1.0.0. Nothing in the repository describes a changelog or a deprecation policy, so if you copy an example into a project of your own, you are on your own for tracking upstream changes to node-llama-cpp. The repository is a snapshot of teaching code, and it should be treated as one.

How it compares with a framework-first tutorial

The obvious alternative is a framework such as LangChain or LangGraph, where an agent is assembled from provided abstractions: a tool wrapper, a memory store, an executor. The difference is where the uncertainty sits. With a framework you get a supported API, documentation, and a community that has already hit the edge cases; you also inherit a dependency whose internals you did not write and may not read.

This repository takes the other route. Function calling is demonstrated by defining tools and their JSON Schema parameters yourself, and the ReAct loop is written out as Reason, Act, Observe rather than configured. That makes the failure modes visible: you see what happens when the model returns malformed arguments, and examples/11_error-handling exists precisely to name those failures and give them stable codes.

A second alternative is the Python version of the same tutorial, linked from the README. It is not a different approach, only a different runtime, and it matters if your target environment is Python rather than Node.js. The concepts transfer; the code does not.

If your goal is to ship an agent this month, a framework will get you there faster. If your goal is to be able to debug one, the order here is the more useful one.

Licence, maintenance and upgrade cost

The repository is MIT licensed according to its listing, and LICENSE.md is present at the root. Note the discrepancy with package.json, which declares ISC; anyone redistributing the code should read LICENSE.md rather than trust the manifest field. This is a description of what the files say, not legal advice.

The last push to the default branch was on 2026-07-24, and the repository is not archived. There are no retrieved releases, so there is no versioned artifact to pin and no upgrade path expressed as releases. In practice, updating means pulling the branch and re-reading the examples you copied, which is cheap for a tutorial and expensive for anything you have built on top of it.

The dependency surface is small, which limits upgrade cost: dotenv, node-llama-cpp and openai, with node-llama-cpp pinned to ^3.14.0 in package.json. The main ongoing cost is not code drift but environment drift: model files, hardware, and the native build of node-llama-cpp on your platform.

Editorial conclusion

Adopt this if you want to see the mechanics of function calling, memory and the ReAct loop before you pick a framework, and if you have a machine with at least 8GB RAM (the README recommends 16GB) plus room for local model weights. Skip it if you need a supported library with tests, semantic versioning or a release history, or if you intend to ship to production straight from these files. Before you start, open DOWNLOAD.md and confirm that the model files it names are ones you can actually download and that your hardware can run them; then run node intro/intro.js and check that a local model answers before you touch the agent examples.

Frequently asked questions

Official sources

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