智能体 | Nanobot的分层架构和Hook模式

在Agent 智能体开发领域，轻量化、高扩展性是开源框架必备技能，Nanobot的分层架构与多样化内置设计模式，成为适配多业务场景的优质智能体开发框架。Nanobot划分渠道层、核心调度层、领域层、基础设施层四层架构，各司其职实现业务解耦。

本文重点介绍：

1）核心调度层采用单一职责原则封装各类函数，以“套娃式”串行执行逻辑。 2）Hook模式依托生命周期钩子实现无侵入功能拓展。

结合架构图与时序图，剖析框架底层逻辑、核心特性及优劣，为智能体Agent二次开发与业务落地提供参考。

1，分层架构设计

图 1，nanobot 分层架构设计

Nanobot 的分层结构：

• • 渠道层是管理各个消息界面。
• • 核心调度层，实现消息处理，消息分发到对应的 agent，并实现消息的回传等功能。
• • 领域层实现了上下文管理，会话和记忆，技能管理，子 agent 等核心逻辑。
• • 基础设施层，包含 tool 工具的注册和实现，mcp 接口服务，大模型接口服务等。

核心调度层根据不同的功能，分装了不同的函数，每个函数实现单一职责，完成功能的一环。

主要的功能包括：

启动任务： 该功能在 gateway 中的回调函数 run 执行，建立对应协成任务，并等待任务完成。

主循环逻辑： 协程任务重包含一个 while 循环，是智能体的主要逻辑，负责拉取消息，获取对应结果，并根据结果，调用回调函数，执行对应的业务逻辑。

消息分发： 根据命令的类型将消息做不同处理，分为命令消息和普通消息。

普通消息处理： 建立 session，获取历史信息，构建上下文，调用大模型，保存结果等主要的逻辑。

大模型生成： 大模型结果解析，对流式和非流式结果统一处理。

实际大模型生成： 大模型实际调用接口封装。

图 2，nanobot 核心应用层设计

通过以上的流程，可以看到，其设计的思想是“套娃式”，每个函数完成一定的功能，然后将结果传递给下一个函数。这样的优点是，逻辑清晰，职责分明，缺点是所有功能必须串行，无法并行。

2，主循环流程

Nanobot Agent 完成任务的主流程。

图3，nanobot 核心主循环

入口 command 通过 gateway 中的 run 函数启动协成任务，并将普通消息分发到 AgentLoop 进行消息处理。在设计 AgentLoop 过程中有 5 中模式。

3，Hook 钩子模式

业务场景：agent 执行过程中，重要阶段需要输出提示信息，大模型的流式结果也需要及时展示。

Nanobot 有固定的执行生命周期，即初始化 → 思考 → 执行动作 → 结束。如果所有逻辑都写死在主流程里：

• • 无法灵活添加日志、监控、重试、中断、权限校验
• • 新增功能必须修改核心代码，违反开闭原则
• • 多场景复用性极差

Hook 模式就是解决：在不修改 Agent 核心代码的前提下，动态插入自定义逻辑，让生命周期完全可扩展。

简单说：

你想在 Agent 运行前 / 中 / 后加任何功能，都用 Hook 实现。

为满足业务需求，首先通过回调基类 AgentHook 定义了 7 个生命周期钩子点，并在主循环中通过 LoopHook 继承回调基类实现具体钩子点动作。并在 AgentRunner 执行过程中按顺序调用这些钩子。

AgentRunner 执行流程:

• • before_iteration()，迭代开始前
• • on_stream(delta)，LLM 流式输出每个 token
• • on_stream_end()，流式输出结束（可能进入工具调用）
• • before_execute_tools()，工具执行前
• • after_iteration()，每轮迭代结束后
• • finalize_content()，所有迭代结束，最终内容处理，(循环 1-5 直到 max_iterations 或 stop)

图4，回调钩子运行时序图

钩子模式实际是一种观察者模式：

1. 1. 被观察者（Subject）：事件发起方（Nanobot 里就是 Agent）
2. 2. 观察者（Observer）：事件监听方（Nanobot 里就是 Hook）
3. 3. 通知机制：主题统一推送消息，观察者被动响应

其核心特点：发布 - 订阅思想。开闭原则，新增监听逻辑不用改主体代码。一对多联动。在具体的 AgentRunner 生命周期阶段，显式的执行定义好的钩子函数，即可实现响应动作。

钩子模式的优势：

• • Agent 只负责思考 + 执行核心业务，不关心日志、监控、埋点
• • 所有附加逻辑全部下沉到 Hook（观察者）
• • 随时增删 Hook，不影响主流程稳定性

小结： Nanobot 的 Hook 本质就是，Agent 作为被观察者发布生命周期事件，所有挂载的 Hook 作为观察者监听并执行逻辑，全程无侵入主流程。