一天一个开源项目（第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 # 定义工具函数defget_weather(location:str)->str:"""Get weather information for a location."""# 实际的天气 API 调用returnf"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？

• 🎯 专注核心：专注于 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. 可扩展性

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

# 自定义 AgentclassCustomAgent(Agent):defcustom_method(self):# 自定义逻辑pass# 自定义工具classCustomTool(Tool):defexecute(self,input):# 自定义执行逻辑pass

核心模块

1. Agent 核心模块

功能：

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

技术实现：

classAgent: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 =[]defchat(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 判断是否需要调用工具# 返回工具调用列表passdef_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. 工具系统模块

功能：

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

技术实现：

classTool: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{}defexecute(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)}defto_openai_format(self)->dict:# 转换为 OpenAI 函数调用格式return{"type":"function","function":{"name": self.name,"description": self.description,"parameters": self.parameters }}

3. 规划器模块

功能：

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

技术实现：

classPlanner:def__init__(self, llm: LLM): self.llm = llm defplan(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:returnf""" 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. 记忆管理模块

功能：

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

技术实现：

classSimpleMemory:def__init__(self, max_history:int=100): self.max_history = max_history self.history =[]defadd(self, role:str, content:str): self.history.append({"role": role,"content": content,"timestamp": time.time()})# 限制历史长度iflen(self.history)> self.max_history: self.history = self.history[-self.max_history:]defget_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 =0for message inreversed(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 提供商支持
• 统一的接口抽象
• 流式响应处理

技术实现：

classLLM: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)# 支持更多提供商...defchat( 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)defchat_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. 检查是否有工具调用ifhasattr(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. 规划与执行循环

defexecute_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. 上下文窗口优化

defoptimize_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

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

自定义工具

classDatabaseTool(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)}

自定义规划器

classHierarchicalPlanner(Planner):defplan(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: https://github.com/HKUDS/nanobot
• 📚 文档: 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 集成和多提供商支持
• ✅ 代码简洁性和可维护性

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