Exploring nanobot: A Lightweight 4,000-Line Python Framework for AI Agent Pipelines

A Coding Guide to Exploring nanobot’s Full Agent Pipeline, from Wiring Up Tools and Memory to Skills, Subagents, and Cron Scheduling

The nanobot framework from HKUDS packs a full AI agent architecture into approximately 4,000 lines of Python code. It enables developers to implement complex multi-step pipelines including memory persistence, tool calling, and background task delegation using models like gpt-4o-mini.

Why This Matters

While many AI agent frameworks are bloated with complex abstractions, nanobot demonstrates that production-grade capabilities can be achieved with minimal overhead. This lightweight approach reduces the cost and complexity of deploying agents that require long-term context and the ability to spawn autonomous subagents for specialized tasks, proving that a ReAct-style architecture can be efficiently managed in a small codebase.

Key Insights

• The nanobot Agent Loop (loop.py) iterates up to 40 times to process context, call the LLM, and execute tools until a final answer is reached (2026).
• Memory persistence is handled via a dual-storage system using MEMORY.md for long-term facts and daily YYYY-MM-DD.md journal entries for recent context.
• The Skills System (skills.py) utilizes Markdown files to define specialized agent behaviors like data analysis or code review that can be loaded on demand.
• SubagentManager (agent/subagent.py) allows the primary agent to delegate tasks to background workers that run independent LLM loops concurrently.
• CronService (cron/service.py) integrates APScheduler to trigger automated agent actions, such as memory consolidation or status updates, based on defined intervals.

Working Examples

Manual recreation of the nanobot agent loop logic for tool calling and context assembly.

def agent_loop(user_message: str, max_iterations: int = 10):\n    system_parts = []\n    for md_file in [\"AGENTS.md\", \"SOUL.md\", \"USER.md\"]:\n        fpath = WORKSPACE / md_file\n        if fpath.exists():\n            system_parts.append(fpath.read_text())\n    system_prompt = \"\\n\\n\".join(system_parts)\n    messages = [{\"role\": \"system\", \"content\": system_prompt}, {\"role\": \"user\", \"content\": user_message}]\n    for iteration in range(1, max_iterations + 1):\n        response = client.chat.completions.create(model=\"gpt-4o-mini\", messages=messages, tools=TOOLS, tool_choice=\"auto\")\n        message = response.choices[0].message\n        if message.tool_calls:\n            messages.append(message.model_dump())\n            for tc in message.tool_calls:\n                result = execute_tool(tc.function.name, json.loads(tc.function.arguments))\n                messages.append({\"role\": \"tool\", \"tool_call_id\": tc.id, \"content\": result})\n        else:\n            return message.content

Practical Applications

• Use Case: Implementing a ‘Code Reviewer’ skill to automatically rate code quality on a 1-10 scale. Pitfall: Allowing subagents to spawn further subagents, which can cause infinite recursion and API cost spikes.
• Use Case: Using the CronService to run a daily ‘memory_cleanup’ job that summarizes and compresses old journal entries. Pitfall: Failing to restrict tool access to the workspace directory, potentially exposing sensitive system files.
• Use Case: Multi-turn session management for persistent chat history across different communication channels like Telegram or Discord. Pitfall: Hard-coding API keys in the config.json instead of using secure environment variables.

References:

• https://www.marktechpost.com/2026/03/28/a-coding-guide-to-exploring-nanobots-full-agent-pipeline-from-wiring-up-tools-and-memory-to-skills-subagents-and-cron-scheduling/
• https://github.com/HKUDS/nanobot