30分钟跑通第一个AI Agent:learn-nanobot Nanobot安装配置完整教程与常见问题排错

原创2026-10-24 16:33:041,867 阅读
文章标签:教程文档AI Agent人工智能MCP 服务

30分钟跑通第一个AI Agent:learn-nanobot Nanobot安装配置完整教程与常见问题排错

learn-nanobot 是一份面向小白的 Nanobot 学习指南,本教程将带你用约 30 分钟完成 Nanobot 安装与配置,跑通你的第一个 AI Agent。Nanobot 是 HKUDS 开源的超轻量级 AI Agent 框架,核心代码仅约 4000 行,却能提供记忆、工具调用、多平台接入等工业级 Agent 能力,非常适合新手入门 AI Agent 开发。

Nanobot框架四大核心模块:AgentLoop核心引擎、工具注册表、技能加载器与长期记忆

为什么选 Nanobot 学 AI Agent?

特点 说明
🪶 超轻量 核心代码约 4000 行,安装后仅约 5MB,一个周末就能读完源码
🧠 功能完整 内置记忆系统、MCP 协议、技能加载、消息总线等核心模块
🌏 国内友好 原生支持飞书、钉钉等 8+ 平台,方便接入 DeepSeek 等国内模型
🆓 完全免费 MIT 协议开源,无任何商业限制

Nanobot 的核心是四大模块:AgentLoop(核心引擎)、ToolRegistry(工具注册表)、SkillLoader(技能加载器) 和 MEMORY.md(长期记忆),理解了它们,你就理解了绝大多数 AI Agent 框架的通用架构。

配套教程见 docs/02-nanobot-overview/README.md,可深入了解项目背景与设计理念。

30 分钟上手路线图

先看一下整体步骤和时间预算,做到心里有数:

步骤 内容 预计耗时
1️⃣ 环境准备 检查 Python 版本、申请 LLM API Key 5 分钟
2️⃣ 安装 pip 或 uv 安装 nanobot-ai 5 分钟
3️⃣ 配置向导 运行 nanobot onboard 生成配置文件 10 分钟
4️⃣ 定义身份 编写 AGENTS.md 告诉 Agent"你是谁" 5 分钟
5️⃣ 首次对话 启动交互模式并观察运行产物 5 分钟

第 1 步:环境准备(5 分钟)

系统要求很简单:

项目 最低要求 推荐配置
操作系统 macOS / Linux / Windows (WSL) macOS / Ubuntu 22.04+
Python 3.10+ 3.11 或 3.12
磁盘空间 500 MB 2 GB+

先检查 Python 版本:

python3 --version   # 输出应为 Python 3.10 或更高

如果版本过低,最简单的方式是用 Conda 创建一个独立环境:

conda create -n nanobot python=3.12 -y
conda activate nanobot

💡 小提示:推荐使用 uv(Rust 编写的 Python 包管理器),安装速度比 pip 快 10-100 倍,也是 Nanobot 官方推荐的方式。

然后准备一个大模型 API Key(Nanobot 通过它驱动 Agent 思考)。任选其一:

  • OpenAI(首选)
  • DeepSeek(国内友好,推荐新手)
  • 本地 Ollama(免费、离线)
export OPENAI_API_KEY="sk-xxxxxxxx"   # 或 DEEPSEEK_API_KEY

第 2 步:安装 Nanobot(5 分钟)

有三种安装方式,新手任选其一:

# 方式一:pip 安装(最简单)
pip install nanobot-ai

# 方式二:uv 工具安装(推荐,环境隔离不污染全局)
uv tool install nanobot-ai

# 方式三:源码安装(适合开发者,便于阅读源码)
git clone 项目源码后执行 uv sync --dev

安装完成后验证:

nanobot --version    # 输出版本号即成功
nanobot --help       # 查看 onboard、run 等子命令

⚠️ 如果提示 nanobot: command not found,说明安装路径不在 PATH 中,可以改用 python -m nanobot 运行,或重新用 uv 安装。

第 3 步:配置向导 onboard(10 分钟)

Nanobot 提供交互式配置向导,无需手写配置文件:

mkdir my-agent && cd my-agent
nanobot onboard

向导会依次引导你完成 5 步:选择 LLM Provider → 输入 API Key → 选择默认模型 → 配置 Workspace → 生成配置文件。

完成后,你的工作目录会长这样:

my-agent/
├── config.json      # 主配置文件
├── AGENTS.md        # Agent 身份定义
└── memory/
    └── MEMORY.md    # 长期记忆文件

读懂 config.json 的 3 个关键参数

config.json 是 Nanobot 最核心的配置文件,参考 projects/01-hello-nanobot/config.json 这份最简示例,新手重点理解 3 个字段即可:

字段 默认值 作用
model + provider gpt-4o + openai 指定用哪个模型、哪个服务商(两者必须匹配)
temperature 0.7 生成随机性:0 最稳定,越高越发散
max_tool_iterations 40 单次对话允许的最大工具调用轮数,防止死循环

💡 排错关键点:provider 和 model 不匹配(比如 provider 配了 deepseek 却写 gpt-4o)会直接报 Model not found,这是新手最常见的配置错误之一。

完整的配置详解(providers、channels、tools 全部字段)见 docs/06-install-and-hands-on/README.md 第 6.5 节。

第 4 步:用 AGENTS.md 定义 Agent 身份(5 分钟)

AGENTS.md 决定了你的 Agent "是谁"——它的内容会被注入 System Prompt。参考 projects/01-hello-nanobot/AGENTS.md 这份示例,10 行 Markdown 就够了:

# 代码审查助手

你是一个专业的代码审查助手。

## 职责
- 审查用户提交的代码
- 指出潜在的 bug 和安全问题
- 提供代码改进建议

## 规则
- 使用中文回答
- 给出具体的代码示例

这就是 Nanobot "Markdown 即配置" 的设计哲学:JSON 给机器读,Markdown 给人和 AI 读,改几个字就能改变 Agent 的行为。

第 5 步:第一次对话,观察 Agent 如何工作(5 分钟)

在配置目录下直接启动:

nanobot

进入交互模式后,试着让它做点需要工具的事,比如"帮我创建一个 hello.py 文件"。你一次完整的对话,Agent 内部经历了 4 步循环:

AI Agent工作循环四步:接收消息、LLM推理、工具执行、返回结果

运行后一定要看这几处产物(面试中都是加分细节):

  • memory/MEMORY.md —— 长期记忆,Agent 把你认为重要的信息"刻"在这里
  • memory/HISTORY.md —— 历史时间线,记录每次会话摘要
  • sessions/ —— JSONL 格式的完整会话记录
  • AGENTS.md —— 下次启动时会被重新加载,身份定义生效

Nanobot记忆系统:MemoryConsolidator记忆巩固器将旧对话压缩写入MEMORY.md长期记忆

可以试试:对话时告诉它"我叫张三,我喜欢用 Python",退出后重启再问"我叫什么",它应该能记住——这就是记忆系统在起作用。原理详解见 docs/07-memory-system/README.md。

常见问题快速排错

症状 可能原因 解决方案
nanobot: command not found 安装路径不在 PATH 用 python -m nanobot 运行,或改用 uv tool install nanobot-ai
requires Python >= 3.10 Python 版本过低 用 pyenv/conda 升级到 3.12 后重装
Authentication failed API Key 抄错或含空格 重新复制 Key;确认 provider 与 Key 匹配
Model not found model 与 provider 不匹配 如 deepseek 应配 deepseek-chat,openai 应配 gpt-4o
连接超时(国内常见) 直连境外 API 不稳定 配置 DeepSeek 等国内 Provider,或把 api_base 指向代理地址
工具调用失败 权限或配置缺失 检查 restrict_to_workspace 限制、exec 是否被禁用、web_search 是否配了 Key
找不到记忆文件 workspace 路径配置错误 检查 config.json 中 workspace 字段,手动 mkdir -p memory

🎯 排错心法:90% 的安装问题出在 Python 版本、API Key、model/provider 匹配 这三处,按上表逐项排查基本都能解决。

下一步学什么?

跑通第一个 Agent 只是开始,按这条路径继续即可:

  1. 记忆系统 —— 理解 MEMORY.md 与记忆压缩机制:docs/07-memory-system/README.md
  2. 技能与工具 —— 给 Agent 装上手脚:docs/08-skills-and-tools/README.md
  3. 多平台接入 —— 接入 Telegram / 飞书 / 钉钉:docs/09-multi-platform/README.md
  4. 安全与部署 —— 把 Agent 放到生产环境:docs/11-security-and-deploy/README.md

还有 4 个递进式的实战项目等你动手:projects/01-hello-nanobot/(Hello Nanobot)、projects/02-custom-skill/(自定义技能)、projects/03-mcp-server/(MCP Server)、projects/04-multi-platform-bot/(多平台 Bot)。完整 17 章学习路线图见 README.md,祝你的第一个 AI Agent 顺利跑起来!🚀

登录后查看全文
learn-nanobot