@antiAIvo: I’ve turned my earlier “Writing an Agent from Scratch” tutorial into an open-source GitHub project: NamiAgent. This isn’t just a tutorial—it’s also an Agent you can run on your computer: read and write files in a designated workspace, execute commands, connect to MCP, and remember who you are. Before writing files or running commands…
Summary
The author has turned the “Build an Agent from Scratch” tutorial into NamiAgent, an open-source project that serves as both an 11-lesson tutorial with text, images, and code and a locally runnable Agent. It supports reading and writing files, executing commands, MCP integration, long-term memory, and web-based visualization, with only one dependency: the openai package.
View Cached Full Text
Cached at: 10/31/26, 07:26 AM
I’ve organized the “Building an Agent from Scratch” tutorial I wrote earlier into an open-source GitHub project: NamiAgent. This isn’t just a tutorial—it’s also an Agent you can run on your computer: read and write files within a designated workspace, execute commands, connect to MCP, and remember who you are. It asks before writing files or running commands, and only proceeds with your approval. It also comes with a local web interface: on the left, see its reasoning at each step and which tools it calls; on the right, see the complete context sent to the model each time and how it grows with each loop. All 18 illustrated articles and the code for 11 lessons are included, with one directory per lesson, ready to run. The tutorial starts with a minimal 100-line loop and adds one capability per lesson: tools, permissions, context management, Skills, MCP, subagents, planning, and memory. The final 7 articles use these components as a yardstick to examine Claude Code, Codex, Pi, Grok, DeepSeek Harness, and OpenClaw. It depends on just one package, openai, and uses no Agent framework. The previous project, NamiGPT, explains the model itself; this one explains how to give the model hands and feet. — # aa1143/NamiAgent Source: https://github.com/aa1143/NamiAgent # NamiAgent A beginner-friendly introduction to AI Agents, with no prior knowledge required More than a tutorial: an Agent you can run locally, with a built-in web interface that makes every step visible. test (https://github.com/aa1143/NamiAgent/actions/workflows/test.yml) Python (https://www.python.org/) Code License Docs License Tutorial (https://namiai.tech/agent/) GitHub stars (https://github.com/aa1143/NamiAgent/stargazers) X (https://x.com/antiAIvo) Illustrated tutorial (https://namiai.tech/agent/) · Quick Start · Online visualization (https://namiai.tech/matrix/agent/) · Author on X (https://x.com/antiAIvo) Write hello.py and run it: confirmation dialogs appear before writing files or running commands. Long-term memory: it still remembers who you are in a new session. There’s nothing mysterious about an Agent. At its core, it’s a while loop: call the model, execute tools, write the results back into the context, then call the model again. It’s a tutorial: start with a minimal 100-line loop and add one capability per lesson: tools, permissions, context management, Skills, MCP, subagents, planning, and memory. Finally, examine how mainstream Agents such as Claude Code and Codex work. I put this material together by learning and experimenting hands-on, step by step. It’s also a usable local Agent: it reads and writes files within your designated workspace, executes commands, connects to MCP, and remembers who you are; it asks before writing files or running commands. Run python web/app.py to open the web interface. On the left, see its reasoning at each step and which tools it calls; on the right, see the complete context sent to the model each time. - A runnable snapshot for every lesson: from lessons/lesson-01 to lesson-11, each directory contains the complete code as it stands at the end of that lesson. Run it directly or compare the differences between adjacent lessons. - No vendor lock-in: uses an OpenAI-compatible API, with DeepSeek as the default. Switching models requires changing just two environment variables. - Free to test: every lesson from Lesson 3 onward includes tests, with 49 in Lesson 11. They use a fake model and require no API key. - Just one dependency, openai: no Agent framework. - Local web interface: see every step in your browser—how the context grows, the model’s reasoning, and which tools it calls—all at a glance (see below). > Start with NamiGPT (https://github.com/aa1143/NamiGPT) to understand the model itself, then learn NamiAgent to understand everything around it. ## Course Contents ### Part 1: Building the Core from Scratch | Lesson | Article | Code | What This Lesson Adds | |—|—|—|—| | 01 | Minimal Loop | lesson-01 | agent.py: three tools + a while loop | | 02 | Tool System | lesson-02 | tools.py: registry, unified executor | | 03 | Permissions | lesson-03 | permissions.py: hard rules → risk levels → human confirmation | | 04 | Context Management | lesson-04 | context.py: truncation → cleanup → summarization, session persistence | | 05 | Skills | lesson-05 | skills.py: AGENTS.md always loaded, skills loaded on demand | | 06 | Connecting to Chat Apps | lesson-06 | telegram.py, bot.py: persistent operation, confirmation via chat, allowlist | | 07 | Scheduled Tasks and Heartbeats | lesson-07 | scheduler.py: preauthorization for unattended operation, heartbeats | ### Part 2: Adding Mainstream Capabilities | Lesson | Article | Code | What This Lesson Adds | |—|—|—|—| | 08 | MCP | lesson-08 | mcp_client.py: stdio MCP client | | 09 | Subagents and Multiple Agents | lesson-09 | subagent.py: independent contexts, parallel read-only operation | | 10 | Planning | lesson-10 | planning.py: to-do lists, plan mode with read-only access enforced by code | | 11 | Memory | lesson-11 | memory.py: long-term memory (confirmation for each entry), session search | ### Part 3: Examining Mainstream Agents (Articles Only, No New Code) | Lesson | Article | |—|—| | 12 | Inside Claude Code | | 13 | Inside Codex | | 14 | Inside Pi | | 15 | Inside Grok Bot | | 16 | Inside DeepSeek Harness | | 17 | Inside OpenClaw and Hermes | | 18 | Overall Comparison Table | > Part 3 reflects the state of these products as of October 2026. They change rapidly; consult their respective official documentation for details. ## Companion Visualization How Agents Work (https://namiai.tech/matrix/agent/): 10 chapters, played frame by frame, showing how the context grows with each loop, where things go wrong, and what various Agent techniques actually do within the context. Below is Chapter 3, best viewed alongside Lesson 1: ## Quick Start Requires Python 3.10+. bash git clone https://github.com/aa1143/NamiAgent.git cd NamiAgent pip install -r requirements.txt export API_KEY=your_model_api_key # Uses DeepSeek by default; to use another OpenAI-compatible model: # export BASE_URL=https://... MODEL=model_name export NAMI_WORKSPACE=~/agent-workspace # From Lesson 3 onward, the Agent can only operate within this directory mkdir -p $NAMI_WORKSPACE cd lessons/lesson-05 python agent.py Run tests (no API key required): bash cd lessons/lesson-11 && pytest -q ## Web Interface: See Every Step of the Agent in Your Browser The two animations at the top of the page are actual recordings of the web interface in action. bash python web/app.py --demo # Demo mode: a scripted fake model, no API key required; try it out first python web/app.py # Uses a real model; reads API_KEY / BASE_URL / MODEL just like the command-line version On macOS, you can also double-click web/start.command: it automatically creates a virtual environment, installs dependencies, prompts you to paste your API key (press Enter for demo mode), then opens your browser. The Agent’s default workspace is ~/agent-workspace. Then open http://localhost:8765 : - Left: every model call, the model’s reasoning, which tools it calls, and what the tools return - Right: the complete context sent to the model for this call. See who wrote each block, roughly how many tokens it takes up, and how it grows with each loop - Permission confirmation: operations with side effects, such as writing files and running commands, trigger a dialog and require your approval before execution (the rules from Lesson 3) - Start with /plan to have it produce a plan first, then begin work after approval (Lesson 10) The web interface directly imports the Agent from lessons/lesson-11, without changing the lesson code, replacing only three interfaces: the model client (pushes the context of each request to the browser), handle_call (pushes tool calls to the browser), and the permission confirmation function ask (replaces terminal input() with a dialog). It uses only the Python standard library, so no web framework needs to be installed. DeepSeek has thinking mode enabled by default, and the reasoning returned by the model (reasoning_content) is displayed separately. When tool calls are involved, this reasoning must be placed back into the context unchanged before sending it to the API; it is also visible in the context panel on the right. The reasoning shown in the interface is merely text written by the model, and does not represent the model’s actual internal computation. ## Environment Variables | Variable | Purpose | Default | |—|—|—| | API_KEY | Model API key | Required | | BASE_URL | OpenAI-compatible API endpoint | https://api.deepseek.com | | MODEL | Model name | deepseek-flash | | NAMI_WORKSPACE | Agent workspace (from Lesson 3 onward) | Directory from which it was launched | | NAMI_STATE_DIR | State such as session history and scheduled tasks (from Lesson 4 onward), stored outside the workspace | ~/.nami-agent | From Lesson 6 onward, bot.py also requires TG_BOT_TOKEN and TG_ALLOWED_USERS; see Lesson 6. From Lesson 8 onward, you can connect to MCP servers, with configuration stored in ~/.nami-agent/mcp.json; see Lesson 8 for the format. ## Safety Notice This is educational code. The Agent really executes commands and reads and writes files. The permission mechanism in Lesson 3 can prevent accidental operations and simple attempts to cross boundaries, but cannot stop deliberate attacks (Section 8 of Lesson 3 specifically covers what it cannot protect against). Please run it in a dedicated workspace directory, and do not set your home directory as the workspace. ## What This Repository Is Not NamiAgent is a minimal Agent you can understand, not a production-grade framework, and it does not aim to compete with Claude Code or Codex on features. The goal is that, after reading it, you can look at any Agent product and understand what it does within the context. ## Related - NamiGPT (https://github.com/aa1143/NamiGPT): build GPT-2 from scratch - Illustrated Large Language Models (https://namiai.tech/matrix/): frame-by-frame visualizations covering inference, training, and Agents - Building an Agent from Scratch, illustrated edition (https://namiai.tech/agent/) ## License The code is licensed under MIT, and the articles under docs/ are licensed under CC BY-NC 4.0.
Similar Articles
@antiAIvo: Want to learn how to code with an AI Agent? One of the best free tutorials is Stanford’s CS146S The Modern Software Developer. The instructor, Mihail Eric, isn’t an ivory-tower professor. He came out of Stanford’s NLP group and worked on Alexa…
Recommend Stanford’s free course CS146S, “The Modern Software Developer” (taught by Mihail Eric), and introduce the accompanying open-source project NamiAgent—a Chinese-language tutorial on building an AI agent from scratch, progressively implementing core capabilities such as tools, permissions, context, Skills, MCP, sub-agents, and memory, complete with web-based visual debugging.
@antiAIvo: How to Handwrite an Agent from Scratch? I Put Together an Agent Tutorial in 18 Parts Coding agents like Claude Code and Codex are really just a loop at their core: The model requests tools, code executes, the result goes back into the conversation, until the model stops requesting This tutorial starts from 100 lines of code and builds up layer by layer in Python:...
Shared a complete 18-part handwritten Agent tutorial, starting from 100 lines of Python and progressively building tool calling, permissions, context management, Skills, chat platform integrations, scheduled tasks, MCP, sub-Agents, planning, and memory. Each lesson also compares how mainstream Agents like Claude Code, Codex, Grok Bot, and DeepSeek Harness approach the same problems. The biggest takeaway: mainstream products mostly diverge on one question — should the security layer be handled by prompts or by code?
@yibie: Every programmer should hand-write an agent. It only takes about 50 lines of code, it's fun, and it will surprise you. But to get the most out of it, do these two things: First, write it from scratch. Open a blank text file and type every line yourself. Don't use any AI, not even autocomplete. Second, rely only on the standard library documentation…
This article encourages programmers to manually write a simple AI agent (around 50 lines of code) to deepen their understanding of how agents work, and suggests writing it from scratch while relying only on standard library and API documentation.
@XAMTO_AI: Want to write a coding agent yourself? You've read plenty of articles about the principles, but you get stuck at the first line when you actually start. Recently I found the Chinese tutorial *Hands-On Pi*, which starts with a real offline agent log and takes you through all 15 levels from the beginning. Truly build a complete coding agent from scratch—every step has runnable code...
Introduces the Chinese tutorial *Hands-On Pi*, covering the step-by-step implementation of a Pi-style coding agent from scratch through 15 runnable checkpoints, including protocols, tool loops, conversation tree storage, context compression, and evaluation. Each chapter comes with the main text, a corresponding commit, tests, and failure experiments.
@vintcessun: Tonight I came across a learning roadmap project that redefined where to start learning Agent. I used to think Agent was just a pile of tools and frameworks, but its core is the "observe-think-execute" loop and the harness engineering's organization of permissions, state, and backtracking. It breaks down learning into building a minimal Agent loop from scratch all the way to deploying a real Agent, with 8 stages, each with clear deliverables and recommended resources — not just links but an actionable todo list. This systematic approach made me realize my previous learning was too fragmented.
An open-source learning roadmap project called Agent-Learning-Hub, which breaks down AI Agent learning into 8 stages from building a minimal Agent loop to production deployment, providing executable todo lists and recommended resources, maintained by members of the Datawhale community.