1. 项目概述：从源码视角理解AgentLoop

最近在社区里看到不少朋友在讨论OpenClaw和Nanobot，尤其是关于如何构建一个稳定、高效的AI Agent系统。很多新手在尝试搭建自己的Agent时，常常卡在“Agent跑起来就停不下来”或者“逻辑混乱，不知道下一步该干嘛”这类问题上。这背后，一个核心的机制就是AgentLoop，也就是智能体的运行循环。它决定了Agent如何感知、思考、决策和行动，是整个系统的大脑和中枢神经。

我花了些时间，仔细研读了Nanobot项目的源码，特别是其AgentLoop的实现部分。Nanobot作为一个轻量级、模块化的Agent框架，它的设计思路非常清晰，对于想深入理解Agent内部运作机制，甚至想自己动手搭建框架的开发者来说，是个绝佳的学习样本。这次，我们就抛开那些高大上的概念，直接钻进代码里，看看一个生产可用的AgentLoop究竟是如何被构建出来的，里面有哪些精妙的设计和不得不防的“坑”。

简单来说，这次我们要搞明白的就是：一个AI Agent是如何通过一个循环（Loop），持续地与环境（用户、工具、其他Agent）进行交互，并完成复杂任务的。无论你是想用OpenClaw这类现成方案，还是想基于LangChain、AutoGen甚至从零开始打造自己的Agent，理解这个“循环”都是最基础、最核心的一课。

2. 核心概念拆解：什么是AgentLoop？

在深入代码之前，我们得先统一一下认知。AgentLoop不是一个凭空创造的概念，它源于我们对智能体（Agent）最朴素的认知：一个能自主感知、决策和行动的实体。在编程世界里，我们用一个“循环”来模拟这种持续的行为。

2.1 AgentLoop的经典模型

一个最简化的AgentLoop通常包含以下四个步骤，你可以把它想象成一个永不疲倦的“观察-思考-行动-休息”的循环：

1. 观察（Observe）：Agent从环境中获取输入。这可能是用户的一条新消息、一个API的返回结果、一个数据库查询的反馈，或者一个定时器触发的事件。
2. 思考（Think）：Agent基于当前的观察、历史记忆（Memory）和预设的目标（Goal），决定接下来要做什么。这一步的核心是调用大语言模型（LLM）进行推理和规划。
3. 行动（Act）：Agent执行在“思考”阶段决定的操作。这可能包括调用一个工具（Tool）、执行一段代码、发送一条消息，或者仅仅是更新内部状态。
4. 反思（Reflect）：评估行动的结果，并将其作为新的“观察”存入记忆，为下一个循环做准备。高级的Agent还会在这里进行更深层次的反思，比如“我刚才的策略有效吗？是否需要调整？”

这个循环会一直运行，直到达到某个终止条件，比如任务完成、用户喊停、或者出现了无法处理的错误。

2.2 Nanobot对AgentLoop的抽象

Nanobot的源码没有使用“Observe-Think-Act”这种直白的命名，而是采用了更工程化、更贴合分布式系统思维的抽象。在它的核心模块中，AgentLoop通常由一个主循环函数、一个状态机和一系列处理器（Handler）构成。

• 主循环：通常是一个while循环或由异步事件驱动的任务循环，负责维持Agent的生命周期。
• 状态机：定义Agent可能处于的各种状态，如IDLE（空闲）、THINKING（思考中）、ACTING（执行中）、WAITING_FOR_TOOL（等待工具返回）、ERROR（错误）等。状态机确保了Agent行为的有序性，避免了状态混乱。
• 处理器：这是Nanobot设计精妙的地方。它将“思考”、“工具调用”、“结果解析”等不同职责拆分成独立的处理器，每个处理器只做一件事，并通过管道（Pipeline）或事件总线串联起来。这使得系统非常易于扩展和维护，你可以像拼乐高一样替换或增加新的处理器。

理解了这个抽象模型，我们再去看源码，就不会被各种类和方法绕晕了，而是能清晰地看到每个代码块在AgentLoop这个大图景中扮演的角色。

3. Nanobot源码中的AgentLoop实现精读

现在，我们打开Nanobot的源码（假设我们聚焦于其核心的agent_loop.py或类似命名的文件）。我不会贴出所有代码行，而是带你走一遍核心流程，并标注出关键的设计点和值得学习的技巧。

3.1 循环的入口与状态初始化

通常，Agent的启动会从一个run或start方法开始。在这个方法里，首先会初始化Agent的内部状态。这个状态对象（可能是一个AgentState类的实例）是贯穿整个Loop的生命线，它包含了：

• 当前对话历史/记忆：与LLM交互的上下文。
• 任务目标/参数：本次循环要解决的具体问题。
• 已使用的工具列表及结果：记录调用历史，避免重复或循环调用。
• 当前状态机状态：如INITIALIZING。

实操心得：状态设计的艺术状态对象的设计至关重要。Nanobot倾向于使用不可变（immutable）或可持久化的数据结构来记录状态。这样做有两个巨大好处：一是方便调试，你可以随时把状态快照保存下来，复现问题；二是为Agent的“持久化”和“断点续跑”提供了可能。想象一下，一个运行了10分钟的任务突然崩溃，如果能把完整状态恢复，就能从断点继续，而不是重头再来。

3.2 核心循环体解析

接下来是真正的while循环。伪代码逻辑如下：

async def _run_loop(self, initial_state: AgentState): state = initial_state while not self._should_stop(state): try: # 1. 状态路由：根据当前状态，决定进入哪个处理环节 if state.status == AgentStatus.THINKING: state = await self._thinking_phase(state) elif state.status == AgentStatus.ACTING: state = await self._acting_phase(state) elif state.status == AgentStatus.WAITING_FOR_TOOL: state = await self._handle_tool_response(state) # ... 其他状态处理 elif state.status == AgentStatus.FINISHED: break else: # 处理未知状态，通常记录日志并转入ERROR状态 self.logger.error(f"Unknown agent status: {state.status}") state = state.update(status=AgentStatus.ERROR, error_info="Unknown status") except Exception as e: # 2. 异常处理：捕获循环内的任何异常，优雅地处理错误 self.logger.exception("Error in agent loop") state = state.update(status=AgentStatus.ERROR, error_info=str(e)) # 可以选择重试、通知用户或直接终止 if self._max_retries_exceeded(state): break return state

关键点分析：

1. 基于状态机的路由：循环的核心是一个大的if-elif或match-case（Python 3.10+）语句，它根据state.status的值，将执行流导向不同的处理函数。这是实现复杂工作流的基础。
2. 异步（Async/Await）：现代Agent框架几乎都采用异步编程。这是因为Agent经常需要等待网络I/O（如调用LLM API、访问数据库）。异步可以避免阻塞，让单个线程也能高效处理多个Agent任务。Nanobot的源码里充满了async和await关键字，这是必须掌握的。
3. 优雅的异常处理：try...except包裹了整个循环体。在分布式系统中，网络抖动、API限流、工具超时等异常是家常便饭。一个健壮的AgentLoop必须能捕获这些异常，并将Agent状态安全地置为ERROR，同时记录详细的日志，而不是让整个进程崩溃。

3.3 “思考”阶段详解

_thinking_phase是Agent的“大脑”。我们看看它里面发生了什么：

async def _thinking_phase(self, state: AgentState) -> AgentState: # 1. 准备给LLM的提示词（Prompt） messages = self._prompt_engine.construct_messages(state) # 可能包括：系统指令、对话历史、工具描述、当前目标等 # 2. 调用LLM llm_response = await self._llm_client.acall( messages=messages, tools=self._available_tools_descriptions, # 告诉LLM它可以使用的工具 temperature=state.thinking_temperature, # ... 其他参数 ) # 3. 解析LLM的响应 parsed_decision = self._response_parser.parse(llm_response) # 4. 根据解析结果更新状态 if parsed_decision.type == "tool_call": new_state = state.update( status=AgentStatus.ACTING, next_action=parsed_decision.tool_name, action_args=parsed_decision.arguments ) elif parsed_decision.type == "final_answer": new_state = state.update( status=AgentStatus.FINISHED, final_output=parsed_decision.answer ) elif parsed_decision.type == "need_more_info": new_state = state.update( status=AgentStatus.WAITING_FOR_USER, question_for_user=parsed_decision.question ) # ... 处理其他决策类型 return new_state

关键点分析：

1. 提示词工程模块化：_prompt_engine是一个独立的模块。Nanobot通常会将不同任务、不同角色的提示词模板化、配置化，而不是硬编码在代码里。这使得调整Agent的行为变得非常灵活。
2. 工具描述注入：调用LLM时，通过tools参数将可用的工具列表（名称、描述、参数schema）传递给模型。这是让LLM学会使用工具的关键。OpenAI的Function Calling、Anthropic的Tool Use都基于此原理。
3. 响应解析器：LLM返回的通常是自由文本或特定的JSON结构。需要一个专门的_response_parser来将其标准化为框架能理解的内部指令（如“调用工具A”、“直接回答”、“反问用户”）。这个解析器需要很强的鲁棒性，能处理LLM输出的各种“奇怪”格式。

踩坑记录：LLM输出的不确定性最大的坑就在这里。LLM并不总是乖乖地按照你指定的格式输出。它可能输出无关内容，可能把JSON格式写错，甚至可能“幻觉”出一个不存在的工具。因此，_response_parser必须包含重试和降级逻辑。例如，如果第一次解析失败，可以尝试用更简单的提示词让LLM重试，或者从文本中尝试正则匹配提取关键信息。Nanobot的源码中往往有复杂的解析和校验逻辑，这部分代码值得反复琢磨。

3.4 “行动”阶段与工具调用

当状态进入ACTING，就意味着Agent决定要使用某个工具了。

async def _acting_phase(self, state: AgentState) -> AgentState: tool_name = state.next_action tool_args = state.action_args # 1. 查找并验证工具 tool = self._tool_registry.get_tool(tool_name) if not tool: # 工具不存在，返回错误状态，并在思考阶段让LLM知晓 return state.update( status=AgentStatus.THINKING, memory=state.memory + f"\n[System] Tool '{tool_name}' not found." ) # 2. 执行工具调用（通常是异步的） try: self.logger.info(f"Executing tool: {tool_name} with args {tool_args}") tool_result = await tool.execute(**tool_args) tool_result_str = str(tool_result) except Exception as e: tool_result_str = f"Error executing tool '{tool_name}': {str(e)}" self.logger.error(tool_result_str) # 3. 将工具执行结果作为新的观察，存入记忆，并触发下一次“思考” new_memory = state.memory + f"\n[Tool {tool_name}] Result: {tool_result_str}" new_state = state.update( status=AgentStatus.THINKING, # 关键：回到思考阶段 memory=new_memory ) return new_state

关键点分析：

1. 工具注册表：_tool_registry管理所有可用工具。这种中心化注册的方式，使得动态添加、移除工具变得非常容易。这也是像OpenClaw这类系统能支持“技能（Skill）”热加载的基础。
2. 执行与状态转换：工具执行完毕后，最重要的一步是将结果格式化后，追加到Agent的记忆（memory）中。然后，将状态重新置为THINKING。这样，下一个循环就会带着工具执行的结果，再次进入“思考”阶段，让LLM基于这个新结果决定下一步行动。这就构成了“思考-行动-观察-再思考”的完整闭环。
3. 错误处理：工具执行也可能失败。框架通常会将错误信息也格式化后存入记忆，让LLM在下一轮思考时能意识到工具调用出了问题，从而可能尝试其他方案或向用户求助。

3.5 循环的终止条件

Agent不能永远跑下去。_should_stop函数检查终止条件，通常包括：

• 任务完成：状态为FINISHED（LLM给出了最终答案）。
• 用户中断：收到了停止信号。
• 达到最大迭代次数：防止LLM陷入死循环。例如，限制最多思考-行动20个回合。这是一个极其重要的安全阀！没有它，一个逻辑混乱的Agent可能会无限调用工具，产生高昂的API费用。
• 超时：整个任务运行时间过长。
• 不可恢复的错误：状态为ERROR且重试无效。

4. 从Nanobot看优秀AgentLoop的设计原则

通过解剖Nanobot，我们可以总结出几个设计高质量AgentLoop的黄金原则：

1. 状态驱动，清晰明确：所有行为都围绕明确的状态流转展开。状态是Agent的“快照”，是调试和监控的基石。
2. 模块化与单一职责：将思考、解析、工具调用等逻辑拆分为独立的组件（处理器）。这提升了代码的可测试性和可维护性。你想换一个LLM提供商？只需替换_llm_client模块。想增加一种新的响应格式？修改_response_parser。
3. 异步优先：充分利用异步I/O应对网络延迟，这是保证Agent吞吐量和响应速度的关键。
4. 拥抱不确定性，健壮性第一：对LLM的输出、工具的执行结果保持怀疑态度，每一层都要有错误处理和降级策略。日志要详尽，方便事后复盘。
5. 资源与安全管控：必须设置迭代次数、运行时间的上限，并对工具调用（特别是涉及外部API、数据写入的工具）进行权限和成本控制。

5. 在OpenClaw及自建Agent中的实践与调优

理解了原理，我们来看看在OpenClaw这类具体系统中，以及自己搭建Agent时需要注意什么。

5.1 OpenClaw中的AgentLoop特色

OpenClaw基于Nanobot等思想构建，但更偏向于企业级、多Agent协作场景。它的AgentLoop可能具备以下增强特性：

• 事件驱动：除了主循环，可能还深度集成了异步事件系统。Agent可以监听特定事件（如“收到新消息”、“数据库变更”），从而被动态触发，而不仅仅是轮询。
• 持久化状态后端：AgentState可能被存储在Redis或数据库中，这使得Agent可以跨进程、跨服务器恢复，实现了真正的“长时记忆”和“持久化任务”。
• 复杂的多路复用：一个Loop可能同时管理与多个用户或子任务的交互，内部有更精细的调度逻辑。

当你运行OpenClaw并看到Agent在持续工作时，背后正是这样一个增强版的、稳健的AgentLoop在支撑。

5.2 自己实现AgentLoop的避坑指南

如果你想自己动手，这里有一些比官方文档更实在的建议：

• 不要从零开始造轮子：除非是为了学习，否则优先考虑基于LangChain、AutoGen、Semantic Kernel或Nanobot这样的框架进行开发。它们已经解决了90%的通用问题。
• 内存管理是难点：随着对话轮数增加，上下文会越来越长。你需要设计记忆压缩/摘要策略。例如，每5轮对话后，让LLM自动生成一个之前对话的摘要，然后用摘要替换掉旧的历史记录，只保留最近几轮原始对话。Nanobot的源码中可能有相关的MemoryManager类值得参考。
• 工具调用的验证与沙盒：永远不要相信LLM生成的参数，直接传给工具。必须进行参数校验和类型转换。对于执行代码、访问文件系统的危险工具，必须在沙盒环境中运行。
• 设置严格的超时和限流：为每一次LLM调用和工具调用设置超时。为整个Loop设置最大耗时和最大迭代次数。使用令牌桶等算法对高消耗工具进行限流。
• 可观测性：在你的Loop关键节点（状态变更、调用LLM、调用工具、发生错误）打入详细的日志和指标（Metrics）。这能让你在出问题时，快速定位是提示词不对、工具挂了，还是LLM“发疯”了。

5.3 调试技巧：当AgentLoop“卡住”或“乱跑”

即使有了框架，Agent行为异常也是常事。你可以按以下步骤排查：

1. 检查状态：打印或日志输出每一轮循环开始时的AgentState。看状态机是否在正常流转。
2. 审查记忆：看看传递给LLM的完整提示词和历史记忆是什么。是不是记忆被污染了？或者上下文太长导致LLM忽略了关键信息？
3. 隔离测试LLM调用：将构造好的消息单独拿出来，用Playground或脚本调用一次LLM，看它的回复是否符合预期。问题可能出在提示词工程上。
4. 模拟工具响应：如果怀疑工具调用环节，可以Mock工具，返回一个预设的结果，看Agent后续的思考逻辑是否正确。
5. 启用迭代限制：首先确保你设置了最大迭代次数（比如10次），这样即使进入死循环，也能自动停止，避免损失。

研究Nanobot的AgentLoop源码，就像拿到了一张精密钟表的设计图。它告诉你各个齿轮（模块）如何咬合，发条（主循环）如何驱动，以及防卡簧（异常处理）在哪里。无论你是要深度定制OpenClaw，还是要设计自己的智能体系统，这张“设计图”提供的思路和最佳实践，都是极为宝贵的财富。记住，一个稳健的Loop，是Agent智能得以可靠展现的舞台。