aa1143/NamiAgent

What is it?

Key features

• 01Builds an agent step by step in 11 lessons, each a runnable code snapshot
• 02Supports tools, permission confirmation, context compression and session persistence
• 03Includes MCP client support over stdio and sub-agents with independent context
• 04Browser UI shows each model call, tool call and the full context per turn
• 05Uses any OpenAI-compatible API, defaulting to DeepSeek, with only the openai package as dependency
• 06Lessons 3 onward include tests that run without an API key

Use cases

• Learning how agent loops, tools and context management work from the ground up
• Reading the code side by side with lessons to compare consecutive stages
• Running a small local agent in a dedicated workspace with confirmation prompts
• Studying how commercial coding agents are structured through the included breakdowns

Quick start

1. 1

   Clone the repository

   git clone https://github.com/aa1143/NamiAgent.git
2. 2

   Enter the project and install dependencies

   cd NamiAgent && pip install -r requirements.txt
3. 3

   Set your model API key and create the workspace

   export API_KEY=你的模型密钥 && export NAMI_WORKSPACE=~/agent-workspace && mkdir -p $NAMI_WORKSPACE
4. 4

   Run the lesson 5 agent

   cd lessons/lesson-05 && python agent.py

Things to know

• !Requires a model API key; the default is DeepSeek.
• !Agent can execute commands and read or write files, so it should run in a dedicated workspace.
• !It is a teaching project, not a production-grade agent framework.
• !Documentation under docs/ is licensed CC BY-NC 4.0, which is non-commercial.

In collections

Topics

FAQ

What is NamiAgent?

A Chinese-language tutorial that builds a minimal AI agent from scratch in 11 lessons, with a runnable local agent and browser UI. NamiAgent is a beginner-oriented tutorial for building AI agents from scratch, paired with a small local agent you can run yourself. The core idea it teaches is a while loop: call the model, execute tools, write results back into the context, and call the model again. Lessons start from a roughly 100-line minimal loop and add one capability at a time, including tools, permissions, context management, Skills, MCP, sub-agents, planning, and long-term memory. A final part walks through how Claude Code, Codex and other mainstream agents are structured.

Is NamiAgent free to use? What license does it have?

NamiAgent is open source under the MIT license. Check the license terms before using it in commercial products.

Is NamiAgent still maintained?

Actively maintained. The last commit to NamiAgent was on Oct 30, 2026.

What can I use NamiAgent for?

Learning how agent loops, tools and context management work from the ground up Reading the code side by side with lessons to compare consecutive stages Running a small local agent in a dedicated workspace with confirmation prompts Studying how commercial coding agents are structured through the included breakdowns

How do I install NamiAgent?

Clone the repository: git clone https://github.com/aa1143/NamiAgent.git Enter the project and install dependencies: cd NamiAgent && pip install -r requirements.txt Set your model API key and create the workspace: export API_KEY=你的模型密钥 && export NAMI_WORKSPACE=~/agent-workspace && mkdir -p $NAMI_WORKSPACE Run the lesson 5 agent: cd lessons/lesson-05 && python agent.py

Where can I get NamiAgent?

The source code and installation instructions are on GitHub: https://github.com/aa1143/NamiAgent