1. 项目概述为什么“Agent Loop”是AI Agent开发的核心如果你正在学习或尝试构建自己的AI Agent可能已经接触过RAG、工具调用、Prompt工程这些概念。但当你真正开始动手试图让一个Agent去完成一个稍微复杂点的任务比如“帮我分析一下这个季度的销售数据并写一份报告”时你大概率会遇到一个瓶颈Agent执行一步就停了或者陷入一个死循环不断重复同一个动作。问题的根源往往不在于你的LLM不够强也不在于你的工具不够多而在于你还没有真正理解并实现一个健壮的Agent Loop。这就是为什么在任何一个系统的AI Agent学习路径中理解“Agent Loop”都是最关键、最核心的一环。你可以把它看作是AI Agent的“大脑”和“神经系统”协同工作的核心循环。没有这个循环Agent只是一次性的指令执行器有了它Agent才具备了持续思考、规划、执行和反思的能力才能处理那些需要多步骤、有状态、甚至需要根据环境反馈动态调整策略的复杂任务。今天我们就抛开那些高大上的概念从一个开发者的实战视角彻底拆解Agent Loop的构成、实现中的关键决策点以及那些只有踩过坑才知道的细节。2. Agent Loop的底层逻辑从ReAct范式到生产级架构要理解Agent Loop我们必须从它的理论基石——ReAct范式说起。ReActReasoning Acting是让LLM具备“思考-行动”能力的关键框架。其核心思想是让模型在每一步都输出一个格式化的文本包含Thought思考/推理、Action要执行的动作如调用某个工具、Action Input动作的输入参数以及可选的Observation上一步动作执行后的观察结果。一个最基础的、教科书式的Agent Loop流程看起来是这样的接收用户输入比如“查询北京明天的天气并建议我是否要带伞”。LLM推理Thought模型分析任务决定第一步需要调用“天气查询”工具。执行动作Action系统解析出工具名get_weather和参数location: “北京”并调用该工具。获取观察Observation工具返回“北京明天晴转多云气温15-25度降水概率10%”。循环判断LLM基于当前所有信息用户问题 历史步骤 最新Observation再次推理。它认为降水概率低但为了周全可能需要再查一下“紫外线指数”或直接给出建议。再次执行或最终回答LLM可能选择继续调用工具也可能认为信息已足够输出最终答案“明天北京天气不错降水概率很低可以不带伞但建议做好防晒。”这个循环会一直持续直到LLM认为任务完成输出一个包含最终答案的Final Answer标记。然而把这个理想化的流程图变成代码你会立刻遇到一系列工程挑战状态管理每一次循环都需要维护一个完整的“对话历史”或“步骤历史”其中包括所有的Thought、Action、Observation。这个历史是LLM进行下一次推理的上下文。如何高效存储和传递这个状态工具调度与执行如何根据LLM输出的文本准确、安全地解析出要调用的工具和参数工具执行是同步还是异步工具执行失败如网络超时、API错误如何处理循环终止条件除了LLM主动输出Final Answer还必须设置安全护栏。比如最大循环次数防止无限循环、超时控制、对无意义重复动作的检测等。流式输出与用户体验在Web或App中你希望用户能看到Agent“思考”的过程“我正在查询天气…”而不是长时间等待后一次性给出结果。这要求Agent Loop能支持中间步骤的流式推送。因此一个生产级的Agent Loop架构远不止一个while循环那么简单。它通常包含以下几个核心组件我们可以称之为“Agent运行时引擎”记忆Memory模块负责存储和管理Agent与用户交互的完整历史包括内部步骤。这可以是简单的列表也可以是向量数据库用于支持更复杂的长期记忆和检索。规划器Planner或推理引擎通常是LLM本身但它的Prompt被精心设计来输出结构化的推理步骤如ReAct格式。这部分是Agent的“大脑”。工具执行器Tool Executor负责接收规划器发出的动作指令找到对应的工具函数传入参数并执行然后将结果格式化后返回。它需要处理错误、类型转换和安全性。流程控制器Orchestrator这是Loop的“调度中心”。它控制着整个循环的流程何时调用规划器何时调用工具执行器如何判断循环是否应该继续或终止。它集成了超时、最大步数等控制逻辑。输出解析器Output Parser将LLM返回的非结构化文本解析成程序可以理解的结构化数据如一个包含thought,action,action_input的字典。这是连接LLM“自由文本”世界和程序“结构化”世界的关键桥梁。理解了这些组件我们再看Harness、LangChain、LlamaIndex等框架就能明白它们的价值它们提供了一套包裹在AI Agent核心推理逻辑之外的基础设施层。它们不负责代替Agent思考而是为你提供了实现上述组件的标准化、可复用的“轮子”比如内置的记忆管理、丰富的工具库、开箱即用的输出解析器以及健壮的流程控制器让你能更专注于业务逻辑和Prompt设计。3. 实战构建一个简易可运行的Agent Loop代码拆解理论说再多不如一行代码。我们不用任何重型框架就用Python和OpenAI API手写一个最核心的Agent Loop让你看清每一块“骨头”是怎么长的。这个Agent的任务是进行简单的数学计算和查询。首先我们定义两个简单的工具import math import requests def calculator(expression: str) - str: 计算一个数学表达式例如 ‘(3 5) * 2‘。 try: # 警告直接使用eval有安全风险仅用于演示。生产环境应用ast.literal_eval或专用库。 result eval(expression, {“__builtins__”: None}, {“math”: math}) return str(result) except Exception as e: return f”计算错误: {e}” def search_web(query: str) - str: 模拟网络搜索实际应调用搜索API。 # 此处为模拟真实情况可调用Serper、Google Search等API mock_responses { “Python创始人”: “Guido van Rossum”, “圆周率小数点后5位”: “3.14159”, “今天天气”: “[模拟]北京晴15-25°C” } return mock_responses.get(query, f”未找到关于‘{query}’的信息。”) # 工具注册表 TOOLS { “calculator”: { “function”: calculator, “description”: “用于计算数学表达式输入应为一个字符串形式的表达式如 ‘3 5 * 2‘。” }, “search_web”: { “function”: search_web, “description”: “用于查询事实性知识或最新信息输入为一个搜索查询词。” } }接下来是核心的Agent Loop实现。我们使用一个精心设计的Prompt来引导LLM遵循ReAct格式import openai from typing import Dict, List, Any, Optional class SimpleAgent: def __init__(self, api_key: str, model: str “gpt-3.5-turbo”): openai.api_key api_key self.model model self.memory: List[Dict[str, str]] [] # 存储对话和步骤历史 self.max_steps 10 # 防止无限循环 def _call_llm(self, prompt: str) - str: 调用LLM获取回复。 try: response openai.ChatCompletion.create( modelself.model, messages[{“role”: “user”, “content”: prompt}], temperature0.1, # 低温度保证输出格式稳定 streamFalse ) return response.choices[0].message.content.strip() except Exception as e: return f”LLM调用失败: {e}” def _parse_llm_output(self, text: str) - Dict[str, Optional[str]]: 解析LLM的输出提取Thought, Action, Action Input。 # 这是一个简单的解析器假设输出格式相对规整。 # 生产环境应使用更鲁棒的解析如正则表达式或框架提供的解析器。 lines text.split(‘\n’) thought, action, action_input None, None, None for line in lines: if line.startswith(‘Thought:’): thought line.replace(‘Thought:’, ”).strip() elif line.startswith(‘Action:’): action line.replace(‘Action:’, ”).strip() elif line.startswith(‘Action Input:’): action_input line.replace(‘Action Input:’, ”).strip().strip(‘“‘) # 去除可能的引号 return {“thought”: thought, “action”: action, “action_input”: action_input} def run(self, user_query: str) - str: 运行Agent Loop处理用户查询。 print(f”用户问题: {user_query}”) # 初始化系统Prompt明确指示ReAct格式和可用工具 system_prompt f”””你是一个善于使用工具解决问题的助手。请严格按以下格式回应 可用工具 {‘ ‘.join([f”{name}: {TOOLS[name][‘description’]}” for name in TOOLS])} 格式 Thought: 你的思考过程分析当前情况决定下一步做什么。 Action: 要使用的工具名必须是以下之一[{‘ ‘.join(TOOLS.keys())}] Action Input: 工具的输入通常是一个字符串。 或 Thought: 我认为已经得到足够信息可以回答用户了。 Final Answer: 你的最终回答。 开始当前用户问题是{user_query} “”” full_context system_prompt self.memory.append({“role”: “system”, “content”: system_prompt}) for step in range(self.max_steps): print(f”\n—- 第 {step 1} 步 —-“) # 1. 调用LLM进行规划/推理 llm_response self._call_llm(full_context) print(f”LLM原始输出:\n{llm_response}”) # 2. 解析输出 parsed self._parse_llm_output(llm_response) print(f”解析结果: {parsed}”) # 检查是否是最终答案 if “Final Answer:” in llm_response: final_answer llm_response.split(“Final Answer:”)[1].strip() print(f”\n任务完成最终答案: {final_answer}”) return final_answer # 3. 执行动作 action parsed.get(“action”) action_input parsed.get(“action_input”) if not action or action not in TOOLS: error_msg f”错误无法解析出有效动作或动作‘{action}’不可用。” print(error_msg) full_context f”\nObservation: {error_msg}” continue try: tool_func TOOLS[action][“function”] observation tool_func(action_input) print(f”执行工具 ‘{action}‘输入 ‘{action_input}‘结果: {observation}”) except Exception as e: observation f”工具‘{action}’执行出错: {e}” print(observation) # 4. 将观察结果加入上下文进入下一轮循环 observation_entry f”\nObservation: {observation}” full_context observation_entry # 更新记忆此处简化实际可能只存摘要 self.memory.append({“role”: “assistant”, “content”: llm_response}) self.memory.append({“role”: “user”, “content”: f”Observation: {observation}”}) # 简单防呆如果观察结果重复可能陷入循环 if step 2 and “Observation:” in full_context[-200:]: if full_context.count(observation_entry) 2: print(“检测到可能陷入循环提前终止。”) return “Agent在尝试中可能陷入了循环未能完成请求。” return f”达到最大步数{self.max_steps}仍未完成任务可能过于复杂或Agent无法处理。” # 使用示例 if __name__ “__main__”: agent SimpleAgent(api_key“你的OpenAI API Key”) result agent.run(“计算圆周率小数点后5位的值然后告诉我它的平方是多少”) print(f”\n最终返回给用户的结果: {result}”)运行这段代码你会看到Agent的完整思考过程Thought: 用户需要圆周率后五位我需要查询。Action:search_webAction Input:“圆周率小数点后5位”Observation:“3.14159”Thought: 现在我有了数值需要计算它的平方应该用计算器。Action:calculatorAction Input:“3.14159 ** 2”Observation:“9.8695877281”Thought: 我已经得到答案可以给出最终回答。Final Answer: 圆周率小数点后5位是3.14159它的平方约等于9.8696。这个简易实现暴露了Agent Loop的所有核心环节也揭示了需要强化的地方更鲁棒的输出解析、更完善的错误处理、支持异步工具调用、以及更智能的循环终止判断。4. 进阶挑战与调优从“能跑”到“好用”当你有了一个能循环起来的Agent下一个目标就是让它稳定、高效、可靠。这里有几个关键的进阶议题4.1 输出解析的稳定性与LLM的“格式之战”上面代码中的_parse_llm_output函数非常脆弱。LLM偶尔会不按格式输出比如忘记写“Thought:”或者把“Action Input”写成“Input”。在生产环境中这会导致循环崩溃。解决方案结构化输出JSON Mode这是最推荐的方式。在调用LLM时要求其以指定的JSON格式返回。OpenAI的API支持response_format{ “type”: “json_object” }这能极大提高输出的一致性。你的Prompt需要明确说明JSON的schema。使用框架的解析器LangChain的OutputFixingParser、RetryOutputParser等组件能自动尝试修复格式错误的输出或重试调用。后处理与兜底在解析后增加校验逻辑。如果解析失败可以将错误信息作为Observation反馈给LLM让它修正输出例如“你上次的回复格式不正确请严格按照指定格式重试。”4.2 工具执行的复杂性与异步化现实中的工具可能是耗时的API调用、数据库查询或文件操作。同步执行会阻塞整个Loop影响性能。解决方案异步执行使用asyncio将工具执行函数定义为async并在Loop中await。这允许Agent在等待一个耗时工具时理论上可以处理其他请求取决于你的架构。超时与重试为每个工具调用设置超时。如果超时可以重试对于幂等操作或记录错误并让LLM决定下一步如“网络查询超时是否尝试其他关键词”。工具结果的处理工具返回的数据可能很庞大如一篇长文。直接塞进上下文会浪费Token并干扰LLM。需要设计摘要或过滤机制只提取关键信息放入Observation。4.3 记忆管理的优化上下文窗口的博弈Agent Loop的每一步都会增长上下文历史。如果任务步骤很多很快就会触及LLM的上下文窗口限制如GPT-4 Turbo的128K。解决方案选择性记忆不是存储完整的原始文本而是存储经过提炼的“步骤摘要”。例如将“调用搜索API查询了X得到结果Y”存储为一条简短记录。向量记忆与检索对于长期、复杂的对话可以将历史交互的关键信息存入向量数据库。在每一步根据当前问题从向量库中检索最相关的历史片段动态构建上下文。这就是RAG检索增强生成在Agent内部的应用。滑动窗口只保留最近N步的详细历史更早的步骤则进行摘要或丢弃。4.4 循环控制与“防呆”机制无限循环和“鬼打墙”重复无意义动作是Agent的常见病。解决方案硬性限制最大步数如20步、总耗时限制是必须的。状态检测检查最近几步的(Action, Action Input)是否出现了重复。如果重复超过阈值则中断循环并可能将“检测到重复操作”作为Observation反馈给LLM让它改变策略。目标检查点对于可分解的任务可以预先定义一些子目标。当Agent的Observation表明某个子目标已达成可通过规则或另一个LLM调用判断可以主动推动循环进入下一阶段。4.5 与前端交互流式Streaming与中间状态对于用户体验而言看到Agent“正在思考…”、“正在搜索…”的中间状态非常重要。解决方案Server-Sent Events (SSE) 或 WebSocket在后端Agent Loop每产生一个中间结果新的Thought、Action开始、Observation返回就通过SSE或WebSocket推送到前端。状态机模型将Agent Loop的每个阶段思考中、执行工具中、生成最终答案中定义为明确的状态前端根据状态显示不同的UI。5. 框架选择与生态LangChain、LlamaIndex还是自研当你理解了Agent Loop的方方面面后选择技术栈就变成了一个权衡问题。LangChain生态最丰富抽象层级高。它的Agent、Tool、Chain、Memory等概念与我们上面拆解的组件几乎一一对应。优势是快速原型开发社区工具多。缺点是“黑盒”感较强抽象有时会带来性能开销和调试复杂度版本迭代快。适用快速验证想法、构建复杂的多Agent工作流、需要大量现成工具集成。LlamaIndex专注于RAG和数据连接。它的Agent能力是建立在强大的数据索引和检索之上的。如果你的Agent核心任务是理解和处理私有数据、知识库LlamaIndex是更专精的选择。它通常与LangChain结合使用。适用构建基于企业文档、知识库的问答Agent、数据分析Agent。Spring AI (Java/Kotlin)或Semantic Kernel (.NET)面向企业级、特定技术栈。如果你所在的团队主要使用Java或.NET这些框架提供了与Spring生态或.NET生态无缝集成的Agent开发体验在类型安全、依赖注入、事务管理等方面有天然优势。适用Java/.NET技术栈的企业需要将AI Agent深度集成到现有微服务架构中。自研框架/轻量级封装极致控制与性能。就像我们上面的示例你可以只依赖OpenAI/Anthropic等LLM的SDK自己实现循环控制、工具路由和记忆管理。这给了你最大的灵活性和性能优化空间但需要自己处理所有细节。适用对性能有极致要求、任务模式非常固定且简单、或者作为学习目的深入理解原理。我的建议是从LangChain开始学习因为它对概念的封装最接近行业共识。用它快速搭建几个原型理解每个组件的作用。然后一定要像我们今天做的一样尝试抛开框架手写一个最简Loop。这个过程会让你真正理解框架在背后帮你做了什么。最后根据项目实际需求性能、团队技能、集成复杂度决定是深入使用某个框架还是在它的基础上做定制或者走向自研。6. 避坑指南那些只有踩过才知道的细节工具描述的“诅咒”给LLM的工具描述description至关重要。描述不清LLM不会用描述太长浪费Token且可能干扰判断。要用LLM能理解的语言清晰说明工具的用途、输入格式和输出示例。例如“输入一个城市名返回该城市当前的天气情况”比“获取天气数据”要好得多。Token消耗的隐形成本Agent Loop每一步都在消耗Token。一个复杂的多步任务其Token消耗可能是单次问答的十倍甚至百倍。在设计和优化时必须将Token成本作为一个核心指标。精简Prompt、优化记忆策略、选择性价比高的模型都是控制成本的关键。“沉默的失败”最可怕工具执行失败如网络错误但返回了一个模糊的Observation如“Error 500”LLM很可能无法理解并做出错误的后续决策。工具层必须返回对LLM友好的错误信息例如“网络请求失败未能获取到天气数据请检查网络或稍后重试。” 这能引导LLM采取合理行动如重试或告知用户。测试的复杂性测试一个Agent不像测试一个普通函数。你需要构建覆盖不同路径的“场景测试”简单任务、多步任务、需要回溯的任务、工具失败的任务、模糊的用户请求等。自动化测试需要模拟LLM的响应和工具的行为可以考虑使用LLM的Mock或本地小模型进行集成测试。Prompt是核心资产驱动整个Loop的System Prompt是你Agent的“宪法”。它的设计需要反复迭代和打磨。使用A/B测试对比不同Prompt下Agent完成任务的成功率、步骤数和成本。将有效的Prompt版本化管理起来。构建一个健壮的Agent Loop就像教一个聪明的孩子学会使用一套复杂的工具去解决问题。你需要定义清晰的规则Prompt提供好用的工具Tool在他犯错时给予明确的反馈Error Handling并在他兜圈子时及时引导Loop Control。这个过程没有银弹需要大量的实验、观察和调优。但一旦你掌握了它你就掌握了构建智能体应用最核心的引擎。