一天一个开源项目（第20篇）：NanoBot - 轻量级AI Agent框架，极简高效的智能体构建工具

引言

"大道至简------最强大的工具往往拥有最简单的接口。"

这是"一天一个开源项目"系列的第20篇文章。今天带你了解的项目是 NanoBot （GitHub）。

在 AI Agent 框架领域，LangChain、CrewAI 等框架功能强大但学习曲线陡峭，对于快速原型开发和小型项目来说可能过于复杂。NanoBot 应运而生，它是一个轻量级、极简的 AI Agent 框架，由香港大学数据科学实验室（HKUDS）开发。NanoBot 专注于提供简洁的 API、灵活的架构和强大的扩展能力，让开发者能够快速构建和部署 AI 智能体，而无需陷入复杂的配置和抽象层。

为什么选择这个项目？

• 🪶 轻量级设计：极简的代码库，易于理解和定制
• 🚀 快速上手：简洁的 API，几分钟内即可构建第一个 Agent
• 🔧 灵活架构：模块化设计，按需扩展功能
• 🎯 专注核心：专注于 Agent 的核心能力，避免过度设计
• 🏫 学术背景：来自香港大学数据科学实验室，有扎实的理论基础
• 📦 易于集成：可以轻松集成到现有项目中
• 🔌 扩展性强：支持自定义工具、记忆、规划器等组件

你将学到什么

• NanoBot 的核心架构和设计理念
• 如何快速构建和部署 AI Agent
• Agent 的规划、执行、工具使用等核心机制
• 如何扩展和定制 Agent 功能
• 与其他 AI Agent 框架的对比分析
• 实际应用场景和最佳实践
• 轻量级框架的设计思路

前置知识

• 对 AI Agent 概念有基本了解
• 熟悉 Python 编程
• 了解 LLM（大语言模型）的基本使用
• 对函数调用（Function Calling）有基本认识（可选）

---

项目背景

项目简介

NanoBot 是一个轻量级、极简的 AI Agent 框架，由香港大学数据科学实验室（HKUDS - Hong Kong University Data Science）开发。它旨在提供一个简洁、高效、易于使用的框架，让开发者能够快速构建和部署 AI 智能体，而无需处理复杂的配置和抽象层。

项目解决的核心问题：

• 现有 Agent 框架过于复杂，学习曲线陡峭
• 对于小型项目和快速原型，现有框架显得"杀鸡用牛刀"
• 缺乏轻量级、专注核心功能的 Agent 框架
• 开发者需要一个简单但功能完整的 Agent 构建工具
• 学术研究和教学需要一个易于理解和定制的框架

面向的用户群体：

• 需要快速构建 AI Agent 的开发者
• 进行 AI Agent 研究和实验的研究人员
• 希望学习 Agent 框架设计的学生和开发者
• 需要轻量级 Agent 解决方案的小型项目
• 对 Agent 框架内部实现感兴趣的技术人员

作者/团队介绍

团队：HKUDS（Hong Kong University Data Science）

• 背景：香港大学数据科学实验室，专注于数据科学、机器学习和 AI 系统研究
• 研究方向：数据挖掘、机器学习、AI Agent、推荐系统等
• 理念：构建简洁、高效、易于使用的 AI 工具和框架
• 技术栈：Python、LLM、Agent 系统

项目创建时间：2024-2025年（持续活跃开发中）

项目数据

• ⭐ GitHub Stars: 持续增长中（具体数据以 GitHub 为准）
• 🍴 Forks: 活跃的社区参与
• 📦 版本: 持续更新中
• 📄 License: 开源协议（具体以 GitHub 为准）
• 🌐 项目地址 : GitHub
• 💬 社区: GitHub Issues 和 Discussions
• 📚 文档: 包含使用指南和 API 文档

项目特点：

• 轻量级：代码库精简，核心功能清晰
• 易用性：简洁的 API，快速上手
• 灵活性：模块化设计，易于扩展
• 学术性：来自知名大学实验室，有扎实的理论基础

---

主要功能

核心作用

NanoBot 的核心作用是提供一个轻量级、易用的 AI Agent 框架，主要功能包括：

1. Agent 构建：快速创建和配置 AI Agent
2. 工具集成：支持自定义工具和函数调用
3. 规划与执行：Agent 的规划、执行和反思机制
4. 记忆管理：短期和长期记忆支持
5. 多 Agent 协作：支持多个 Agent 协同工作（如有）
6. LLM 集成：支持多种 LLM 提供商
7. 流式响应：支持流式输出和实时交互

使用场景

NanoBot 适用于多种 AI Agent 应用场景：

1. 快速原型开发

   • 快速验证 Agent 想法
   • 构建 MVP（最小可行产品）
   • 实验不同的 Agent 架构

2. 研究和教学

   • AI Agent 相关研究
   • 教学和演示 Agent 概念
   • 理解 Agent 框架的内部实现

3. 小型项目

   • 个人项目和小型应用
   • 不需要复杂框架的场景
   • 需要快速部署的 Agent

4. 学习和实验

   • 学习 Agent 框架设计
   • 实验不同的 Agent 能力
   • 理解 Agent 的工作原理

5. 工具集成

   • 将 Agent 集成到现有系统
   • 为应用添加 AI 能力
   • 构建智能助手和自动化工具

快速开始

安装方式

NanoBot 可以通过 pip 安装：

# 方式一：从 GitHub 安装
pip install git+https://github.com/HKUDS/nanobot.git

# 方式二：克隆后本地安装
git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .

# 方式三：如果已发布到 PyPI
pip install nanobot

系统要求：

• Python 3.8+
• 支持的 LLM API（OpenAI、Anthropic 等）

基本使用

1. 创建简单的 Agent

from nanobot import Agent, LLM

# 初始化 LLM
llm = LLM(provider="openai", model="gpt-4")

# 创建 Agent
agent = Agent(
    name="Assistant",
    llm=llm,
    system_prompt="You are a helpful assistant."
)

# 与 Agent 对话
response = agent.chat("Hello, how are you?")
print(response)

2. 添加工具支持

from nanobot import Agent, Tool

# 定义工具函数
def get_weather(location: str) -> str:
    """Get weather information for a location."""
    # 实际的天气 API 调用
    return f"Weather in {location}: Sunny, 25°C"

# 创建工具
weather_tool = Tool(
    name="get_weather",
    description="Get weather information",
    function=get_weather
)

# 创建带工具的 Agent
agent = Agent(
    name="WeatherBot",
    llm=llm,
    tools=[weather_tool]
)

# Agent 可以自动使用工具
response = agent.chat("What's the weather in Hong Kong?")
print(response)

3. 使用规划器

from nanobot import Agent, Planner

# 创建规划器
planner = Planner(llm=llm)

# 创建带规划器的 Agent
agent = Agent(
    name="PlannerBot",
    llm=llm,
    planner=planner
)

# Agent 可以规划复杂任务
response = agent.chat(
    "Plan a trip to Japan: research flights, hotels, and attractions"
)
print(response)

4. 流式响应

# 启用流式响应
for chunk in agent.chat_stream("Tell me a story"):
    print(chunk, end="", flush=True)

核心特性

1. 简洁的 API

   • 直观的接口设计
   • 最少的配置即可开始使用
   • 清晰的代码结构

2. 灵活的架构

   • 模块化设计，组件可替换
   • 支持自定义扩展
   • 易于集成到现有项目

3. 工具系统

   • 轻松定义和使用工具
   • 自动函数调用
   • 工具链组合

4. 规划与执行

   • 内置规划器支持
   • 任务分解和执行
   • 反思和优化机制

5. 记忆管理

   • 对话历史管理
   • 长期记忆支持（如有）
   • 上下文窗口优化

6. 多 LLM 支持

   • 支持多种 LLM 提供商
   • 统一的接口抽象
   • 易于切换模型

7. 流式响应

   • 实时输出支持
   • 提升用户体验
   • 降低延迟感知

8. 易于调试

   • 清晰的日志输出
   • 详细的执行追踪
   • 便于问题定位

项目优势

与其他 AI Agent 框架的对比：

对比项	NanoBot	LangChain	CrewAI	AutoGPT
学习曲线	✅ 极简，快速上手	⚠️ 较陡，概念多	⚠️ 中等，需要理解团队概念	⚠️ 复杂，配置多
代码量	✅ 轻量级，核心精简	⚠️ 大型框架，功能丰富	⚠️ 中等规模	⚠️ 大型项目
灵活性	✅ 高度灵活，易定制	⚠️ 抽象层多，定制复杂	✅ 灵活，支持多 Agent	⚠️ 相对固定
适用场景	✅ 快速原型、小型项目	✅ 生产环境、复杂应用	✅ 多 Agent 协作	✅ 自主 Agent
文档质量	✅ 简洁清晰	✅ 详细全面	✅ 良好	⚠️ 一般
社区支持	⚠️ 新兴项目	✅ 成熟，社区大	✅ 活跃社区	✅ 活跃社区
学术背景	✅ 大学实验室	❌ 商业公司	❌ 商业公司	❌ 社区项目

为什么选择 NanoBot？

• 🎯 专注核心：专注于 Agent 的核心功能，避免过度设计
• 🚀 快速开发：简洁的 API，快速构建和迭代
• 🧠 易于理解：代码清晰，便于学习和定制
• 🏫 学术支持：来自知名大学实验室，有理论支撑
• 🔧 高度可定制：模块化设计，按需扩展
• 📦 轻量级：适合资源受限的场景
• 🎓 学习价值：理解 Agent 框架设计的绝佳材料

---

项目详细剖析

架构设计

NanoBot 采用模块化、可扩展的架构设计，核心组件清晰分离，便于理解和定制。

核心架构

NanoBot/
├── Agent (核心)
│   ├── LLM 接口
│   ├── 工具系统
│   ├── 规划器
│   ├── 记忆管理
│   └── 执行引擎
├── Tools (工具)
│   ├── 内置工具
│   ├── 自定义工具
│   └── 工具链
├── Planner (规划器)
│   ├── 任务分解
│   ├── 步骤规划
│   └── 执行策略
├── Memory (记忆)
│   ├── 对话历史
│   ├── 长期记忆
│   └── 上下文管理
└── LLM (大模型)
    ├── 多提供商支持
    ├── 统一接口
    └── 流式响应

设计原则

1. 简洁性优先

# NanoBot 的设计哲学：最少的代码实现最多的功能
agent = Agent(llm=llm)
response = agent.chat("Hello")

2. 模块化设计

每个组件都是独立的模块，可以单独使用或替换：

# 可以单独使用规划器
planner = Planner(llm=llm)
plan = planner.plan("复杂任务")

# 可以单独使用工具
tool = Tool(name="calculator", function=calculate)
result = tool.execute("2 + 2")

3. 可扩展性

通过继承和组合轻松扩展功能：

# 自定义 Agent
class CustomAgent(Agent):
    def custom_method(self):
        # 自定义逻辑
        pass

# 自定义工具
class CustomTool(Tool):
    def execute(self, input):
        # 自定义执行逻辑
        pass

核心模块

1. Agent 核心模块

功能：

• Agent 的创建和配置
• 对话管理和响应生成
• 工具调用和规划执行
• 状态管理和上下文维护

技术实现：

class Agent:
    def __init__(
        self,
        name: str,
        llm: LLM,
        system_prompt: str = None,
        tools: List[Tool] = None,
        planner: Planner = None,
        memory: Memory = None
    ):
        self.name = name
        self.llm = llm
        self.system_prompt = system_prompt
        self.tools = tools or []
        self.planner = planner
        self.memory = memory or SimpleMemory()
        self.conversation_history = []
    
    def chat(self, message: str) -> str:
        # 1. 添加到对话历史
        self.conversation_history.append({
            "role": "user",
            "content": message
        })
        
        # 2. 如果有规划器，先规划
        if self.planner:
            plan = self.planner.plan(message, self.conversation_history)
            # 执行规划...
        
        # 3. 检查是否需要调用工具
        tool_calls = self._detect_tool_calls(message)
        if tool_calls:
            results = self._execute_tools(tool_calls)
            message = self._format_with_tool_results(message, results)
        
        # 4. 调用 LLM
        response = self.llm.chat(
            messages=self._build_messages(),
            tools=self._format_tools()
        )
        
        # 5. 保存响应
        self.conversation_history.append({
            "role": "assistant",
            "content": response
        })
        
        return response
    
    def _detect_tool_calls(self, message: str) -> List[dict]:
        # 使用 LLM 判断是否需要调用工具
        # 返回工具调用列表
        pass
    
    def _execute_tools(self, tool_calls: List[dict]) -> List[dict]:
        # 执行工具调用
        results = []
        for tool_call in tool_calls:
            tool = self._find_tool(tool_call["name"])
            result = tool.execute(tool_call["arguments"])
            results.append(result)
        return results

2. 工具系统模块

功能：

• 工具的定义和注册
• 工具调用的执行
• 工具链的组合
• 工具结果的格式化

技术实现：

class Tool:
    def __init__(
        self,
        name: str,
        description: str,
        function: Callable,
        parameters: dict = None
    ):
        self.name = name
        self.description = description
        self.function = function
        self.parameters = parameters or {}
    
    def execute(self, **kwargs) -> Any:
        # 验证参数
        self._validate_parameters(kwargs)
        
        # 执行函数
        try:
            result = self.function(**kwargs)
            return {
                "success": True,
                "result": result
            }
        except Exception as e:
            return {
                "success": False,
                "error": str(e)
            }
    
    def to_openai_format(self) -> dict:
        # 转换为 OpenAI 函数调用格式
        return {
            "type": "function",
            "function": {
                "name": self.name,
                "description": self.description,
                "parameters": self.parameters
            }
        }

3. 规划器模块

功能：

• 任务分解和步骤规划
• 执行策略制定
• 计划优化和调整

技术实现：

class Planner:
    def __init__(self, llm: LLM):
        self.llm = llm
    
    def plan(self, task: str, context: List[dict] = None) -> dict:
        # 使用 LLM 生成计划
        prompt = self._build_planning_prompt(task, context)
        
        response = self.llm.chat(
            messages=[{"role": "user", "content": prompt}],
            response_format="json"
        )
        
        plan = json.loads(response)
        return {
            "task": task,
            "steps": plan["steps"],
            "estimated_time": plan.get("estimated_time"),
            "dependencies": plan.get("dependencies", [])
        }
    
    def _build_planning_prompt(self, task: str, context: List[dict]) -> str:
        return f"""
        Given the following task, create a detailed plan:
        
        Task: {task}
        
        Context: {json.dumps(context, indent=2) if context else "None"}
        
        Please provide a JSON response with:
        - steps: List of steps to complete the task
        - estimated_time: Estimated time for each step
        - dependencies: Dependencies between steps
        """

4. 记忆管理模块

功能：

• 对话历史管理
• 上下文窗口优化
• 长期记忆存储（如有）

技术实现：

class SimpleMemory:
    def __init__(self, max_history: int = 100):
        self.max_history = max_history
        self.history = []
    
    def add(self, role: str, content: str):
        self.history.append({
            "role": role,
            "content": content,
            "timestamp": time.time()
        })
        
        # 限制历史长度
        if len(self.history) > self.max_history:
            self.history = self.history[-self.max_history:]
    
    def get_context(self, max_tokens: int = None) -> List[dict]:
        # 返回对话上下文
        if max_tokens:
            # 智能截取，保留重要信息
            return self._truncate_by_tokens(self.history, max_tokens)
        return self.history
    
    def _truncate_by_tokens(self, history: List[dict], max_tokens: int) -> List[dict]:
        # 从最新消息开始，逐步添加直到达到 token 限制
        truncated = []
        current_tokens = 0
        
        for message in reversed(history):
            message_tokens = self._count_tokens(message["content"])
            if current_tokens + message_tokens > max_tokens:
                break
            truncated.insert(0, message)
            current_tokens += message_tokens
        
        return truncated

5. LLM 集成模块

功能：

• 多 LLM 提供商支持
• 统一的接口抽象
• 流式响应处理

技术实现：

class LLM:
    def __init__(self, provider: str, model: str, api_key: str = None):
        self.provider = provider
        self.model = model
        self.api_key = api_key or os.getenv(f"{provider.upper()}_API_KEY")
        self.client = self._create_client()
    
    def _create_client(self):
        if self.provider == "openai":
            import openai
            return openai.OpenAI(api_key=self.api_key)
        elif self.provider == "anthropic":
            import anthropic
            return anthropic.Anthropic(api_key=self.api_key)
        # 支持更多提供商...
    
    def chat(
        self,
        messages: List[dict],
        tools: List[dict] = None,
        response_format: str = None
    ) -> str:
        # 统一的聊天接口
        if self.provider == "openai":
            return self._openai_chat(messages, tools, response_format)
        elif self.provider == "anthropic":
            return self._anthropic_chat(messages, tools, response_format)
    
    def chat_stream(self, messages: List[dict], tools: List[dict] = None):
        # 流式响应
        if self.provider == "openai":
            stream = self.client.chat.completions.create(
                model=self.model,
                messages=messages,
                tools=tools,
                stream=True
            )
            for chunk in stream:
                if chunk.choices[0].delta.content:
                    yield chunk.choices[0].delta.content

关键技术实现

1. 工具自动调用

NanoBot 通过 LLM 的函数调用能力自动检测和执行工具：

def _detect_and_execute_tools(self, message: str, context: List[dict]) -> str:
    # 1. 构建包含工具信息的消息
    messages = self._build_messages_with_tools(context)
    
    # 2. 调用 LLM，启用函数调用
    response = self.llm.chat(
        messages=messages,
        tools=[tool.to_openai_format() for tool in self.tools]
    )
    
    # 3. 检查是否有工具调用
    if hasattr(response, "tool_calls") and response.tool_calls:
        # 4. 执行工具
        tool_results = []
        for tool_call in response.tool_calls:
            tool = self._find_tool(tool_call.function.name)
            result = tool.execute(**json.loads(tool_call.function.arguments))
            tool_results.append({
                "tool_call_id": tool_call.id,
                "role": "tool",
                "name": tool_call.function.name,
                "content": json.dumps(result)
            })
        
        # 5. 将工具结果添加到上下文，再次调用 LLM
        messages.extend(tool_results)
        final_response = self.llm.chat(messages=messages)
        return final_response.content
    
    return response.content

2. 规划与执行循环

def execute_with_planning(self, task: str) -> str:
    # 1. 生成计划
    plan = self.planner.plan(task, self.conversation_history)
    
    # 2. 执行计划中的每个步骤
    results = []
    for step in plan["steps"]:
        # 检查是否需要工具
        if step.get("requires_tool"):
            tool_result = self._execute_tool_for_step(step)
            results.append(tool_result)
        else:
            # 直接使用 LLM
            response = self.llm.chat(
                messages=self._build_messages() + [{
                    "role": "user",
                    "content": step["description"]
                }]
            )
            results.append(response.content)
        
        # 3. 反思和调整（可选）
        if step.get("requires_reflection"):
            reflection = self._reflect_on_step(step, results[-1])
            if reflection["should_adjust"]:
                plan = self._adjust_plan(plan, reflection)
    
    # 4. 总结结果
    summary = self._summarize_execution(plan, results)
    return summary

3. 上下文窗口优化

def optimize_context(self, messages: List[dict], max_tokens: int) -> List[dict]:
    # 策略1: 保留系统提示和最近的对话
    system_messages = [msg for msg in messages if msg["role"] == "system"]
    recent_messages = messages[-10:]  # 保留最近10条
    
    # 策略2: 如果还是超限，使用摘要
    current_tokens = self._count_tokens(system_messages + recent_messages)
    if current_tokens > max_tokens:
        # 对旧消息进行摘要
        old_messages = messages[:-10]
        summary = self._summarize_messages(old_messages)
        
        return system_messages + [
            {"role": "assistant", "content": f"Previous conversation summary: {summary}"}
        ] + recent_messages
    
    return system_messages + recent_messages

扩展机制

自定义 Agent

class CustomAgent(Agent):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.custom_state = {}
    
    def custom_method(self, input_data):
        # 自定义逻辑
        result = self.llm.chat([
            {"role": "user", "content": f"Process: {input_data}"}
        ])
        self.custom_state["last_result"] = result
        return result

自定义工具

class DatabaseTool(Tool):
    def __init__(self, connection_string: str):
        super().__init__(
            name="query_database",
            description="Query a SQL database",
            function=self._query
        )
        self.db = connect(connection_string)
    
    def _query(self, sql: str) -> dict:
        try:
            result = self.db.execute(sql)
            return {
                "success": True,
                "data": result.fetchall(),
                "columns": result.keys()
            }
        except Exception as e:
            return {
                "success": False,
                "error": str(e)
            }

自定义规划器

class HierarchicalPlanner(Planner):
    def plan(self, task: str, context: List[dict] = None) -> dict:
        # 1. 高层次规划
        high_level_plan = self._high_level_planning(task)
        
        # 2. 对每个高层次目标进行详细规划
        detailed_steps = []
        for goal in high_level_plan["goals"]:
            steps = self._detailed_planning(goal)
            detailed_steps.extend(steps)
        
        return {
            "task": task,
            "high_level_goals": high_level_plan["goals"],
            "detailed_steps": detailed_steps
        }

---

项目地址与资源

官方资源

• 🌟 GitHub : github.com/HKUDS/nanob...
• 📚 文档: GitHub README 和 Wiki（如有）
• 💬 社区: GitHub Issues 和 Discussions
• 🐛 Issue Tracker : GitHub Issues

相关资源

• HKUDS 实验室: 香港大学数据科学实验室相关资源
• AI Agent 框架对比: LangChain、CrewAI、AutoGPT 等
• LLM 集成指南: OpenAI、Anthropic 等 LLM 提供商文档

同类项目对比

如果你想了解更多 AI Agent 框架：

• LangChain：功能丰富的 LLM 应用框架
• CrewAI：多 Agent 团队协作框架
• AutoGPT：自主 AI Agent 系统
• AgentGPT：浏览器中的 AI Agent 构建工具
• SuperAGI：开源 AI Agent 开发框架

适用人群

NanoBot 适合以下开发者：

• AI Agent 开发者：需要快速构建和部署 Agent
• 研究人员：进行 Agent 相关研究和实验
• 学生和教师：学习 Agent 框架设计和实现
• 快速原型开发者：需要轻量级框架验证想法
• 框架学习者：希望理解 Agent 框架的内部实现
• 小型项目开发者：不需要复杂框架的场景

学习价值：

• ✅ 轻量级框架的设计思路
• ✅ Agent 核心机制的实现
• ✅ 工具系统和函数调用
• ✅ 规划与执行循环
• ✅ 模块化架构设计
• ✅ LLM 集成和多提供商支持
• ✅ 代码简洁性和可维护性

---

欢迎来我中的个人主页找到更多有用的知识和有趣的产品