[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-72689":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":35,"readmeContent":36,"aiSummary":37,"trendingCount":16,"starSnapshotCount":16,"syncStatus":38,"lastSyncTime":39,"discoverSource":40},72689,"ai-agents-from-scratch","pguso\u002Fai-agents-from-scratch","pguso","Demystify AI agents by building them yourself. Local LLMs, no black boxes, real understanding of function calling, memory, and ReAct patterns.","",null,"JavaScript",4248,618,26,9,0,17,71,753,51,30.38,"MIT License",false,"main",true,[27,28,29,30,31,32,33,34],"ai-agents","educational","function-calling","llm","llm-agent","node-llama-cpp","react-agent","tutorial","2026-06-12 02:03:06","# AI Agents From Scratch\n\nLearn to build AI agents locally without frameworks. Understand what happens under the hood before using production frameworks.\n\n![Agent architecture overview](diagrams\u002Fagent-architecture.png)\n\n\n## Purpose\n\nThis repository teaches you to build AI agents from first principles using **local LLMs** and **node-llama-cpp**. By working through these examples, you'll understand:\n\n- How LLMs work at a fundamental level\n- What agents really are (LLM + tools + patterns)\n- How different agent architectures function\n- Why frameworks make certain design choices\n\n> A Python version of this tutorial is available here:\n> https:\u002F\u002Fgithub.com\u002Fpguso\u002Fagents-from-scratch\n\n**Philosophy**: Learn by building. Understand deeply, then use frameworks wisely.\n\n## Companion Website \n\nThis repository now has a **matching companion website**:\n\n**https:\u002F\u002Fagentsfromscratch.com**\n\nThe website is **not a replacement for this repo**, but a **conceptual companion** that:\n\n- Explains *why* each example exists  \n- Visualizes the learning path from raw LLM calls to full agents  \n- Separates **code**, **explanations**, and **core concepts**  \n- Helps you understand agent architectures before using frameworks  \n\n**Recommended workflow:**\n- Use **GitHub** for running, modifying, and studying the code  \n- Use the **website** for mental models, explanations, and progression  \n\n> Think of the site as the *map* and this repo as the *terrain*.\n\n## Agent Fundamentals - From LLMs to ReAct\n\n### Prerequisites\n- Node.js 18+\n- At least 8GB RAM (16GB recommended)\n- Download models and place in `.\u002Fmodels\u002F` folder, details in [DOWNLOAD.md](DOWNLOAD.md)\n\n### Installation\n```bash\nnpm install\n```\n\n### Run Examples\n```bash\nnode intro\u002Fintro.js\nnode simple-agent\u002Fsimple-agent.js\nnode react-agent\u002Freact-agent.js\n```\n\n## Learning Path\n\nFollow these examples in order to build understanding progressively:\n\n### 1. **Introduction** - Basic LLM Interaction\n`intro\u002F` | [Code](examples\u002F01_intro\u002Fintro.js) | [Code Explanation](examples\u002F01_intro\u002FCODE.md) | [Concepts](examples\u002F01_intro\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Loading and running a local LLM\n- Basic prompt\u002Fresponse cycle\n\n**Key concepts**: Model loading, context, inference pipeline, token generation\n\n---\n\n### 2. (Optional) **OpenAI Intro** - Using Proprietary Models\n`openai-intro\u002F` | [Code](examples\u002F02_openai-intro\u002Fopenai-intro.js) | [Code Explanation](examples\u002F02_openai-intro\u002FCODE.md) | [Concepts](examples\u002F02_openai-intro\u002FCONCEPT.md)\n\n**What you'll learn:**\n- How to call hosted LLMs (like GPT-4)\n- Temperature Control\n- Token Usage\n\n**Key concepts**: Inference endpoints, network latency, cost vs control, data privacy, vendor dependence\n\n---\n\n### 3. **Translation** - System Prompts & Specialization\n`translation\u002F` | [Code](examples\u002F03_translation\u002Ftranslation.js) | [Code Explanation](examples\u002F03_translation\u002FCODE.md) | [Concepts](examples\u002F03_translation\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Using system prompts to specialize agents\n- Output format control\n- Role-based behavior\n- Chat wrappers for different models\n\n**Key concepts**: System prompts, agent specialization, behavioral constraints, prompt engineering\n\n---\n\n### 4. **Think** - Reasoning & Problem Solving\n`think\u002F` | [Code](examples\u002F04_think\u002Fthink.js) | [Code Explanation](examples\u002F04_think\u002FCODE.md) | [Concepts](examples\u002F04_think\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Configuring LLMs for logical reasoning\n- Complex quantitative problems\n- Limitations of pure LLM reasoning\n- When to use external tools\n\n**Key concepts**: Reasoning agents, problem decomposition, cognitive tasks, reasoning limitations\n\n---\n\n### 5. **Batch** - Parallel Processing\n`batch\u002F` | [Code](examples\u002F05_batch\u002Fbatch.js) | [Code Explanation](examples\u002F05_batch\u002FCODE.md) | [Concepts](examples\u002F05_batch\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Processing multiple requests concurrently\n- Context sequences for parallelism\n- GPU batch processing\n- Performance optimization\n\n**Key concepts**: Parallel execution, sequences, batch size, throughput optimization\n\n---\n\n### 6. **Coding** - Streaming & Response Control\n`coding\u002F` | [Code](examples\u002F06_coding\u002Fcoding.js) | [Code Explanation](examples\u002F06_coding\u002FCODE.md) | [Concepts](examples\u002F06_coding\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Real-time streaming responses\n- Token limits and budget management\n- Progressive output display\n- User experience optimization\n\n**Key concepts**: Streaming, token-by-token generation, response control, real-time feedback\n\n---\n\n### 7. **Simple Agent** - Function Calling (Tools)\n`simple-agent\u002F` | [Code](examples\u002F07_simple-agent\u002Fsimple-agent.js) | [Code Explanation](examples\u002F07_simple-agent\u002FCODE.md) | [Concepts](examples\u002F07_simple-agent\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Function calling \u002F tool use fundamentals\n- Defining tools the LLM can use\n- JSON Schema for parameters\n- How LLMs decide when to use tools\n\n**Key concepts**: Function calling, tool definitions, agent decision making, action-taking\n\n**This is where text generation becomes agency!**\n\n---\n\n### 8. **Simple Agent with Memory** - Persistent State\n`simple-agent-with-memory\u002F` | [Code](examples\u002F08_simple-agent-with-memory\u002Fsimple-agent-with-memory.js) | [Code Explanation](examples\u002F08_simple-agent-with-memory\u002FCODE.md) | [Concepts](examples\u002F08_simple-agent-with-memory\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Persisting information across sessions\n- Long-term memory management\n- Facts and preferences storage\n- Memory retrieval strategies\n\n**Key concepts**: Persistent memory, state management, memory systems, context augmentation\n\n---\n\n### 9. **ReAct Agent** - Reasoning + Acting\n`react-agent\u002F` | [Code](examples\u002F09_react-agent\u002Freact-agent.js) | [Code Explanation](examples\u002F09_react-agent\u002FCODE.md) | [Concepts](examples\u002F09_react-agent\u002FCONCEPT.md)\n\n**What you'll learn:**\n- ReAct pattern (Reason → Act → Observe)\n- Iterative problem solving\n- Step-by-step tool use\n- Self-correction loops\n\n**Key concepts**: ReAct pattern, iterative reasoning, observation-action cycles, multi-step agents\n\n**This is the foundation of modern agent frameworks!**\n\n---\n\n### 10. **AoT Agent** - Atom of Thought Planning\n`aot-agent\u002F` | [Code](examples\u002F10_aot-agent\u002Faot-agent.js) | [Code Explanation](examples\u002F10_aot-agent\u002FCODE.md) | [Concepts](examples\u002F10_aot-agent\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Atom of Thought methodology\n- Atomic planning for multi-step computations\n- Dependency management between operations\n- Structured JSON output for reasoning plans\n- Deterministic execution of plans\n\n**Key concepts**: AoT planning, atomic operations, dependency resolution, plan validation, structured reasoning\n\n---\n\n### 11. **Error Handling** - Resilience for LLM + Tools\n`error-handling\u002F` | [Code](examples\u002F11_error-handling\u002Ferror-handling.js) | [Code Explanation](examples\u002F11_error-handling\u002FCODE.md) | [Concepts](examples\u002F11_error-handling\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Typed error taxonomy (validation, LLM, tools, workflow) with stable codes\n- Timeouts, retries with backoff\u002Fjitter, and classifying transient failures\n- Graceful degradation when the LLM path fails (deterministic tool fallback)\n- Orchestration-level errors (`AgentWorkflowError`) and correlation ids for support\n\n**Key concepts**: Error taxonomy, retry policies, timeouts, fallbacks, degraded mode, observability, user-safe messaging\n\n---\n\n### 12. **Tree of Thought** - Search over reasoning branches\n`tree-of-thought\u002F` | [Code](examples\u002F12_tree-of-thought\u002Ftree-of-thought.js) | [Code Explanation](examples\u002F12_tree-of-thought\u002FCODE.md) | [Concepts](examples\u002F12_tree-of-thought\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Generating multiple candidate next actions from the same partial plan\n- Ranking and pruning branches with a deterministic score in code\n- Running a compact beam search loop with inspectable kept\u002Fpruned decisions\n- Verifying the winning path with explicit sanity checks\n\n**Key concepts**: Tree of Thought, beam search, branch pruning, verifiable objectives, search controllers\n\n---\n\n### 13. **Graph of Thought** - DAG merge for multi-source outputs\n`graph-of-thought\u002F` | [Code](examples\u002F13_graph-of-thought\u002Fgraph-of-thought.js) | [Code Explanation](examples\u002F13_graph-of-thought\u002FCODE.md) | [Concepts](examples\u002F13_graph-of-thought\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Modeling reasoning as a DAG: parallel source extracts → merge rules → final draft\n- Resolving conflicts explicitly before generation (`must_include`, `must_avoid`, `conflict_notes`)\n- Adding deterministic merge and draft compliance checks\n- Running independent nodes in parallel to reduce latency\n\n**Key concepts**: Graph of Thought, DAG orchestration, multi-source fusion, merge-before-generate, policy reconciliation\n\n**Decision guide**: use ToT when you need to search competing paths; use GoT when you need to combine multiple sources into one consistent policy. Compare both in:\n- [ToT concept](examples\u002F12_tree-of-thought\u002FCONCEPT.md)\n- [GoT concept](examples\u002F13_graph-of-thought\u002FCONCEPT.md)\n\n---\n\n### 14. **Chain of Thought** - Auditable stepwise decisioning\n`chain-of-thought\u002F` | [Code](examples\u002F14_chain-of-thought\u002Fchain-of-thought.js) | [Code Explanation](examples\u002F14_chain-of-thought\u002FCODE.md) | [Concepts](examples\u002F14_chain-of-thought\u002FCONCEPT.md)\n\n**What you'll learn:**\n- Splitting a high-stakes decision into explicit reasoning phases\n- Preventing early bias with a facts-only extraction step\n- Balancing fraud signals with legitimacy evidence before policy application\n- Producing an auditable final decision with customer-safe and internal outputs\n\n**Key concepts**: Chain of Thought, structured reasoning traces, policy-constrained decisions, explainability, review-ready workflows\n\n---\n\n## Documentation Structure\n\nEach example folder contains:\n\n- **`\u003Cname>.js`** - The working code example\n- **`CODE.md`** - Step-by-step code explanation\n- Line-by-line breakdowns\n- What each part does\n- How it works\n- **`CONCEPT.md`** - High-level concepts\n- Why it matters for agents\n- Architectural patterns\n- Real-world applications\n- Simple diagrams\n\n## Core Concepts\n\n### What is an AI Agent?\n\n```\nAI Agent = LLM + System Prompt + Tools + Memory + Reasoning Pattern\n           ─┬─   ──────┬──────   ──┬──   ──┬───   ────────┬────────\n            │          │           │       │              │\n         Brain      Identity    Hands   State         Strategy\n```\n\n### Evolution of Capabilities\n\n```\n1. intro          → Basic LLM usage\n2. translation    → Specialized behavior (system prompts)\n3. think          → Reasoning ability\n4. batch          → Parallel processing\n5. coding         → Streaming & control\n6. simple-agent   → Tool use (function calling)\n7. memory-agent   → Persistent state\n8. react-agent    → Strategic reasoning + tool use\n```\n\n### Architecture Patterns\n\n**Simple Agent (Steps 1-5)**\n```\nUser → LLM → Response\n```\n\n**Tool-Using Agent (Step 6)**\n```\nUser → LLM ⟷ Tools → Response\n```\n\n**Memory Agent (Step 7)**\n```\nUser → LLM ⟷ Tools → Response\n       ↕\n     Memory\n```\n\n**ReAct Agent (Step 8)**\n```\nUser → LLM → Think → Act → Observe\n       ↑      ↓      ↓      ↓\n       └──────┴──────┴──────┘\n           Iterate until solved\n```\n\n## ️ Helper Utilities\n\n### PromptDebugger\n`helper\u002Fprompt-debugger.js`\n\nUtility for debugging prompts sent to the LLM. Shows exactly what the model sees, including:\n- System prompts\n- Function definitions\n- Conversation history\n- Context state\n\nUsage example in `simple-agent\u002Fsimple-agent.js`\n\n## ️ Project Structure - Fundamentals\n\n```\nai-agents\u002F\n├── README.md                          ← You are here\n├─ examples\u002F\n├── 01_intro\u002F\n│   ├── intro.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 02_openai-intro\u002F\n│   ├── openai-intro.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 03_translation\u002F\n│   ├── translation.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 04_think\u002F\n│   ├── think.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 05_batch\u002F\n│   ├── batch.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 06_coding\u002F\n│   ├── coding.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 07_simple-agent\u002F\n│   ├── simple-agent.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 08_simple-agent-with-memory\u002F\n│   ├── simple-agent-with-memory.js\n│   ├── memory-manager.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 09_react-agent\u002F\n│   ├── react-agent.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 10_aot-agent\u002F\n│   ├── aot-agent.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 11_error-handling\u002F\n│   ├── error-handling.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 12_tree-of-thought\u002F\n│   ├── tree-of-thought.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 13_graph-of-thought\u002F\n│   ├── graph-of-thought.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── 14_chain-of-thought\u002F\n│   ├── chain-of-thought.js\n│   ├── CODE.md\n│   └── CONCEPT.md\n├── helper\u002F\n│   └── prompt-debugger.js\n├── models\u002F                             ← Place your GGUF models here\n└── logs\u002F                               ← Debug outputs\n```\n\n## Additional Resources\n\n- **node-llama-cpp**: [GitHub](https:\u002F\u002Fgithub.com\u002Fwithcatai\u002Fnode-llama-cpp)\n- **Model Hub**: [Hugging Face](https:\u002F\u002Fhuggingface.co\u002Fmodels?library=gguf)\n- **GGUF Format**: Quantized models for local inference\n\n## Contributing\n\nThis is a learning resource. Feel free to:\n- Suggest improvements to documentation\n- Add more example patterns\n- Fix bugs or unclear explanations\n- Share what you built!\n\n## License\n\nEducational resource - use and modify as needed for learning.\n\n---\n\n**Built with ❤️ for people who want to truly understand AI agents**\n\nStart with `intro\u002F` and work your way through. Each example builds on the previous one. Read both CODE.md and CONCEPT.md for full understanding.\n\nHappy learning! \n","该项目旨在通过从零开始构建AI代理来揭示其工作原理，使用本地语言模型（LLM）和node-llama-cpp技术，帮助开发者深入理解AI代理的核心机制。项目强调在实际应用框架前先掌握基础概念和技术细节，包括函数调用、记忆管理和ReAct模式等核心功能。适合那些希望深入了解AI代理内部运作机制的学习者或开发者，尤其是对LLM与工具集成感兴趣的人员。通过逐步实践提供的示例代码，参与者能够建立起从基本的LLM交互到复杂代理架构的知识体系，为将来更高效地利用现成框架打下坚实的基础。",2,"2026-06-11 03:43:11","high_star"]