AI Agents From Scratch
Build AI agents locally without frameworks, demystifying function calling, memory, and ReAct patterns using node-llama-cpp.
Evidence: The repository provides no mechanisms or documentation for permission management, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, rollback, or source attribution. All trust-related criteria are unsupported, hence scored 0.
Evidence: The README lists example paths that are inconsistent with the project structure (e.g., README links to 'examples/01_intro/intro.js' while structure shows '01_intro/intro.js'), indicating minor inconsistency. Dependencies are listed in package.json but without version pinning or integrity checks. The error-handling example (11_error-handling) mentions error taxonomy and retries but lacks implementation details. Thus, self-consistency, dependency availability, and failure messages are scored 1.
Evidence: The README clearly targets developers wanting to understand AI agent internals and provides a progressive learning path covering multiple scenarios. Capability boundaries are mentioned (e.g., 'Limitations of pure LLM reasoning') but not detailed. Trigger precision is partially addressed via command-line run instructions, but no detailed parameters or configuration. Environment fit is partially covered with Node.js 18+ and RAM requirements, but no detailed system compatibility. Hence, audience and scenarios scored 2, others 1.
Evidence: The README provides clear project structure, installation notes, and examples, but lacks FAQ, detailed known limitations, versioning/changelog, and explicit maintenance responsibility. LICENSE.md is MIT but with placeholder copyright year and author. Thus, information architecture and examples/FAQ scored 2, install notes, naming stability, known limitations, license, and maintenance responsibility scored 1, versioning/changelog scored 0.
Evidence: Output format of examples is not detailed, but README provides run commands. Marginal value is high as the repository offers a unique learning resource for building AI agents from scratch. Cost-benefit is partially addressed with hardware requirements but no detailed cost analysis. Hence, output usability scored 1, marginal value 2, cost-benefit 1.
Evidence: Claims in README (e.g., 'This is where text generation becomes agency!') lack verifiable evidence. No tests or benchmarks are provided to support teaching effectiveness. Fact-inference separation is unclear; for example, descriptions of ReAct pattern are factual but without sources. Hence, claim traceability scored 1, cross-source corroboration 0, fact-inference separation 1.
- The repository provides no security mechanisms or permission management; assess risks before use.
- Inconsistencies between README example paths and project structure may confuse users.
- LICENSE.md contains placeholder copyright information; verify actual licensing.
- Dependencies are not version-pinned, posing supply chain risks.
What does this agent do, and when should you use it?
This repository is a progressive, educational resource for building AI agents from first principles using local LLMs and node-llama-cpp. It contains 15 examples that start with basic LLM interaction and gradually cover system prompts, reasoning, batch processing, streaming, function calling, persistent memory, ReAct, AoT, error handling, Tree of Thought, Graph of Thought, Chain of Thought, and embedding-based tool routing. Each example includes working code (.js) plus dedicated documentation (CODE.md and CONCEPT.md) explaining the implementation and concepts. The project emphasizes local inference, requiring users to download GGUF models, and provides a companion website for conceptual mapping. The goal is for learners to deeply understand how agents work under the hood so they can use production frameworks wisely.
The repository runs a series of Node.js scripts that load local GGUF models via node-llama-cpp and perform inference. Examples include intro/intro.js (basic prompting), simple-agent/simple-agent.js (function calling), react-agent/react-agent.js (ReAct pattern), and tree-of-thought/tree-of-thought.js (beam search). Each script reads local models, takes input, calls the LLM, and optionally uses tool functions (e.g., function definitions in simple-agent). It provides a PromptDebugger utility (helper/prompt-debugger.js) to inspect the exact prompt sent to the model. Users run scripts via the command line and modify parameters based on CODE.md and CONCEPT.md files in each example folder.
- A Node.js developer who wants to use local LLMs in their application and needs to understand the underlying mechanisms.
- A developer learning function calling who wants a complete, working example on a local LLM with tool definitions.
- An AI engineer looking to deeply understand the ReAct pattern and the reasoning, acting, observing loop.
- A developer who wants to add persistent memory to LLM applications and understand state management.
- An engineer needing to implement tool routing to reduce context length and observe how embedding similarity selects relevant tools.
- A student or hobbyist who wants a hands-on introduction to agent architectures before building with production frameworks.
What are this agent's strengths and limitations?
- All code uses local LLMs via node-llama-cpp, eliminating API dependencies and protecting privacy.
- Each example includes CODE.md and CONCEPT.md, providing detailed explanations ideal for education.
- Covers multiple advanced agent patterns (ReAct, ToT, GoT, CoT) offering a broad architectural perspective.
- Includes a PromptDebugger utility to debug the exact prompt sent to the LLM, enhancing observability.
- Companion website supplements the repository with conceptual explanations, aiding the learning path.
- Requires familiarity with local model configuration and hardware (at least 8GB RAM).
- Examples are standalone scripts and lack production deployment integration or standardized APIs.
- Primarily a tutorial resource, not a production-ready agent framework; additional engineering is needed.
- Model downloads are manual, adding setup steps.
- Core dependency on node-llama-cpp and local GGUF models; migrating to other engines requires adaptation.
How do you install or deploy this agent?
First, ensure Node.js 18 or higher is installed. Then clone the repository and run npm install to install dependencies. Next, create a models/ folder in the repository root and download GGUF-format models (e.g., from Hugging Face) into it. Refer to DOWNLOAD.md for specific model recommendations and links.
How do you use this agent?
After installation, run examples from the repository root, such as node intro/intro.js or node react-agent/react-agent.js. Make sure models are downloaded and placed in ./models/. Each example folder contains CODE.md (step-by-step code explanation) and CONCEPT.md (concept overview); for full understanding, read both.