Repolode
Submit
pguso

pguso/ai-agents-from-scratch

A hands-on tutorial that teaches AI agent building from scratch with local LLMs via node-llama-cpp, covering function calling, memory and ReAct.

View on GitHub
Stars
4,871
Forks
721
Open issues
12
Last commit
3 months ago

What is it?

AI Agents From Scratch is a learning repository for building AI agents in JavaScript without relying on agent frameworks. It runs local GGUF models through node-llama-cpp, so readers can see every prompt, tool call and loop iteration directly in code rather than hidden behind an abstraction layer.

The material is organized as 15 sequential examples. They progress from basic model loading and system prompts through streaming, batch processing and function calling, to persistent memory, the ReAct reasoning-and-acting loop, error handling, and newer patterns such as Tree of Thought, Graph of Thought, Chain of Thought and embedding-based tool routing. Each example folder includes a runnable script along with CODE.md and CONCEPT.md explanations.

The project requires Node.js 18+ and at least 8GB of RAM, and models are placed in a local models folder following the included download guide. A companion website at agentsfromscratch.com provides conceptual explanations alongside the code, and a Python version of the tutorial is maintained separately.

Key features

  • 01Runs local GGUF models through node-llama-cpp without cloud API keys
  • 02Covers function calling with JSON Schema tool definitions
  • 03Includes a ReAct agent loop with reason, act and observe steps
  • 04Demonstrates persistent memory for facts and preferences across sessions
  • 05Provides error handling with retries, timeouts and fallbacks
  • 06Each example ships with code, a line-by-line explanation and conceptual notes

Use cases

  • Developers who want to understand agent internals before adopting LangChain or similar frameworks
  • Engineers learning function calling and tool use with a small local model
  • Teams building offline or privacy-sensitive LLM prototypes in Node.js
  • Instructors preparing a hands-on course on agent architectures

Quick start

  1. 1

    Install Node.js 18+ and download models into ./models/ (see DOWNLOAD.md)

  2. 2

    Install dependencies

    npm install
  3. 3

    Run the introduction example

    node intro/intro.js
  4. 4

    Run the simple agent example

    node simple-agent/simple-agent.js

Things to know

  • Requires downloading local GGUF models and at least 8GB RAM (16GB recommended).
  • It is a tutorial with examples rather than a production framework.

Topics

#ai-agents#llm#function-calling#react-agent#local-llm#tutorial#node-llama-cpp#javascript#educational#llm-agent

FAQ

What is ai-agents-from-scratch?
A hands-on tutorial that teaches AI agent building from scratch with local LLMs via node-llama-cpp, covering function calling, memory and ReAct. AI Agents From Scratch is a learning repository for building AI agents in JavaScript without relying on agent frameworks. It runs local GGUF models through node-llama-cpp, so readers can see every prompt, tool call and loop iteration directly in code rather than hidden behind an abstraction layer.
Is ai-agents-from-scratch free to use? What license does it have?
ai-agents-from-scratch is open source under the MIT license. Check the license terms before using it in commercial products.
Is ai-agents-from-scratch still maintained?
Updated within 6 months. The last commit to ai-agents-from-scratch was on Jul 24, 2026.
What can I use ai-agents-from-scratch for?
Developers who want to understand agent internals before adopting LangChain or similar frameworks Engineers learning function calling and tool use with a small local model Teams building offline or privacy-sensitive LLM prototypes in Node.js Instructors preparing a hands-on course on agent architectures
How do I install ai-agents-from-scratch?
Install Node.js 18+ and download models into ./models/ (see DOWNLOAD.md) Install dependencies: npm install Run the introduction example: node intro/intro.js Run the simple agent example: node simple-agent/simple-agent.js
Where can I get ai-agents-from-scratch?
The source code and installation instructions are on GitHub: https://github.com/pguso/ai-agents-from-scratch

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects