第 10 章《AgentLoop 编排核心》· AgentLoop 编排怎么做？6 阶段流水线 + TurnContext 实战（nanobot）

本文回答什么问题:AgentLoop 的 6 阶段流水线怎么实现?TurnContext 是什么?session_key / workspace / hooks / outbound 在源码里如何编排?目标读者:LLM Agent 开发者 / 想修改核心循环的工程师预计阅读时间:18 分钟源码版本:GitHub HKUDS/nanobotmain 分支主线代码(仓库相对路径)AgentLoop(nanobot/agent/loop.py,约 2058 行)是 nanobot 通道层回合编排者——把用户消息变成Agent 回复的全过程。本章聚焦主入口_dispatch和 6 阶段流水线源码。1. 整体定位:AgentLoop vs AgentRunnerAgentLoop(本章):回合——管 session_key / workspace / hooks / outbound 投递AgentRunner(第 11 章):多循环——管 LLM 调用 / 流式 / 工具执行 / 迭代上限调试分流原则:通道问题看loop.py,模型问题看runner.py。核心要点速查(建议收藏)核心文件:nanobot/agent/loop.py(约 2058 行)主入口:AgentLoop._dispatch(msg)处理单回合;run_forever()主循环TurnContext:runnertoolshookssession的载体,每个回合构造一次6 阶段:Inbound → session 解析 → workspace 解析 → Context 构建 → Runner 多轮 → Outbound 投递3 个关键子方法:_resolve_session/_resolve_workspace/_handle_one_turn2. 6 阶段流水线源码拆解ChannelMessageBus_outboundSessionManagerAgentRunnerAgentTurnHookTurnContextAgentLoopMessageBusChannelMessageBus_outboundSessionManagerAgentRunnerAgentTurnHookTurnContextAgentLoopMessageBusconsume_inbound InboundMessage① resolve session_key workspace scope② build TurnContext runner/tools/hookspre_turn_hook messagerunner.run specOutboundMessage event streampost_turn_hook message response⑬ append() 持久化publish_outbound with TurnRouteconsume_outbound then send阶段 ① · Inbound 接入asyncdef_dispatch(self,msg:InboundMessage):# ... 见阶段 ②AgentLoop.run_forever()主循环从bus.consume_inbound()拿消息,转交_dispatch。阶段 ② · session 解析asyncdef_dispatch(self,msg:InboundMessage):# 1. 解析 session_key(默认 f{channel}:{chat_id},可被 metadata[session_key] 覆盖)session_keymsg.session_key# InboundMessage 已提供 property# 2. 解析 workspace(根据 chat_id 找 ~/.nanobot/workspaces/key/)workspaceself._resolve_workspace(msg)ifworkspaceisNone:awaitself._send_error(msg,no workspace available)return_resolve_workspace决定 workspace scope——这是nanobot/security/workspace_access.py的核心逻辑(详见第 29 章)。阶段 ③ · TurnContext 构造# 3. 构造 TurnContext(把 runner / tools / hooks 打包)ctxTurnContext(msgmsg,session_keysession_key,workspaceworkspace,runnerself._runner,# AgentRunner 单例toolsself._tools,# ToolRegistry 单例hooksself._hooks,# AgentTurnHook chainconfigself._config,)TurnContext 是回合的数据快照——AgentRunner 通过ctx.runner.run(spec)拿到。阶段 ④ · Hook 前置# 4. pre_turn_hook(可取消整个回合)ifnotawaitself._hooks.before_turn(ctx):return# hook 决定取消典型用法:WebUI 的批准按钮 → 等用户批准后再放行 Runner。阶段 ⑤ · Runner 多轮循环# 5. 构造 AgentRunSpec(从 ctx 派生出 spec)specAgentRunSpec(messagesself._ctx_builder.build_messages(ctx),# 历史 当前toolsctx.tools,max_iterationsself._config.max_iterations,)# 6. 跑 AgentRunner(可能 200 轮,详见第 11 章)resultawaitctx.runner.run(spec,hookself._hooks)阶段 ⑥ · Outbound 投递 Hook 后置# 7. post_turn_hook(可改 result)awaitself._hooks.after_turn(ctx,result)# 8. 持久化 sessionawaitself._session_manager.append(ctx.session_key,result.messages)# 9. 投递 outbound(每个 OutboundMessage 进 MessageBus)forout_msginresult.outbound_messages:awaitself._bus.publish_outbound(out_msg)# 10. TurnEnd 事件(可选,带 latency)awaitself._bus.publish_outbound(OutboundMessage(channelmsg.channel,chat_idmsg.chat_id,content,eventTurnEndEvent(latency_mselapsed_ms),))3. 4 个核心子方法_resolve_session(msg)→ session_keydef_resolve_session(self,msg:InboundMessage)-str:returnmsg.session_key_overrideorf{msg.channel}:{msg.chat_id}_resolve_workspace(msg)→ Pathdef_resolve_workspace(self,msg:InboundMessage)-Path|None:workspace_idself._workspace_access.resolve(channelmsg.channel,chat_idmsg.chat_id,sender_idmsg.sender_id,)ifworkspace_idisNone:returnNonereturnPath.home()/.nanobot/workspaces/workspace_id_handle_one_turn(ctx)→ OutboundMessage list主流程,见 §2 阶段 ③-⑥。_send_error(msg, reason)→ OutboundMessageasyncdef_send_error(self,msg:InboundMessage,reason:str):awaitself._bus.publish_outbound(OutboundMessage(channelmsg.channel,chat_idmsg.chat_id,contentf⚠{reason},))4. 3 个核心决策决策 1 · 为什么 AgentLoop 管 session_key / workspace,不管 LLM 调用?单一职责:loop.py 改 session 路由不影响 LLM 行为;runner.py 改流式输出不影响 session 路由。决策 2 · 为什么 TurnContext 是 dataclass 而非 dict?类型安全 IDE 自动补全;改字段会破坏编译。决策 3 · 为什么 hooks 可以取消回合?WebUI “abort” 按钮、审批流、配对确认都可以在 hook 里return False中止整个回合。5. 常见问题 / 避坑Q:AgentLoop 是单例吗?A:。gateway启动时构造一次,多通道共享。Q:_dispatch报错会怎样?A:try/except包裹,捕获后_send_error(msg, str(exc))通知通道,继续run_forever()不退出。Q:为什么用before_turn而不是pre_turn?A:before_turn返回False取消回合;after_turn可改 result——3 种语义区分。6. 小结6 阶段流水线:Inbound → session → workspace → TurnContext → Hook → Runner → Hook → 持久化 → OutboundTurnContext是回合数据快照调试分流:Hook 系统允许取消 / 改写 / 监控回合本文要点速查6 阶段源码定位:见 §2 各阶段代码片段TurnContext 字段:msg session_key workspace runner tools hooks config3 个核心子方法:_resolve_session/_resolve_workspace/_handle_one_turn下一步:第 11 章《AgentRunner LLM 循环》—— 阶段 ⑤ 详细展开按角色推荐LLM Agent 开发者:必读(后续 11-16 章都基于本章 6 阶段)系统架构师:必读(核心循环必读)LLM Provider 适配者:选读(知道 AgentRunner.run 怎么调即可)聊天通道开发者:选读(知道通道消息怎么进 loop 即可)Tool / MCP 工具开发者:选读(知道 Tool 在 TurnContext 里)下一步第 11 章《AgentRunner LLM 循环》—— 阶段 ⑤ 的_request_model_execute_tools(主题群Agent 核心,第 3 周)第 13 章《Hook 系统》——before_turn/after_turn完整 hook 类型(主题群Agent 核心,第 3 周)第 14 章《会话管理 SessionManager》—— 阶段 ⑧ 的 append 原子写(主题群Agent 核心,第 3 周)tags:#nanobot#AI Agent#LLM#Python#源码解析#AgentLoop#编排