从零开发一个 AI Agent：4000 行代码，能做出什么？

经常关注开源社区的朋友应该知道，我接下来要讲的项目，就是港大开源的nanobot。但是我不想讲这东西怎么用，也不想讲这东西怎么牛，我就是想说说要是我们自己也从头开始整一个AI Agent，该怎么做？这是「AI Agent 开发实战」系列的第 1 篇，从零开始，自己动手开发一套 AI Agent 系统。

---

一、一个 4000 行代码的项目，凭什么拿下 39000 颗星？

2026 年 2 月，香港大学数据科学实验室（HKUDS）开源了一个叫 nanobot 的项目。

它没有酷炫的 Demo 视频，没有商业公司的推广预算，甚至没有插件市场。但它在两周内拿下了 19000 颗 GitHub Star，到现在已经超过 39000 颗。

为什么？

因为它的核心代码只有 约 4000 行。

作为对比，同样是 AI Agent 框架的 OpenClaw，代码量超过 43 万行。nanobot 只有它的 1%。

这不是「偷工减料」，而是一种哲学：Agent 的核心，应该小到你能读完每一行代码。

主流框架（LangChain、AutoGen、CrewAI）越来越像黑盒——你想搞清楚 Agent 的推理逻辑到底怎么跑的，得穿透十几层抽象。nanobot 的作者洞察到一个本质：

一个 AI Agent 的核心，本质上就是一个消息处理循环。

就这么简单。接收输入 → LLM 分析 → 调用工具 → 输出响应 → 继续循环。

这个系列，就是带你从这行代码开始，一步步搭建出你自己的 AI Agent 系统。（吹的有点儿大，但是吧，我确实是这么想的，哈哈）

---

二、先搞清楚：什么是 AI Agent？

如果你问十个人「什么是 AI Agent」，你会得到十一个答案。

但抛开所有营销话术，Agent 的核心可以用一个循环概括：

思考（Think）→ 行动（Act）→ 观察（Observe）→ 再思考

这就是学术界说的 ReAct 模式（Reasoning + Acting）。

具体来说：

1. 思考：LLM 接收用户消息和上下文，判断该直接回复，还是需要调用工具
2. 行动：如果需要调工具，执行工具调用（比如搜索网页、读写文件、运行代码）
3. 观察：拿到工具返回的结果，把它喂回给 LLM
4. 循环：LLM 基于新信息继续思考，直到给出最终回复

这就是 nanobot 全部核心逻辑的「设计图纸」。后面的所有功能——记忆、多渠道、定时任务、MCP 协议——都是在这个循环上「长」出来的。

记住这个循环。整个系列都围绕它展开。

---

三、开发一个 AI Agent 系统，需要做哪些事？

站在前人的肩膀上，不需要你是个资深工程师。 nanobot 的设计理念就是：如果你能读懂 4000 行 Python 代码，你就能理解和改造它。

📦 5 个核心模块

一个功能完备的 AI Agent 系统，需要这 5 个模块：

模块 1：Agent Loop（核心循环）

这是整个系统的心脏。

它负责管理「思考→行动→观察」的循环流程。具体包括：

• 接收用户消息
• 调用 LLM 获取响应
• 判断响应中是否包含工具调用
• 如果有，执行工具，把结果喂回 LLM
• 如果没有，返回最终回复给用户
• 循环直到任务完成

一句话理解：Agent Loop 就是那个 while True 循环，它是 Agent 能够「自主行动」的根本原因。

模块 2：工具系统（Tool System）

Agent 如果没有工具，就只是个聊天机器人。

工具系统负责：

• 工具注册：定义有哪些工具可用（比如搜索、文件读写、执行命令）
• 工具发现：让 LLM 知道当前有哪些工具可以调用
• 工具执行：接收 LLM 的调用请求，执行对应操作，返回结果

nanobot 内置了 Shell 执行、文件读写、目录浏览等基础工具，还支持通过装饰器自定义工具。更重要的是，它兼容 MCP 协议（Model Context Protocol），可以直接复用整个 MCP 生态中的工具。

一句话理解：工具系统是 Agent 的「手脚」，决定了它能做什么事。

模块 3：记忆系统（Memory System）

**没有记忆的 Agent，每次对话都从零开始。**Nanobot的记忆系统，官方说明分为两层（和一般科普文章中的三层记忆不同哦）：

记忆系统分两层：

• 短期记忆：当前对话的上下文（就是聊天记录），让 Agent 在多轮对话中保持连贯
• 长期记忆：跨会话的持久化存储，让 Agent 能记住用户的偏好、历史决策、重要事实

nanobot 的记忆系统支持跨会话持久化，还能在上下文过长时自动压缩（compaction），避免 Token 爆炸。

一句话理解：记忆系统是 Agent 的「大脑硬盘」，决定了它能不能「长大」。

模块 4：LLM 客户端（LLM Client）

Agent 的智能来自 LLM，但你不应该被绑死在一个模型上。

一个好的 LLM 客户端需要：

• 统一接口：不管底层是 OpenAI、Claude、DeepSeek 还是本地 vLLM，上层代码调用方式一致
• 模型切换：运行时可以切换模型
• 降级容错：主模型挂了，自动切换到备用模型（fallback）
• 流式输出：支持流式返回，用户体验更好

nanobot 通过 LiteLLM 统一路由，支持 20+ 种 LLM 提供商。

一句话理解：LLM 客户端是 Agent 的「大脑接口」，决定了它的灵活性和可靠性。

模块 5：网关系统（Gateway）

Agent 要能从多个入口接收消息。

网关系统负责：

• 多渠道接入：Telegram、Discord、微信、飞书、钉钉、Slack、邮件等
• 消息路由：把不同渠道的消息统一转给 Agent Loop 处理
• 格式适配：不同渠道的消息格式不同，网关负责转换

nanobot 支持 9 种聊天渠道，一个 Agent 可以同时连接多个入口。

一句话理解：网关系统是 Agent 的「嘴巴和耳朵」，决定了它能在哪里跟你对话。

---

四、把它们拼起来：一张架构图

这 5 个模块就是你要开发的全部。 每个模块都可以独立开发、测试、迭代。

---

五、系列路线图：接下来我们会讲什么？

这个系列不是泛泛而谈，每一篇都聚焦一个知识点，讲透、讲清楚：

篇目	主题	核心知识点
第 1 篇（本篇）	全景指南	AI Agent 的核心循环、5 大模块、前置准备
第 2 篇	Agent Loop	用 100 行代码写出最小可用的 Agent 循环
第 3 篇	工具系统	工具注册、发现、执行的完整实现
第 4 篇	LLM 客户端	统一接口设计、多模型路由、降级容错
第 5 篇	记忆系统	短期/长期记忆、上下文压缩、持久化
第 6 篇	网关系统	多渠道接入、消息路由、格式适配
第 7 篇	MCP 协议	接入 MCP 生态，让 Agent 拥有无限工具
第 8 篇	定时任务	让 Agent 自己按计划行动
第 9 篇	部署上线	从本地脚本到生产级服务
第 10 篇	完整实战	把所有模块组装成一个可用的 Agent

每篇文章都可以独立阅读，但按顺序读下来，你会拥有一个完整的 AI Agent 开发知识体系。

---

六、写在最后

nanobot 证明了一件事：构建一个功能强大的 AI Agent，不需要复杂的微服务架构，单体 Python 脚本依然能打。

开发者厌倦了黑盒式的大型框架，想要一个自己能完全看懂并掌控的代码库。对于学习者，一个干净的基座比一个臃肿的产品更适合做实验。

这个系列的目标也是如此：不是教你用一个框架，而是教你理解一个框架。

当你能从零写出自己的 Agent Loop，当你能设计自己的工具系统，当你能实现自己的记忆管理——你就真正拥有了你的 AI Agent。

下一篇，我们会用 100 行代码写出第一个最小可用的 Agent 循环。

关注我，一起从零开始造 Agent。

欢迎点赞关注加转发，您的支持是我更新的动力，谢谢~