本文回答什么问题：AI Agent 框架的端到端架构由哪 6 阶段流水线组成，每阶段在源码中落在哪个文件？

目标读者：LLM Agent 开发者 / 系统架构师
预计阅读时间：12 分钟
源码版本：GitHub HKUDS/nanobot main 分支主线代码(仓库相对路径 nanobot/<module>.py,所有源码引用以此为基线)

本章是「nanobot 源码精讲」专栏的开篇章，目的是建立全局心智模型：在你开始读 30 章之前，先在脑中跑一遍"用户发消息 → Agent 回复"的全链路。

1. 整体定位：nanobot 是什么、不是什么

nanobot 是什么,先看 README 的原话——它的定位不是「更大的 LangChain」,而是「小到能读完核心的 AI Agent 框架」。本节先把它能做什么、不能做什么讲清楚,再进入数据结构与流程图。

🐈 nanobot is an ultra-lightweight, open-source, self-hosted personal AI agent framework written in Python. It runs in a WebUI, terminal, or chat apps and combines tools, long-term memory, MCP integrations, model routing, multi-agent delegation, scheduled automation, and an OpenAI-compatible API in a small, readable core.

它不是什么：

• ❌ 不是 LangChain/LlamaIndex 的「全家桶」——没有 RAG/Embedding/VectorStore 内置
• ❌ 不是 Agent 协议（DAP/MCP-server-only）——它是 Agent 运行框架
• ❌ 不是多智能体 OS——它有 Subagent 子代理派生，但仍是单 AgentLoop 主导

它是什么（从 README L53-L61 的功能清单 + 实际源码目录反推）：

能力	出处
WebUI / 终端 / 17 个聊天通道	nanobot/cli/、nanobot/channels/
工具：files / shell / web / MCP / cron / image / subagent	nanobot/agent/tools/ 23 个文件
会话历史 + Dream 长期记忆	nanobot/session/manager.py、nanobot/agent/memory.py
长期目标 / 定时任务	nanobot/cron/、nanobot/session/goal_state.py
Python SDK + OpenAI 兼容 API	nanobot/nanobot.py、nanobot/api/server.py
自部署为 gateway	nanobot/gateway/

核心要点速查（建议收藏）

• nanobot 顶层 21 模块,3 大子系统(Agent / Provider / Channel)按依赖分层,__init__.py 懒加载(见 nanobot/__init__.py L31-L54)保证启动延迟最小
• 17 个内置聊天通道全部在 nanobot/channels/<name>/ 自包含子包,pkgutil.iter_modules 扫描自动发现(Glob 验证于 nanobot/channels/*/manifest.py)
• 8 个具名 LLM Provider 后端(Anthropic / OpenAICompat / OpenAICodex / XAIGrok / GitHubCopilot / AzureOpenAI / Bedrock / Unconfigured)统一契约在 nanobot/providers/base.py 的 LLMProvider ABC
• 23 个内置工具文件 + ~16 个可注册 Tool 类,自发现走 pkgutil + entry_points(group="nanobot.tools") 双轨(见第 27 章 ToolLoader 自发现详解)
• 数据流核心路径: Channel → MessageBus.inbound → AgentLoop → AgentRunner → LLMProvider/ToolRegistry → AgentLoop → MessageBus.outbound → Channel(已在 docs/architecture.md L8-L23 官方架构图镜像)
• AgentLoop(约 2058 行)负责通道层回合;AgentRunner(约 1505 行)负责模型层多循环——严格分工:通道问题看 loop.py,模型问题看 runner.py

2. 核心数据结构（速查表）

2.1 顶层规模（可数 · 已 Glob 验证）

维度	数量	验证命令
Python 顶层模块	21 个	LS nanobot/
内置聊天通道	17 个	Glob nanobot/channels/*/manifest.py
内置 Provider 后端	8 个具名（Anthropic / OpenAICompat / OpenAICodex / XAIGrok / GitHubCopilot / AzureOpenAI / Bedrock / Unconfigured）	nanobot/providers/__init__.py L9-L29
内置 Tool 文件	23 个（其中约 16 个可注册工具类）	Glob nanobot/agent/tools/*.py
AgentLoop 主文件	约 2058 行	nanobot/agent/loop.py
AgentRunner 主文件	约 1505 行	nanobot/agent/runner.py
Skills（提示词扩展包）	10+ 个内置	nanobot/skills/

2.2 关键类型（先认识 5 个就够开篇）

类型	位置	作用
InboundMessage	nanobot/bus/events.py L23-L39	来自通道的用户消息
OutboundMessage	nanobot/bus/events.py L42-L58	回流到通道的回复
OutboundEvent 联合	nanobot/bus/outbound_events.py L17-L89	10 个 dataclass 子类
LLMProvider / LLMResponse / ToolCallRequest	nanobot/providers/base.py L50-L99	Provider 抽象
Tool / ToolResult	nanobot/agent/tools/base.py	工具抽象

3. 整体架构图（docs/architecture.md L8-L23 镜像）

逐节点解释：

• Channel：将外部平台（Telegram/Discord/CLI/WebUI）转换为 InboundMessage 推入 MessageBus.inbound。
• MessageBus:asyncio.Queue 双向解耦(nanobot/bus/queue.py L17-L18)。
• AgentLoop：通道层回合编排者（session key、workspace、context、hooks、outbound 投递）。
• AgentRunner：模型层多轮循环（provider 调用、流式输出、工具执行、迭代上限）。
• Provider：8 个具名后端，详见第 17-21 章。
• Tools：23 个文件，详见第 26-28 章。

6 阶段流水线的完整时序图 + 每阶段源码定位在**第 03 章《整体架构与数据流》**详讲——本章不开 6 阶段细节,只让你看到"6 个节点闭环"的高层图。本章侧重"这是什么 / 不是什么 / 怎么用",第 03 章侧重"源码怎么实现 6 阶段"。

4. 5 类核心读者视角速查（帮你判断"本章是否值得读完"）

nanobot 的 5 类典型使用者在看完本章后,会跳到不同主题群——提前给出 5 类视角的"看完本章去哪":

读者类型	本章要确认什么	看完本章去哪
LLM Agent 开发者	"5 个关键类型 + 6 节点闭环"是否够用	第 03 章《整体架构与数据流》 拿完整 14 步时序图 → 第 10-16 章 Agent 核心 深挖 loop/runner
LLM Provider 适配者	"8 个具名后端统一契约"是否成立	第 17 章 LLMProvider 抽象 + 第 19 章 Provider 实现对比
聊天通道开发者	"17 通道子包结构 + 配对码"是否优雅	第 22 章 BaseChannel + 第 23 章 通道自发现与配对
Tool / MCP 工具开发者	"23 工具 + Tool ABC + entry_points"是否够用	第 26 章 Tool 抽象 + 第 27 章 ToolLoader 自发现 + 第 28 章 关键工具链
系统架构师 / 安全审计	“三层防护(workspace / network / pairing)是否到位”	第 29 章 安全策略

5. 选 nanobot 还是 LangChain / AutoGen？(对比决策表)

维度	nanobot(本专栏)	LangChain	AutoGen	CrewAI
定位	Agent 运行框架(编排+工具+通道+部署)	LLM 编排库(链+Retriever+Agent)	多 Agent 协作框架	多 Agent 角色协作
RAG / VectorStore	❌ 不内置(专注 Agent 核心)	✅ 内置(主卖点)	❌ 不内置	❌ 不内置
内置聊天通道	✅ 17 个(Telegram/Discord/Slack/Feishu/Weixin…)	❌ 需自己接	❌ 需自己接	❌ 需自己接
OpenAI 兼容 API	✅ /v1/chat/completions + /v1/audio/transcriptions + /v1/images/generations	❌ 需自己实现	❌ 需自己实现	❌ 需自己实现
长期记忆	✅ Dream 整合(自动写 MEMORY.md + git diff 审计)	需 Memory 包	需自己接	需自己接
定时任务	✅ Cron 工具 + 9 种系统 jobs	❌ 需 APScheduler	❌ 需 APScheduler	❌ 需 APScheduler
多 Agent	✅ Subagent 派生(单 AgentLoop 主导)	需 LangGraph	✅ 多 Agent 协作(原生)	✅ 多 Agent 角色(原生)
代码量	核心可读(AgentLoop 2058 行 + AgentRunner 1505 行)	数十万行(包多)	中等	中等
学习曲线	平缓(读完 10 章可二次开发)	陡(概念多)	中等	中等

决策建议:

• 要"开箱即用的聊天 Agent + 17 IM 通道 + OpenAI 兼容 API" → 选 nanobot(本专栏)
• 要"RAG + 文档问答 + LLM 链" → 选 LangChain
• 要"多 Agent 协商 / 复杂 workflow" → 选 AutoGen / CrewAI

6. 常见误区 / 避坑（开篇章）

Q：nanobot 是不是和 LangChain、AutoGen、CrewAI 同一类？

A：不是。定位不同(详见 §5 对比表)。nanobot 是 Agent 运行框架(编排 + 工具 + 通道 + 部署),不含 RAG/VectorStore;LangChain 是 LLM 编排库(链 + Retriever + Agent);AutoGen/CrewAI 是 多 Agent 协作框架。

Q：源码大不大？我能读完吗？

A：核心可读——AgentLoop+ AgentRunner+ MessageBus+ LLMProvider 基类(数百行)。其他大部分是 channel / tool 各自独立的小文件。30 章专栏读完需要约 30-40 小时,但读完前 10 章就能上手二次开发。

Q：从哪里开始读源码？

A：建议路径(与画像 1 一致):bus/queue.py → bus/events.py → bus/outbound_events.py → agent/loop.py → agent/runner.py。完整 14 步时序图在第 03 章。

7. 小结

• nanobot = 通道层 + AgentLoop + AgentRunner + Provider 适配 + Tool 系统 的轻量自托管框架
• 5 个最关键类型:InboundMessage / OutboundMessage+OutboundEvent / LLMProvider / Tool / MessageBus
• 5 类读者各有"看完本章去哪"路径(详见 §4)
• 5 个框架选型对比表(详见 §5)
• 30 章专栏读完可独立二次开发

本文要点速查

1. nanobot 是 Agent 运行框架,不是 LLM 编排库——与 LangChain/AutoGen/CrewAI 的 5 维度对比详见 §5
2. 5 个最关键类型:InboundMessage / OutboundMessage+OutboundEvent / LLMProvider / Tool / MessageBus——覆盖所有数据流节点
3. 5 类读者各有专属阅读路径——LLM Agent / Provider / Channel / Tool / 架构师 看本章后跳向不同主题群(详见 §4)
4. 6 阶段流水线只给"6 节点闭环"高层图——完整 14 步时序图 + 节点→源码映射在第 03 章详讲(避免本章与 03 章重复)
5. 下一步：第 02 章《源码结构与扩展点索引》—— 21 模块 / 17 通道 / 23 工具速查地图

---

按角色推荐

• LLM Agent 开发者【你】：必读(本章让你 5 分钟建立"nanobot 是什么 / 5 类读者路径 / 选哪个框架"的全景认知;想深挖 6 阶段实现看第 03 章,想深挖 loop/runner 看第 10-11 章)
• LLM Provider 适配者：选读(看完 §4 表格"看完本章去哪"行 → 直接跳第 17-19 章;本节够你判断"是否值得深入")
• 聊天通道开发者：选读(知道 BaseChannel 在 nanobot/channels/base.py + 17 通道清单即可,详见第 22-25 章)
• Tool / MCP 工具开发者：选读(理解 ToolRegistry + entry_points + 23 工具拆分,第 26-28 章 详解)
• 系统架构师 / 安全审计：必读(§5 选型对比 + §4 主题群导览;三层防护 workspace_policy / network / pairing 在第 29 章汇总)

下一步

• 第 02 章 源码结构与扩展点索引 —— 21 模块 / 17 通道 / 23 工具速查地图(主题群"架构与基础设施")
• 第 03 章 整体架构与数据流 —— 完整时序图与节点 → 源码映射(同主题群)
• 第 10 章 AgentLoop 编排核心 —— 通道层 6 阶段流水线源码拆解(主题群"Agent 核心",第 3 周)

---

tags：#nanobot #AI Agent #LLM #Python #源码解析 #Agent架构 #事件驱动