1. 从“工具”到“智能体”一个被误解的演进路径最近在社区里看到不少关于“AI Agent”的讨论尤其是像“mini-cursor”这类工具经常被拿来作为Agent实现的典型案例。但说实话很多讨论都停留在表面把Agent简单地理解为一个能调用几个API的“高级工具”或者一个加了循环的脚本。这其实是一个巨大的误解。我花了相当长的时间从最基础的Tool定义开始一步步拆解、构建最终跑通了一个具备自主决策和循环能力的Agent原型。这个过程让我深刻认识到从Tool到Agent绝不仅仅是加一个while循环那么简单它背后是一整套设计范式的转变。今天我就想抛开那些高大上的概念以一个实践者的角度聊聊我是如何理解并实现这个过程的。我们会从最根本的“工具”定义出发看看一个合格的Tool应该长什么样然后我们会探讨如何让这些工具“活”起来即构建一个能理解任务、选择工具、执行并反思的“大脑”也就是Agent的核心逻辑最后也是最关键的一步就是实现那个让Agent持续工作的“循环”机制。这个循环不是无脑的重复而是包含了状态管理、错误处理、目标校验的智能迭代。你会发现真正的难点往往不在代码本身而在于对问题边界的界定和逻辑链条的设计。无论你是想在自己的项目中引入Agent能力还是单纯对AI应用开发感兴趣这篇文章都会提供一个非常落地的视角。我们不谈空泛的理论只聚焦于可运行的代码和可复现的设计思路。准备好了吗让我们从最基础的一砖一瓦开始搭建。2. Tool 的本质超越函数封装的标准化接口在谈论Agent之前我们必须先厘清它的“手脚”——Tool。很多人把Tool等同于一个普通的函数或方法认为只要把功能封装起来能调用就行。这种理解过于狭隘也是后续构建Agent时出现各种混乱的根源。一个设计良好的Tool应该是一个标准化的、自描述的、可被智能体安全理解和调用的功能单元。2.1 Tool 的标准结构名称、描述与参数一个最基本的Tool至少需要包含三个核心要素这远比一个简单的函数签名要丰富。1. 名称 (Name):这不是随便起的。它应该是一个动词或动宾短语清晰、无歧义地表达这个工具的核心动作。例如search_web就比web或do_search要好得多。Agent在决策时会依赖这个名称来快速匹配意图。2. 描述 (Description):这是Tool的“自然语言说明书”。它需要详细说明这个工具是做什么的、在什么场景下使用、以及最重要的——它的局限性。例如“在互联网上搜索相关信息并返回最相关的几条摘要。注意无法访问需要登录的网站且结果可能包含过时信息。” 一段好的描述能极大提升Agent调用工具的准确率。3. 参数 (Parameters):需要明确定义每个参数的名称、类型、是否必需以及参数描述。现代AI框架如LangChain、LlamaIndex通常使用JSON Schema来定义。这不仅是为了类型安全更是为了让大语言模型LLM能准确理解需要提供什么信息。让我们看一个具体的例子一个用于查询天气的Tool定义以Python伪代码和结构化描述为例# 这是一个概念示例并非特定框架代码 weather_tool { “name”: “get_current_weather”, “description”: “获取指定城市的当前天气情况包括温度、天气状况和湿度。如果城市不存在将返回错误信息。”, “parameters”: { “type”: “object”, “properties”: { “location”: { “type”: “string”, “description”: “城市名称例如‘北京’ ‘San Francisco’” }, “unit”: { “type”: “string”, “enum”: [“celsius”, “fahrenheit”], “description”: “温度单位默认为‘celsius’摄氏度” } }, “required”: [“location”] }, “function”: _get_weather_impl # 背后实际执行的函数 }这个结构清晰地告诉Agent有一个工具叫get_current_weather它能查天气你需要给我一个location参数我还能选温度单位。2.2 实现背后的函数健壮性与错误处理Tool的描述是给Agent“看”的而其背后真正的执行函数才是实现功能的关键。这里的实现需要格外注重健壮性。输入验证 (Input Validation):即使在Schema中定义了类型在执行函数内部也应再次校验。例如location参数是否为空字符串是否包含非法字符错误处理 (Error Handling):网络请求可能超时API可能返回错误码数据库可能连接失败。执行函数必须能捕获所有可能的异常并将其转化为Tool执行层能理解的、结构化的错误信息返回给Agent而不是直接抛出异常导致整个流程崩溃。例如返回{“status”: “error”, “message”: “网络请求超时请稍后重试”}。结果标准化 (Result Standardization):执行结果也应该是一个结构化的对象至少包含执行状态成功/失败和具体数据。这有利于Agent以统一的方式解析不同工具的返回结果。def _get_weather_impl(location: str, unit: str “celsius”) - dict: “”“实际的天气查询逻辑”“” try: # 1. 参数清洗与验证 if not location or not isinstance(location, str): return {“status”: “error”, “data”: None, “message”: “城市名称不能为空且必须为字符串”} # 2. 调用第三方API api_response call_weather_api(location, unit) # 3. 处理API响应 if api_response.status_code 200: weather_data parse_response(api_response.json()) return {“status”: “success”, “data”: weather_data, “message”: “”} elif api_response.status_code 404: return {“status”: “error”, “data”: None, “message”: f“未找到城市‘{location}’的天气信息”} else: return {“status”: “error”, “data”: None, “message”: f“天气服务暂时不可用状态码{api_response.status_code}”} except requests.exceptions.Timeout: return {“status”: “error”, “data”: None, “message”: “查询超时请检查网络”} except Exception as e: # 捕获其他未预料异常避免进程终止 return {“status”: “error”, “data”: None, “message”: f“系统内部错误{str(e)}”}2.3 Tool 的注册与管理让 Agent 知其可用定义了多个Tool之后我们需要一个中心化的地方来管理它们这就是Tool Registry工具注册表。Agent在启动时会从注册表中加载所有可用的Tool及其描述。一个简单的注册表可以是一个字典或列表更复杂的系统可能会支持动态加载、权限控制、工具分组等功能。class ToolRegistry: def __init__(self): self._tools {} def register(self, tool: dict): “”“注册一个工具”“” if tool[“name”] in self._tools: raise ValueError(f“工具名称 ‘{tool[‘name’]}’ 已存在”) self._tools[tool[“name”]] tool def get_tool(self, name: str) - dict: “”“根据名称获取工具定义”“” return self._tools.get(name) def get_all_tools_descriptions(self) - list: “”“获取所有工具的描述信息用于提供给LLM”“” return [{ “name”: t[“name”], “description”: t[“description”], “parameters”: t[“parameters”] } for t in self._tools.values()] # 初始化注册表并注册工具 registry ToolRegistry() registry.register(weather_tool) registry.register(search_web_tool) # 假设有另一个搜索工具至此我们有了一个个标准、健壮、可被管理的“工具”。它们就像手术室里的器械整齐排列功能明确。接下来我们需要一位“主刀医生”——Agent来观察病情理解用户需求决定使用哪把器械选择工具并执行手术调用工具。3. Agent 核心决策、执行与状态管理的“大脑”拥有了功能明确的Tool之后我们面临的核心问题变成了如何根据一个模糊的、自然语言描述的用户请求自动选择正确的工具并执行这就是Agent的“大脑”要解决的问题。这个大脑通常由一个大语言模型驱动其核心工作流可以概括为规划 (Planning) - 执行 (Execution) - 观察 (Observation)的循环。但在第一次循环开始前还有一个至关重要的步骤任务理解与规划。3.1 任务解析与初步规划将指令转化为可操作步骤用户说“帮我查一下北京和上海的天气然后对比一下哪里更暖和。” 这显然不是一个Tool调用能完成的。Agent首先需要理解这个复合指令并将其分解成一系列有序的子任务。这个过程就是任务解析与规划。在实际实现中我们通常通过一个精心设计的系统提示词 (System Prompt)来引导LLM完成这个工作。提示词会告诉LLM它的角色、可用的工具、以及输出的格式要求。一个简化的规划阶段提示词可能如下你是一个任务规划助手。请根据用户的请求和可用的工具将复杂任务分解为一系列可执行的步骤。 每一步都应该是一个清晰的动作并且可以对应到一个具体的工具调用。 可用工具 {tools_descriptions} 用户请求{user_input} 请以以下JSON格式输出你的计划 { “plan”: [ {“step”: 1, “action”: “动作描述”, “tool”: “工具名”, “args”: {参数对象}}, {“step”: 2, …} ] }LLM根据这个提示可能会生成如下计划{ “plan”: [ {“step”: 1, “action”: “获取北京的当前天气”, “tool”: “get_current_weather”, “args”: {“location”: “北京”, “unit”: “celsius”}}, {“step”: 2, “action”: “获取上海的当前天气”, “tool”: “get_current_weather”, “args”: {“location”: “上海”, “unit”: “celsius”}}, {“step”: 3, “action”: “对比两地的温度数据”, “tool”: “compare_temperatures”, “args”: {“data_from_step”: 1, “data_from_step”: 2}} ] }这里出现了两个关键点第一我们假设有一个compare_temperatures工具可能需要我们自己实现一个简单的数据对比工具或者这一步由LLM直接分析完成。第二步骤间存在依赖关系第三步需要前两步的结果。如何传递这个依赖这就引出了状态管理。3.2 状态管理贯穿始终的上下文记忆Agent在执行过程中需要记住之前发生了什么。比如第一步查询北京天气的结果是什么这个结果需要被传递给后续的步骤使用。我们通常用一个状态字典 (State Dictionary)或上下文 (Context)对象来管理这些信息。状态中通常包含step_history: 已执行步骤的历史记录包括步骤号、使用的工具、参数、执行结果成功/失败、返回数据。intermediate_data: 中间数据例如{“beijing_weather”: {…}, “shanghai_weather”: {…}}方便后续步骤引用。current_goal: 当前要解决的核心问题或子目标。iteration_count: 循环次数用于防止无限循环。在每一步执行前Agent或规划器可以根据当前状态和原始目标决定下一步做什么。执行后将结果更新到状态中。这样整个任务就变成了一个在状态驱动下的有序操作序列。3.3 工具执行与结果整合连接规划与现实有了计划和当前状态Agent就可以执行具体的工具调用了。这个过程相对直接根据计划中的tool字段从Tool Registry中获取工具定义和对应的执行函数。准备参数。参数可能来自计划中静态定义的args也可能需要从state[‘intermediate_data’]中动态获取例如args: {“weather_data”: state[‘intermediate_data’][‘beijing_weather’]}。调用工具函数获取结构化结果。将执行结果无论成功失败记录到state[‘step_history’]中并将有用的数据提取到state[‘intermediate_data’]。如果工具执行失败返回status: “error”Agent不能简单地继续下一步。它需要根据错误信息决定是重试、更换参数、选择替代工具还是向用户求助。这就进入了观察与反思环节也是驱动循环的关键。4. 循环引擎驱动智能迭代与自我修正“循环”是Agent区别于单次工具调用的最显著特征。但这个循环不是while True那么简单而是一个受控的、有状态的、具备反思能力的迭代过程。我将其称为“循环引擎”它负责管理整个Agent的生命周期。4.1 循环的基本结构REPL 模式一个经典的Agent循环遵循REPL模式读取 (Read) - 评估 (Eval) - 打印 (Print) - 循环 (Loop)在Agent场景下可以理解为观察状态 - 决策/规划 - 执行动作 - 更新状态并循环。其核心控制流伪代码如下def run_agent_loop(initial_input: str, tool_registry: ToolRegistry, max_iterations: int 10): “”“运行Agent主循环”“” # 初始化状态 state { “original_input”: initial_input, “step_history”: [], “intermediate_data”: {}, “current_goal”: initial_input, “iteration”: 0, “is_complete”: False, “final_answer”: None } while state[“iteration”] max_iterations and not state[“is_complete”]: state[“iteration”] 1 print(f“\n 迭代第 {state[‘iteration’]} 次 ) # 1. 观察与决策 (Read Eval)基于当前状态决定下一步做什么 # 这通常通过调用LLM来完成LLM根据state和可用工具输出下一步指令或判断任务是否完成 decision make_decision(state, tool_registry) if decision[“action”] “call_tool”: # 2. 执行 (Print - Act)调用工具 tool_name decision[“tool_name”] tool_args decision[“tool_args”] tool_result execute_tool(tool_registry, tool_name, tool_args) # 3. 更新状态 (Loop)记录结果 state[“step_history”].append({ “iteration”: state[“iteration”], “tool”: tool_name, “args”: tool_args, “result”: tool_result }) # 将结果数据存入中间数据区供后续步骤参考 if tool_result[“status”] “success”: state[“intermediate_data”][f“step_{state[‘iteration’]}_result”] tool_result[“data”] # 4. 检查终止条件 (Loop Condition) # 例如判断是否已收集到足够信息来回答原始问题 state[“is_complete”], state[“final_answer”] check_completion(state, initial_input) elif decision[“action”] “final_answer”: # LLM认为可以直接给出最终答案了 state[“is_complete”] True state[“final_answer”] decision[“answer”] elif decision[“action”] “ask_user”: # 需要向用户澄清或获取更多信息 user_feedback ask_user_for_clarification(decision[“question”]) state[“intermediate_data”][“user_feedback”] user_feedback # 将用户反馈融入状态继续循环 if not state[“is_complete”]: state[“final_answer”] “任务未能在最大迭代次数内完成。请尝试更具体的指令。” return state4.2 决策函数Agent 的“思考”过程make_decision函数是循环引擎的核心。它通常封装了一次对LLM的调用其提示词需要精心设计以引导LLM进行“思考”。这个提示词需要包含系统角色定义你是谁一个AI助手当前任务和目标用户最初问了什么可用工具列表及其详细描述你能做什么当前执行状态和历史你已经做了什么得到了什么结果输出格式指令你必须以指定的JSON格式回答包含下一步动作。一个决策提示词的片段示例当前任务{state[‘original_input’]} 到目前为止我们已经执行了以下步骤 {format_step_history(state[‘step_history’])} 目前掌握的中间信息 {format_intermediate_data(state[‘intermediate_data’])} 请根据以上信息决定下一步行动。你有以下选择 A. 调用工具如果认为需要某个工具来获取信息或执行操作。 B. 直接给出最终答案如果认为已有足够信息回答用户问题。 C. 向用户提问如果需要澄清或获取更多信息。 如果你选择A请输出 {“action”: “call_tool”, “tool_name”: “工具名”, “tool_args”: {参数}, “reasoning”: “选择该工具的原因”} 如果你选择B请输出 {“action”: “final_answer”, “answer”: “你的最终答案”, “reasoning”: “为什么现在可以给出答案”} ...LLM的输出会被解析驱动下一步的行动。这个“思考-行动-观察”的闭环就是智能循环的本质。4.3 错误处理与循环终止避免陷入死胡同循环必须要有明确的退出机制否则会陷入死循环。常见的终止条件包括成功终止LLM决策为final_answer并且答案经过校验例如可以再用一个简单的LLM调用判断答案是否直接回应了原始问题。失败终止达到最大迭代次数max_iterations这是一个安全阀。用户干预终止在需要用户反馈的环节用户输入了“取消”或超时未回复。逻辑错误终止连续多次工具调用失败或LLM决策陷入重复模式例如连续三次调用同一个工具且参数相同但都失败。在工具调用失败时循环引擎不应立即放弃。make_decision函数在接收到失败结果后其提示词应能引导LLM进行反思例如“上一步调用get_current_weather失败原因是‘城市不存在’。请重新评估你的计划。” LLM可能会尝试更换城市名参数或者选择另一个工具如search_web来查询城市标准名称从而体现出自我修正的能力。5. 实战整合构建一个简易的“旅行规划助手”理论说了这么多我们用一个具体的、简化的例子来串起整个流程构建一个能理解“我想去一个温暖的海边城市度周末帮我看看天气和推荐景点”这类请求的旅行规划助手。5.1 定义工具集我们需要三个核心工具get_current_weather: 同前文查询天气。search_city_info: 一个模拟工具根据关键词如“温暖海边城市”返回一些候选城市列表例如三亚、厦门、青岛。get_attractions: 另一个模拟工具根据城市名返回该城市的几个热门景点。这些工具都按照第2章的标准进行定义和实现并注册到ToolRegistry中。5.2 设计 Agent 工作流初始请求用户输入“我想去一个温暖的海边城市度周末帮我看看天气和推荐景点。”第一轮决策 (迭代1)make_decision函数结合工具描述LLM可能决定先调用search_city_info参数为{“keyword”: “温暖 海边 城市”}。执行工具返回[“三亚”, “厦门”, “青岛”]。状态更新intermediate_data[“candidate_cities”] [“三亚”, “厦门”, “青岛”]。第二轮决策 (迭代2)LLM观察状态发现有了候选城市但还需要天气信息来做决定。它可能决定调用get_current_weather但面对三个城市它需要决定先查哪个。一种策略是依次查询也可能在提示词中引导LLM选择第一个城市。假设它选择查询三亚{“location”: “三亚”, “unit”: “celsius”}。执行工具返回三亚天气例如28°C晴。状态更新intermediate_data[“sanya_weather”] {…}。后续迭代循环继续LLM可能会继续查询厦门和青岛的天气并将所有天气数据收集齐。然后LLM基于天气数据比如判断哪个最“温暖”选择一个城市。假设它选择了三亚。接着LLM调用get_attractions获取三亚的景点{“city”: “三亚”}。最后LLM综合天气和景点信息判断已有足够资料决策动作变为final_answer生成一段推荐文本“推荐你去三亚度周末目前天气温暖晴朗28摄氏度。推荐的景点有亚龙湾、天涯海角、南山寺等。”循环终止任务完成输出最终答案。5.3 实现中的关键细节与避坑指南在实际编码实现这个流程时你会遇到一些教科书上不会写的坑1. 提示词工程是成败关键具体性给LLM的工具描述和指令必须极其具体。不要说“你可以搜索”而要说“你可以使用search_web工具在互联网上查找信息该工具接受一个查询字符串作为参数”。格式强制要求LLM以JSON格式输出决策并在代码中做好解析和异常处理。如果LLM返回了非JSON内容要有降级策略如提示其重试或转为向用户求助。思维链 (Chain-of-Thought) 鼓励在决策提示词中要求LLM输出“reasoning”字段写明它的思考过程。这不仅能提高决策质量也极大方便了调试。当Agent做出错误决策时查看它的“推理过程”比只看结果更有用。2. 状态设计要面向LLMintermediate_data里的数据结构要尽量简单、扁平方便在提示词中以文本形式清晰呈现给LLM。避免复杂的嵌套对象。可以使用清晰的键名如weather_beijing,search_results_page1。3. 控制循环成本与超时迭代次数限制 (max_iterations)必须设置通常5-15次防止复杂任务或无解任务消耗过多资源。单次工具调用超时每个工具函数都应设置超时避免因某个外部服务挂起导致整个Agent卡死。总时间预算除了迭代次数还可以设置总运行时间上限。4. 处理LLM的“固执”与“幻觉”有时LLM会陷入一个错误决策循环。例如它坚信某个工具需要某个参数但那个参数就是获取不到。除了在提示词中强调“如果工具调用连续失败请尝试其他方案”外还可以在代码层面实现一种“断路器”机制如果同一个工具在连续3次迭代中因同样原因失败则强制在状态中标记该工具暂时不可用并在提示词中告知LLM引导它寻找替代路径。5. 验证最终答案不要盲目相信LLM给出的final_answer。可以增加一个轻量级的验证步骤例如用一个非常简短的提示词让另一个LLM调用或规则判断来评估“给定的答案是否直接回应了原始问题是/否”。如果否则可以将此作为反馈重新注入状态让循环继续。从定义一个规范的Tool到构建一个能自主规划、执行、循环的Agent这个过程就像在教一个聪明的孩子如何使用一套复杂的工具箱来完成项目。你需要清晰地定义每件工具的用途Tool描述教会他如何根据目标制定计划规划在他执行时给予必要的上下文和记忆状态管理并在遇到困难时引导他反思和调整策略循环与错误处理。最终这个“孩子”就能独立处理一系列复杂的任务。这其中的每一步都充满了工程上的细节和设计上的权衡而正是这些细节决定了一个Agent是真正智能的助手还是一个容易崩溃的脆弱脚本。