Model or dataset
pguso/ai-agents-from-scratch avatar
pguso/ai-agents-from-scratch

Fifteen agent examples in Node.js on local models

Demystify AI agents by building them yourself. Local LLMs, no black boxes, real understanding of function calling, memory, and ReAct patterns.

4,915 stars711 forksJavaScriptMIT

At a glance

What is it?
pguso/ai-agents-from-scratch rebuilds agent patterns on local models through node-llama-cpp, in numbered JavaScript examples that start with npm install and a models folder you fill yourself. Fifteen example directories sit in the tree, and no release tags any of it.
Who is it for?
Use this if you want to watch function calling, memory and the ReAct loop assembled by hand in JavaScript, and if you can spare 8GB of RAM plus a model you pick yourself. Skip it if your first agent needs error handling, if you want a tagged version to depend on.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 114 days ago.
What is it written in?
Mainly JavaScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pguso/ai-agents-from-scratch4,915 ★ · +182
Star history
Repository2026-09-102026-11-15
pguso/ai-agents-from-scratch4.7k4.9k

182 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Eight gigabytes of RAM and a models folder sit between npm install and the first token

The listed prerequisites are short: Node.js 18+, at least 8GB of RAM with 16GB recommended, and model files that you download yourself into a ./models/ folder, with the download details handed off to DOWNLOAD.md. Installation is a single command, and three scripts are named for a first run.

bash
npm install
node intro/intro.js
node simple-agent/simple-agent.js
node react-agent/react-agent.js

Nothing here tells you which model the scripts expect or how large it should be. The memory floor is stated, the workload that meets it is not, so a reader with exactly 8GB clears the prerequisite and still has to choose something to download. The same page also points at a Python edition of the tutorial at github.com/pguso/agents-from-scratch, which carries its own install and its own model story.

The run commands and the code links name two different directory layouts

The run block prints node intro/intro.js, node simple-agent/simple-agent.js and node react-agent/react-agent.js. Every example link on the same page points elsewhere: examples/01_intro/intro.js, examples/07_simple-agent/simple-agent.js, examples/09_react-agent/react-agent.js. The numbered examples/ layout is what the links and the root file listing agree on, and that listing holds .env.example, .gitignore, CONTRIBUTING.md, DOWNLOAD.md, LICENSE.md, PROMPTING.md, diagrams/, examples/, helper/, logs/, package-lock.json and package.json with no intro/, simple-agent/ or react-agent/ directory beside them.

For someone starting at the top of the page that split has a cost. A reader who copies the run commands reaches for a path the root listing does not contain, and a reader who follows the links sees a different path than the one printed a few lines above it. Both routes land on the same example, but the first failure is a module resolution error rather than anything about agents.

Each example ships CODE.md and CONCEPT.md, leaving the README an index

Every numbered entry links three files: the script, a CODE.md walkthrough of that script, and a CONCEPT.md page of background ideas. The entry itself carries a title, the path line, a short list of what you will learn, and a line of key concepts. Under the first entry those concepts read model loading, context, the inference pipeline and token generation. Under the seventh, the one where the page says text generation becomes agency, they read function calling, tool definitions, agent decision making and action taking.

So the README names topics rather than explaining them. The prose a reader expects from a top level file has been spread across per-example CODE.md and CONCEPT.md files, and a companion site at agentsfromscratch.com that the README describes as a conceptual companion for mental models and progression, with the repository handling running and modifying the code. Work offline, or decide you would rather read one source, and the top level page gives you a syllabus with no lessons attached.

Error taxonomy arrives at example 11, behind ten agents that assume the call succeeds

Resilience gets its own numbered entry, and that entry names a typed error taxonomy split into validation, LLM, tool and workflow errors with stable codes, alongside timeouts, retries with backoff and jitter, classifying transient failures, and graceful degradation.

Putting it there has a price for the reader who came for the interesting part. Entries seven through ten are the ones people lift: function calling with JSON Schema tool definitions, memory persisted across sessions with retrieval strategies, the ReAct loop of reason, act and observe, and Atom of Thought planning that asks for a structured JSON plan and then executes it deterministically. None of those four summaries mentions a timeout, a retry count or an error code.

Four of the fifteen example directories have no run command at all

The repository tree lists fifteen numbered example directories: examples/01_intro/ up through examples/11_error-handling/, then examples/12_tree-of-thought/, examples/13_graph-of-thought/, examples/14_chain-of-thought/ and examples/15_tool-routing-embeddings/.

package.json claims ISC while the repository ships an MIT license file

The package manifest describes something other than the project. It names the package ai-agents at version 1.0.0, leaves description as an empty string, sets main to index.js, declares type as module, and records the license as ISC. The repository is listed as MIT, and the root of the tree carries LICENSE.md, so the manifest and the license file disagree in writing.

The dependency list is short, and each entry has a job.

json
"dotenv": "^17.2.3",
"node-llama-cpp": "^3.14.0",
"openai": "^6.7.0"

dotenv is what makes the single line in .env.example meaningful: OPENAI_API_KEY=your_api_key_here. node-llama-cpp is the local engine behind every entry except the hosted one. openai serves the hosted OpenAI intro in entry two, so every reader installs the hosted client whether or not they ever touch a network endpoint. Look at what the manifest cannot do either: main points at index.js, which is not among the root entries, and the only npm script prints Error: no test specified and exits 1. There is no suite to check an edit against, and anyone reading the license field instead of LICENSE.md will draw the wrong conclusion about reuse.

No releases means no tag to pin, and the last commit dates the whole thing

The project publishes no GitHub releases, so there is no tag to depend on. The most recent commit is dated 2026-07-24, and the code you study is whatever sits on the main branch at that commit.

That matters more here than it would for a released library, because what you consume is teaching code rather than an API. A published version shields you from a behaviour change inside a version range; fifteen example scripts carry no such guard, and any file can be rewritten between two visits. Around it sit 4891 stars, 712 forks and 12 open issues, and the README links a separate Python edition at github.com/pguso/agents-from-scratch, which is its own repository with its own install rather than a second language binding inside this one. If any of this code will end up in a project you own, write down the commit you copied from. A tag would record that for you, and there is none.

Editorial conclusion

Use this if you want to watch function calling, memory and the ReAct loop assembled by hand in JavaScript, and if you can spare 8GB of RAM plus a model you pick yourself. Skip it if your first agent needs error handling, if you want a tagged version to depend on. Before you copy anything, record the commit you took it from, since the last one is dated 2026-07-24 and there is nothing newer to point at.

Frequently asked questions

Does ai-agents-from-scratch need a GPU or an API key to run?

The default path is local. The prerequisites are Node.js 18+, at least 8GB of RAM with 16GB recommended, and model files you download into ./models/ yourself, with the details in DOWNLOAD.md. Entry two, 02_openai-intro, calls hosted models, and .env.example holds an OPENAI_API_KEY placeholder.

Which examples does ai-agents-from-scratch contain?

The README's numbered entries include 01_intro through 11_error-handling. The tree also lists examples/12_tree-of-thought/, examples/13_graph-of-thought/, examples/14_chain-of-thought/ and examples/15_tool-routing-embeddings/.

Can I pin a version of ai-agents-from-scratch?

No. There are no GitHub releases, so there is no tag to depend on, and the most recent commit is dated 2026-07-24. package.json reads version 1.0.0 and license ISC while the repository is listed as MIT, and its only npm script exits 1 with no test specified.

Official sources

  1. Issues
  2. License: MIT
  3. pguso/ai-agents-from-scratch on GitHub
  4. README
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pguso-ai-agents-from-scratch.svg)](https://hysenlabs.com/projects/pguso-ai-agents-from-scratch)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pguso-ai-agents-from-scratch.svg)](https://hysenlabs.com/projects/pguso-ai-agents-from-scratch)

Was this useful?