Skip to main content
Tool 4 min read

Nanobot: Lightweight AI Agent Framework

Nanobot: ultra-lightweight AI agent framework in 4K lines of code. Multi-provider LLMs, 8+ chat channels, local models, research-ready. Deploy in 2 minutes

Originally published:

GitHub by HKUDS

Ultra-Lightweight AI Agent Framework

Nanobot is a minimalist personal AI assistant framework that delivers full agent capabilities in just ~4,000 lines of Python code—99% smaller than comparable systems. Built for developers and researchers who need production-ready agentic AI without bloat, nanobot prioritizes simplicity, extensibility, and rapid deployment while maintaining research-grade code clarity.

Core Strengths

  • Extreme Minimalism: ~3,500 verified lines of agent logic. Run bash core_agent_lines.sh to audit the codebase anytime.
  • Multi-Provider LLM Support: OpenRouter, DashScope (Qwen), DeepSeek, Moonshot/Kimi, and vLLM for local models. Adding a new provider takes two simple steps.
  • 8+ Communication Channels: Telegram, Discord, WhatsApp, Feishu, DingTalk, Slack, Email, and QQ—deploy via CLI or webhook.
  • Local Model Ready: Run private AI using vLLM or any OpenAI-compatible server with zero external dependencies.
  • Real-Time Task Scheduling: Natural language task automation with intelligent scheduling and execution tracking.
  • Research-Grade Code: Clean, readable architecture designed for understanding, modification, and academic use.

Architecture & Design Philosophy

Nanobot follows a modular agent architecture with three core layers: providers (LLM backends), channels (chat interfaces), and agents (task orchestration). This separation allows developers to swap implementations without touching core logic. The framework emphasizes composition over inheritance—each component is independently testable and deployable.

The ultra-lightweight design doesn't sacrifice functionality. Nanobot supports tool calling, memory management, error recovery, and multi-turn conversations. The codebase is intentionally verbose where it matters (agent logic, task planning) and concise everywhere else (config handling, channel routing).

Getting Started (2 Minutes)

Installation

Three installation options suit different workflows:

  • From Source (Development): git clone https://github.com/HKUDS/nanobot.git && cd nanobot && pip install -e .
  • Via uv (Fast & Stable): uv tool install nanobot-ai
  • Via PyPI (Standard): pip install nanobot-ai

Configuration

Nanobot uses a single JSON configuration file at ~/.nanobot/config.json. For most users, the minimal setup requires an API key from OpenRouter (global), DashScope (Qwen), or a local vLLM server.

Quickest start: Run nanobot onboard for interactive setup, then nanobot agent -m "What is 2+2?" to verify installation.

Local Models with vLLM

Run private inference without external APIs. Start a vLLM server pointing to any Hugging Face model (e.g., Llama 3.1 8B), configure nanobot to target http://localhost:8000, and execute. The apiKey field can be any non-empty string for local servers without authentication.

Multi-Channel Deployment

A single nanobot instance can serve multiple chat platforms simultaneously using the nanobot gateway command. Setup complexity varies by channel:

  • Easy (Token Only): Telegram, Discord, QQ—provide bot token and user IDs from platform settings.
  • Medium (Credentials): WhatsApp (QR scan via Node.js), Feishu (WebSocket, no public IP), DingTalk, Slack, Email (IMAP/SMTP).

Telegram Recommended: Search @BotFather on Telegram, send /newbot, copy the token, and paste into config. This takes 90 seconds.

No Public IP Required: Feishu and QQ use WebSocket long connections, making nanobot deployable on laptops or home networks without port forwarding.

Who Should Use Nanobot

  • AI Researchers: Clear, auditable code for studying agent behavior, prompt engineering, and tool-use patterns.
  • Developers Building Custom Agents: Minimal codebase means faster iteration, easier debugging, and straightforward customization.
  • Education & Workshops: Ideal for teaching agentic AI concepts without overwhelming students with framework complexity.
  • Budget-Conscious Startups: Local model support + multi-provider flexibility enables cost-optimized deployments.
  • Privacy-Focused Teams: Run entirely on-device using vLLM; no data leaves your infrastructure.

Recent Momentum

Nanobot has been actively developed since February 2026, with rapid iteration on provider support, channel integrations, and reliability. Recent releases added Slack/Email/QQ channels, improved provider architecture, Qwen support, local vLLM integration, and enhanced security hardening. The project maintains 206 open issues and 161 pull requests, reflecting active community engagement.

Resource Links

License: MIT — freely usable for personal and commercial projects.

Read original
Share:

Original Source

https://github.com/HKUDS/nanobot

View Original

Last updated: