2026/8/18 2:00:03
FEATURED · 精选文章 
最近两年AI Agent智能体这个词的热度几乎盖过了所有单一的大模型应用。打开任何一个技术社区都能看到关于Agent的讨论、教程和开源项目。但一个很普遍的现象是很多开发者包括一些有一定经验的工程师在尝试搭建自己的第一个Agent时常常会陷入一种“跑通Demo即成功”的误区。你可能会跟着一个教程用几行代码调用大模型的API让Agent回答一个问题或者执行一个简单的任务。流程走通了界面有反应了于是你觉得“我学会了”。但当你试图把这个Demo改造成一个能处理真实业务、能稳定运行、能应对各种边界情况的“企业级”应用时问题就接踵而至对话上下文怎么管理工具调用失败了怎么重试多个Agent如何协作状态如何持久化如何监控和调试这背后的根本原因在于我们常常混淆了“概念验证”和“工程实现”。前者是证明一件事理论上可行后者是确保这件事在复杂、多变、不可预测的现实环境中可靠、高效、可维护地运行。今天我们不谈那些浮于表面的“零基础入门”而是直接切入核心从一次成功的Demo到一个真正可用的企业级AI Agent中间到底隔着哪些必须跨越的鸿沟我们又该如何系统性地搭建它1. 理解AI Agent它不只是“会调用工具的ChatGPT”在开始动手之前我们必须先统一认知到底什么是AI Agent很多人把它简单理解为“能使用工具的ChatGPT”。这个理解没错但太浅它只描述了表象没触及本质。1.1 智能体的核心是“感知-思考-行动”的循环一个真正的AI Agent应该被视为一个自主的、目标驱动的软件实体。它的核心工作模式是一个持续的循环感知接收来自环境的信息用户输入、系统状态、工具执行结果等。思考基于内部状态记忆、目标、知识和感知到的信息进行推理和规划决定下一步要做什么。行动执行决策可能是调用一个工具Tool、生成一段回复、或者修改内部状态。观察结果行动会改变环境产生新的可感知信息循环继续。这个循环的关键在于“自主性”和“目标驱动”。它不是为了回答单个问题而是为了完成一个可能由多个步骤组成的复杂目标。比如一个订票Agent的目标是“为用户预订一张下周五从北京到上海的最便宜机票”。这个目标需要它自主地执行查询航班信息、比价、选择航班、填写乘客信息、完成支付等一系列动作。1.2 从“单次问答”到“持续会话”状态管理是分水岭传统的聊天机器人或简单的API调用往往是无状态的。每次请求都是独立的模型不知道上一次对话发生了什么。而Agent必须是有状态的。它需要记住会话历史用户说了什么它回复了什么工具返回了什么结果。任务目标当前正在执行什么任务进展到哪一步了。内部信念基于已有信息它对世界或当前任务的认知是什么。这种状态管理能力是将一系列离散的“单次调用”串联成一个连贯的“任务流程”的基础。没有良好的状态管理Agent就无法处理需要多轮交互的复杂任务。1.3 工具使用能力延伸也是风险来源Agent通过调用工具Tools来扩展其能力边界这是它最吸引人的特性之一。工具可以是信息获取类搜索引擎、数据库查询、API数据抓取。动作执行类发送邮件、操作文件、控制智能设备、执行代码。计算与处理类调用计算引擎、运行数据分析脚本。然而工具调用也是Agent系统中最不稳定、最易出错的环节。网络超时、API变更、权限不足、输入格式错误、结果解析失败……任何一个环节出错都可能导致整个任务链中断。因此一个健壮的Agent必须包含完善的工具调用异常处理机制。理解了这三点我们就能明白搭建一个企业级Agent远不止是写一个调用大模型和工具的脚本。它本质上是在设计一个具备一定自主决策能力的微型软件系统。接下来我们就从零开始看看如何搭建这样一个系统。2. 搭建基石从零开始构建你的第一个Agent框架市面上已经有很多优秀的Agent框架如LangChain、LlamaIndex、AutoGen等。但在深入使用它们之前我强烈建议你先抛开框架用最基础的代码实现一个最小可用的Agent。这个过程能让你透彻理解Agent的每个核心组件是如何工作的未来在使用高级框架时你才能知其然并知其所以然能进行深度定制和问题排查。我们的目标是构建一个能完成“查询天气并给出穿衣建议”的简单Agent。它需要调用一个天气查询工具。2.1 第一步定义清晰的任务规划与工具系统首先我们需要明确Agent的核心组件大脑大语言模型LLM负责思考和决策。工具库Agent可以调用的外部函数集合。记忆体存储会话历史和任务状态。执行引擎协调以上组件运行“感知-思考-行动”循环。我们先从工具定义开始。一个工具至少需要名称、描述、参数列表、执行函数。# 工具定义示例 class Tool: def __init__(self, name, description, func, parameters): self.name name self.description description self.func func self.parameters parameters # 参数格式描述用于提示词 # 模拟一个天气查询工具 def get_weather(city: str) - str: # 这里应该是调用真实天气API我们模拟返回 weather_data { 北京: 晴15-25°C微风, 上海: 多云18-28°C东南风3级, 深圳: 阵雨22-30°C南风4级, } return weather_data.get(city, f未找到{city}的天气信息) weather_tool Tool( nameget_weather, description根据城市名称查询当前天气情况。, funcget_weather, parameters{city: string} # 简单表示参数类型 )2.2 第二步设计提示词工程——给Agent“注入灵魂”Agent的“思考”能力完全由提示词Prompt引导。一个好的提示词需要明确告诉LLM你的角色是什么。你有什么工具可用每个工具是干什么的怎么用。你应该遵循什么样的思考流程。你该如何组织你的输出以便执行引擎能理解。我们采用一种简单但有效的“ReAct”模式Reasoning Acting提示词def build_system_prompt(tools): tools_desc \n.join([f- {t.name}: {t.description} 参数: {t.parameters} for t in tools]) return f 你是一个有帮助的AI助手。你可以使用以下工具 {tools_desc} 请严格按照以下格式思考和回应 Thought: 你需要先思考当前情况分析用户目标并决定下一步行动。 Action: 如果你需要调用工具请输出工具名称。格式为: Action: tool_name Action Input: 调用工具所需的输入必须是合法的JSON字符串。格式为: Action Input: input_json Observation: 工具调用的结果会在这里提供给你。 当你最终得出答案时请输出 Final Answer: 你的最终回答 现在开始与用户对话。记住除非用户要求或必要不要主动调用工具。 用户{{user_input}} 这个提示词强制LLM以结构化的方式输出便于我们解析它的“思考”和“决策”。2.3 第三步实现核心执行循环——感知、思考、行动的引擎这是Agent的“心脏”。它将循环执行解析用户输入和上轮结果 - 组合提示词 - 调用LLM - 解析LLM输出 - 执行工具或返回答案。import json import re class SimpleAgent: def __init__(self, llm_client, tools): self.llm llm_client # 假设这是一个能调用LLM API的客户端 self.tools {t.name: t for t in tools} self.conversation_history [] # 简单的记忆体 def run(self, user_input): self.conversation_history.append(fUser: {user_input}) full_prompt self._construct_prompt(user_input) max_turns 5 # 防止死循环 for _ in range(max_turns): # 1. 思考与决策 llm_response self.llm.generate(full_prompt) self.conversation_history.append(fAssistant: {llm_response}) # 2. 解析LLM输出 thought, action, action_input, final_answer self._parse_response(llm_response) if final_answer: self.conversation_history.append(fFinal Answer: {final_answer}) return final_answer if action and action in self.tools: # 3. 执行行动 try: params json.loads(action_input) if action_input else {} tool_result self.tools[action].func(**params) observation fObservation: {tool_result} except Exception as e: observation fObservation: Tool call failed with error: {str(e)} # 4. 将观察结果加入历史进入下一轮循环 self.conversation_history.append(observation) full_prompt f\n{observation}\n else: # 如果解析不出有效动作可能LLM不听话直接返回或报错 return Im not sure how to handle that. return I seem to be stuck in a loop. Please try rephrasing your request. def _construct_prompt(self, user_input): # 组合系统提示词和会话历史 history \n.join(self.conversation_history[-6:]) # 只保留最近几轮防止上下文过长 base_prompt build_system_prompt(list(self.tools.values())) return base_prompt.format(user_inputuser_input) f\n{history} def _parse_response(self, response): # 使用正则表达式解析Thought, Action, Action Input, Final Answer thought re.search(rThought:\s*(.*?)(?\nAction:|\nFinal Answer:|$), response, re.DOTALL) action re.search(rAction:\s*(\w), response) action_input re.search(rAction Input:\s*(.*?)(?\nObservation:|\nFinal Answer:|$), response, re.DOTALL) final_answer re.search(rFinal Answer:\s*(.*?)$, response, re.DOTALL) return ( thought.group(1).strip() if thought else None, action.group(1) if action else None, action_input.group(1).strip() if action_input else None, final_answer.group(1).strip() if final_answer else None, )2.4 第四步运行与验证——看到第一个“活”的Agent现在我们可以初始化并运行这个Agent了假设你已有一个LLM客户端如OpenAI、通义千问等API的封装。# 伪代码展示调用流程 llm_client YourLLMClient(api_keyyour_key) agent SimpleAgent(llm_client, tools[weather_tool]) response agent.run(北京今天天气怎么样) print(response) # 理想输出 Thought: 用户想查询北京天气我需要调用get_weather工具。 # Action: get_weather # Action Input: {city: 北京} # Observation: 晴15-25°C微风 # Thought: 我已获得天气信息可以直接回答用户。 # Final Answer: 北京今天天气是晴气温在15到25摄氏度之间有微风。 response agent.run(那我应该穿什么) print(response) # 理想输出 Agent能结合之前的天气信息存储在history中进行推理并给出穿衣建议。通过这个从零搭建的过程你亲手实现了Agent最核心的循环。你会深刻理解提示词如何引导模型、工具调用如何衔接、状态如何在不同轮次间传递。这是所有高级框架底层都在做的事情。有了这个基础我们再去看LangChain等框架就会明白它们的AgentExecutor、Tool类、Memory模块到底在抽象什么以及当出现问题时应该从哪个层面去调试。3. 走向企业级必须补上的四块关键拼图一个能在个人电脑上跑通的Demo距离能在生产环境服务真实用户的“企业级Agent”还差得很远。企业级应用的核心要求是可靠、可维护、可监控、可扩展。我们的简单Agent需要从以下四个维度进行强化。3.1 拼图一健壮的工具调用与异常处理我们的简单实现里工具调用失败只有一个简单的异常捕获。在生产环境中这远远不够。重试机制网络请求可能临时失败。对于非幂等操作如支付需谨慎对于查询类操作可以设置指数退避重试。超时控制每个工具调用必须设置超时防止一个慢速工具拖垮整个Agent会话。结果验证与格式化工具返回的结果可能是混乱的JSON、HTML或纯文本。需要有一套机制来清洗和标准化结果再喂给LLM否则可能导致LLM解析错误。熔断与降级如果某个工具持续失败应能暂时将其“熔断”避免持续请求并尝试使用备用工具或给出降级回答。# 增强版工具调用示例 def safe_tool_call(tool_func, params, max_retries3, timeout10): for attempt in range(max_retries): try: # 使用带超时的执行方式具体实现取决于工具 result tool_func(**params) # 验证结果格式 validated_result validate_and_format_result(result) return validated_result except TimeoutError: if attempt max_retries - 1: return Error: Tool call timed out. except Exception as e: if attempt max_retries - 1: return fError: Tool call failed after {max_retries} attempts. Last error: {str(e)} time.sleep(2 ** attempt) # 指数退避 return Error: Max retries exceeded.3.2 拼图二可持续的会话与记忆管理我们之前的conversation_history是一个简单的列表存在很大问题上下文长度限制LLM有token限制历史对话不能无限增长。信息重要性不同不是所有历史对话都对当前任务同等重要。长期记忆与短期记忆用户可能希望Agent记住一些长期信息如偏好而不只是最近几次对话。企业级应用需要更复杂的记忆系统摘要式记忆当对话历史过长时自动将早期对话总结成一段摘要保留核心信息节省token。向量记忆将对话中的关键信息如用户提到的产品、需求存入向量数据库实现基于语义的长期记忆检索。分层记忆区分会话级记忆本次聊天和用户级记忆该用户的长期信息。3.3 拼图三全面的可观测性与调试支持当Agent在线上出现逻辑错误、性能低下或给出奇怪回答时如何快速定位问题你需要可观测性。全链路日志记录每一轮循环的完整信息用户输入、LLM的原始响应、解析后的Thought/Action、工具调用的输入输出、最终答案。这些日志需要结构化存储便于查询。性能指标监控每个环节的耗时LLM响应时间、工具调用时间、Token消耗量、工具调用成功率等。追踪与可视化能够像分布式系统调用链一样可视化一次用户请求在Agent内部经历了哪些步骤每个步骤的输入输出是什么。这对于调试复杂任务流至关重要。3.4 拼图四任务分解、规划与多Agent协作简单Agent只能处理线性任务。复杂任务如“帮我规划一个三天的北京旅游行程并预订第一天的酒店和机票”需要任务分解与规划能力。规划模块让LLM先将大目标拆解成一系列有序的子任务。子任务执行与状态管理依次或并行执行子任务并管理整体任务状态哪些完成了哪些失败了下一步该做什么。多Agent协作对于超复杂任务可以引入多个具有专长的Agent如一个负责信息收集一个负责规划一个负责执行让它们通过通信机制协同工作。这涉及到更复杂的架构设计如基于Actor模型或发布订阅模式。补上这四块拼图你的Agent才初步具备了处理真实业务场景的“体质”。它不再是一个脆弱的脚本而是一个有弹性、可追溯、能处理一定复杂度的软件服务。4. 框架选型与实战LangChain / Dify / 自研如何选择理解了底层原理和工程化要求后我们再来看具体的工具和框架选择。市面上选择很多主要分为三类特性维度LangChain / LlamaIndex (开发框架)Dify / Coze / 扣子 (低代码平台)完全自研核心定位为开发者提供的SDK和框架高度灵活可深度定制。提供可视化界面的应用构建平台开箱即用强调快速搭建。从零开始完全控制。灵活性极高。可以自定义每一个组件集成任何模型、工具、记忆系统。较低。受限于平台提供的组件、工作流和模型支持。最高。但也最复杂。开发成本中等。需要编写代码但框架处理了大量样板代码。极低。拖拽式配置无需或只需少量代码。极高。所有轮子都要自己造。可控性与深度高。可以深入底层优化性能实现复杂逻辑。低。底层是黑盒遇到平台限制或特殊需求时无能为力。最高。适合场景1. 复杂、定制化需求高的企业应用。2. 需要与现有系统深度集成。3. 研究和探索前沿Agent架构。1. 快速原型验证和内部工具搭建。2. 对编程不熟悉的业务人员构建简单应用。3. 功能需求完全在平台能力范围内。1. 有极特殊的性能、安全或架构要求。2. 技术实力雄厚且Agent是核心业务壁垒。工程化支持需要自己搭建日志、监控、部署、扩展。但社区生态丰富有大量参考。平台通常提供基础的发布、监控和版本管理。全部需要自己实现。给开发者的建议学习与原型阶段可以从LangChain开始。它的抽象层次很好能让你快速搭建出结构清晰的Agent同时又不屏蔽底层细节适合学习。用它实现我们第二章的“天气Agent”代码会简洁很多。内部工具与快速交付如果需求不复杂且追求速度Dify这类平台是很好的选择。可以在几小时内搭建一个可用的聊天机器人或内容生成工具。严肃的企业级项目LangChain通常是更稳妥的选择。它提供了坚实的基础组件同时允许你在需要时替换或自定义任何部分。你可以基于LangChain构建同时逐步融入你自己的记忆系统、工具调用层和监控模块。自研除非你有非常充分的理由如极致的性能要求、特殊硬件环境、或Agent本身就是你的核心产品否则不建议从头自研。LangChain等开源框架的生态和社区支持能节省你大量时间。以LangChain为例快速重构天气Agentfrom langchain.agents import initialize_agent, AgentType from langchain.tools import Tool from langchain.llms import OpenAI # 或其他LLM from langchain.memory import ConversationBufferMemory # 1. 定义工具和之前类似 def get_weather(city: str) - str: weather_data {北京: 晴15-25°C, 上海: 多云18-28°C} return weather_data.get(city, 未找到信息) weather_tool Tool( nameGetWeather, funcget_weather, description查询城市天气。输入应为城市名称字符串。 ) # 2. 初始化LLM和记忆 llm OpenAI(temperature0, openai_api_keyyour_key) memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 3. 创建并运行Agent tools [weather_tool] agent initialize_agent( tools, llm, agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION, # 选择一种Agent类型 memorymemory, verboseTrue # 打印详细执行过程便于调试 ) response agent.run(北京天气如何) print(response) # LangChain会帮你处理ReAct格式的解析、工具调用、历史管理。使用框架后代码简洁性大幅提升但你必须通过阅读文档和源码理解其背后的AgentExecutor是如何工作的这样才能在出问题时进行有效调试。5. 避坑指南新手搭建Agent最常遇到的五个“坑”结合大量实践我总结了新手在搭建Agent时最容易踩的五个坑以及如何规避。5.1 坑一盲目追求复杂忽视单点验证现象一开始就想做一个“全能助理”集成十几个工具规划复杂任务链。问题复杂度爆炸任何一个工具或逻辑出错都难以定位。建议从“一个工具一个明确任务”开始。先让Agent能稳定可靠地完成“查天气”这一件事。确保它的提示词、工具调用、结果解析全链路畅通。然后再逐步增加第二个工具如“查航班”并测试两个工具间的协作。采用增量式开发。5.2 坑二提示词过于简单或混乱现象Agent行为不可控经常不按预期调用工具或胡言乱语。问题提示词没有清晰定义角色、约束和输出格式。建议明确指令在系统提示词开头就定下基调。“你是一个专注于完成XXX任务的助手必须严格按照以下步骤和格式工作。”结构化输出强制要求LLM以Thought:Action:Final Answer:等格式输出。这能极大提高解析的可靠性。提供示例在提示词中提供1-2个完整的对话示例Few-shot Learning让LLM更好地理解你的期望。5.3 坑三忽视上下文管理与Token消耗现象对话进行到后面Agent“失忆”了或者API调用因超长而失败、费用激增。问题没有对会话历史进行有效的管理和裁剪。建议设定历史窗口只保留最近N轮对话。实现摘要功能当历史过长时调用LLM对早期对话进行总结用摘要替代原始文本。选择性记忆只将与当前任务强相关的历史信息放入上下文。可以利用向量检索来实现。5.4 坑四工具调用没有防御性编程现象工具API变更、网络波动、输入异常导致整个Agent崩溃。问题工具调用层缺乏异常处理、重试、超时和结果验证。建议如第三章所述为每个工具调用包装一层健壮的安全调用器处理各类异常并返回结构化的错误信息供LLM或上层逻辑处理。5.5 坑五没有规划评估与监控体系现象Agent上线后不知道它运行得好不好哪里慢用户常问什么经常出什么错。问题缺乏可观测性。建议在开发初期就引入日志和监控。至少记录用户Query、Agent的完整思考过程、工具调用详情输入、输出、耗时、状态、最终回复。这些数据是后续优化提示词、改进工具、分析用户需求的黄金资料。搭建一个能用的AI Agentdemo可能只需要一个下午。但构建一个能在真实业务中创造价值、稳定运行的企业级智能体是一个系统工程。它考验的不仅仅是你对LLM API的调用能力更是你对软件架构、异常处理、状态管理和用户体验的综合理解。我的建议是不要急于求成从最小闭环开始。先深入理解“感知-思考-行动”这个核心循环亲手实现它。然后像搭积木一样逐步为你的Agent加上健壮的工具层、可持续的记忆系统、可观测的监控模块。在这个过程中善用LangChain这样的成熟框架来提升效率但永远保持对底层原理的好奇。AI Agent的世界才刚刚开始真正的挑战和乐趣不在于复现一个炫酷的演示而在于让这些智能体真正理解我们的意图可靠地执行任务并无缝融入我们复杂的工作流之中。这条路需要更多的工程师带着系统的思维和务实的态度一步步去探索和构建。
从Demo到企业级应用：AI Agent工程化实战指南
最近两年AI Agent智能体这个词的热度几乎盖过了所有单一的大模型应用。打开任何一个技术社区都能看到关于Agent的讨论、教程和开源项目。但一个很普遍的现象是很多开发者包括一些有一定经验的工程师在尝试搭建自己的第一个Agent时常常会陷入一种“跑通Demo即成功”的误区。你可能会跟着一个教程用几行代码调用大模型的API让Agent回答一个问题或者执行一个简单的任务。流程走通了界面有反应了于是你觉得“我学会了”。但当你试图把这个Demo改造成一个能处理真实业务、能稳定运行、能应对各种边界情况的“企业级”应用时问题就接踵而至对话上下文怎么管理工具调用失败了怎么重试多个Agent如何协作状态如何持久化如何监控和调试这背后的根本原因在于我们常常混淆了“概念验证”和“工程实现”。前者是证明一件事理论上可行后者是确保这件事在复杂、多变、不可预测的现实环境中可靠、高效、可维护地运行。今天我们不谈那些浮于表面的“零基础入门”而是直接切入核心从一次成功的Demo到一个真正可用的企业级AI Agent中间到底隔着哪些必须跨越的鸿沟我们又该如何系统性地搭建它1. 理解AI Agent它不只是“会调用工具的ChatGPT”在开始动手之前我们必须先统一认知到底什么是AI Agent很多人把它简单理解为“能使用工具的ChatGPT”。这个理解没错但太浅它只描述了表象没触及本质。1.1 智能体的核心是“感知-思考-行动”的循环一个真正的AI Agent应该被视为一个自主的、目标驱动的软件实体。它的核心工作模式是一个持续的循环感知接收来自环境的信息用户输入、系统状态、工具执行结果等。思考基于内部状态记忆、目标、知识和感知到的信息进行推理和规划决定下一步要做什么。行动执行决策可能是调用一个工具Tool、生成一段回复、或者修改内部状态。观察结果行动会改变环境产生新的可感知信息循环继续。这个循环的关键在于“自主性”和“目标驱动”。它不是为了回答单个问题而是为了完成一个可能由多个步骤组成的复杂目标。比如一个订票Agent的目标是“为用户预订一张下周五从北京到上海的最便宜机票”。这个目标需要它自主地执行查询航班信息、比价、选择航班、填写乘客信息、完成支付等一系列动作。1.2 从“单次问答”到“持续会话”状态管理是分水岭传统的聊天机器人或简单的API调用往往是无状态的。每次请求都是独立的模型不知道上一次对话发生了什么。而Agent必须是有状态的。它需要记住会话历史用户说了什么它回复了什么工具返回了什么结果。任务目标当前正在执行什么任务进展到哪一步了。内部信念基于已有信息它对世界或当前任务的认知是什么。这种状态管理能力是将一系列离散的“单次调用”串联成一个连贯的“任务流程”的基础。没有良好的状态管理Agent就无法处理需要多轮交互的复杂任务。1.3 工具使用能力延伸也是风险来源Agent通过调用工具Tools来扩展其能力边界这是它最吸引人的特性之一。工具可以是信息获取类搜索引擎、数据库查询、API数据抓取。动作执行类发送邮件、操作文件、控制智能设备、执行代码。计算与处理类调用计算引擎、运行数据分析脚本。然而工具调用也是Agent系统中最不稳定、最易出错的环节。网络超时、API变更、权限不足、输入格式错误、结果解析失败……任何一个环节出错都可能导致整个任务链中断。因此一个健壮的Agent必须包含完善的工具调用异常处理机制。理解了这三点我们就能明白搭建一个企业级Agent远不止是写一个调用大模型和工具的脚本。它本质上是在设计一个具备一定自主决策能力的微型软件系统。接下来我们就从零开始看看如何搭建这样一个系统。2. 搭建基石从零开始构建你的第一个Agent框架市面上已经有很多优秀的Agent框架如LangChain、LlamaIndex、AutoGen等。但在深入使用它们之前我强烈建议你先抛开框架用最基础的代码实现一个最小可用的Agent。这个过程能让你透彻理解Agent的每个核心组件是如何工作的未来在使用高级框架时你才能知其然并知其所以然能进行深度定制和问题排查。我们的目标是构建一个能完成“查询天气并给出穿衣建议”的简单Agent。它需要调用一个天气查询工具。2.1 第一步定义清晰的任务规划与工具系统首先我们需要明确Agent的核心组件大脑大语言模型LLM负责思考和决策。工具库Agent可以调用的外部函数集合。记忆体存储会话历史和任务状态。执行引擎协调以上组件运行“感知-思考-行动”循环。我们先从工具定义开始。一个工具至少需要名称、描述、参数列表、执行函数。# 工具定义示例 class Tool: def __init__(self, name, description, func, parameters): self.name name self.description description self.func func self.parameters parameters # 参数格式描述用于提示词 # 模拟一个天气查询工具 def get_weather(city: str) - str: # 这里应该是调用真实天气API我们模拟返回 weather_data { 北京: 晴15-25°C微风, 上海: 多云18-28°C东南风3级, 深圳: 阵雨22-30°C南风4级, } return weather_data.get(city, f未找到{city}的天气信息) weather_tool Tool( nameget_weather, description根据城市名称查询当前天气情况。, funcget_weather, parameters{city: string} # 简单表示参数类型 )2.2 第二步设计提示词工程——给Agent“注入灵魂”Agent的“思考”能力完全由提示词Prompt引导。一个好的提示词需要明确告诉LLM你的角色是什么。你有什么工具可用每个工具是干什么的怎么用。你应该遵循什么样的思考流程。你该如何组织你的输出以便执行引擎能理解。我们采用一种简单但有效的“ReAct”模式Reasoning Acting提示词def build_system_prompt(tools): tools_desc \n.join([f- {t.name}: {t.description} 参数: {t.parameters} for t in tools]) return f 你是一个有帮助的AI助手。你可以使用以下工具 {tools_desc} 请严格按照以下格式思考和回应 Thought: 你需要先思考当前情况分析用户目标并决定下一步行动。 Action: 如果你需要调用工具请输出工具名称。格式为: Action: tool_name Action Input: 调用工具所需的输入必须是合法的JSON字符串。格式为: Action Input: input_json Observation: 工具调用的结果会在这里提供给你。 当你最终得出答案时请输出 Final Answer: 你的最终回答 现在开始与用户对话。记住除非用户要求或必要不要主动调用工具。 用户{{user_input}} 这个提示词强制LLM以结构化的方式输出便于我们解析它的“思考”和“决策”。2.3 第三步实现核心执行循环——感知、思考、行动的引擎这是Agent的“心脏”。它将循环执行解析用户输入和上轮结果 - 组合提示词 - 调用LLM - 解析LLM输出 - 执行工具或返回答案。import json import re class SimpleAgent: def __init__(self, llm_client, tools): self.llm llm_client # 假设这是一个能调用LLM API的客户端 self.tools {t.name: t for t in tools} self.conversation_history [] # 简单的记忆体 def run(self, user_input): self.conversation_history.append(fUser: {user_input}) full_prompt self._construct_prompt(user_input) max_turns 5 # 防止死循环 for _ in range(max_turns): # 1. 思考与决策 llm_response self.llm.generate(full_prompt) self.conversation_history.append(fAssistant: {llm_response}) # 2. 解析LLM输出 thought, action, action_input, final_answer self._parse_response(llm_response) if final_answer: self.conversation_history.append(fFinal Answer: {final_answer}) return final_answer if action and action in self.tools: # 3. 执行行动 try: params json.loads(action_input) if action_input else {} tool_result self.tools[action].func(**params) observation fObservation: {tool_result} except Exception as e: observation fObservation: Tool call failed with error: {str(e)} # 4. 将观察结果加入历史进入下一轮循环 self.conversation_history.append(observation) full_prompt f\n{observation}\n else: # 如果解析不出有效动作可能LLM不听话直接返回或报错 return Im not sure how to handle that. return I seem to be stuck in a loop. Please try rephrasing your request. def _construct_prompt(self, user_input): # 组合系统提示词和会话历史 history \n.join(self.conversation_history[-6:]) # 只保留最近几轮防止上下文过长 base_prompt build_system_prompt(list(self.tools.values())) return base_prompt.format(user_inputuser_input) f\n{history} def _parse_response(self, response): # 使用正则表达式解析Thought, Action, Action Input, Final Answer thought re.search(rThought:\s*(.*?)(?\nAction:|\nFinal Answer:|$), response, re.DOTALL) action re.search(rAction:\s*(\w), response) action_input re.search(rAction Input:\s*(.*?)(?\nObservation:|\nFinal Answer:|$), response, re.DOTALL) final_answer re.search(rFinal Answer:\s*(.*?)$, response, re.DOTALL) return ( thought.group(1).strip() if thought else None, action.group(1) if action else None, action_input.group(1).strip() if action_input else None, final_answer.group(1).strip() if final_answer else None, )2.4 第四步运行与验证——看到第一个“活”的Agent现在我们可以初始化并运行这个Agent了假设你已有一个LLM客户端如OpenAI、通义千问等API的封装。# 伪代码展示调用流程 llm_client YourLLMClient(api_keyyour_key) agent SimpleAgent(llm_client, tools[weather_tool]) response agent.run(北京今天天气怎么样) print(response) # 理想输出 Thought: 用户想查询北京天气我需要调用get_weather工具。 # Action: get_weather # Action Input: {city: 北京} # Observation: 晴15-25°C微风 # Thought: 我已获得天气信息可以直接回答用户。 # Final Answer: 北京今天天气是晴气温在15到25摄氏度之间有微风。 response agent.run(那我应该穿什么) print(response) # 理想输出 Agent能结合之前的天气信息存储在history中进行推理并给出穿衣建议。通过这个从零搭建的过程你亲手实现了Agent最核心的循环。你会深刻理解提示词如何引导模型、工具调用如何衔接、状态如何在不同轮次间传递。这是所有高级框架底层都在做的事情。有了这个基础我们再去看LangChain等框架就会明白它们的AgentExecutor、Tool类、Memory模块到底在抽象什么以及当出现问题时应该从哪个层面去调试。3. 走向企业级必须补上的四块关键拼图一个能在个人电脑上跑通的Demo距离能在生产环境服务真实用户的“企业级Agent”还差得很远。企业级应用的核心要求是可靠、可维护、可监控、可扩展。我们的简单Agent需要从以下四个维度进行强化。3.1 拼图一健壮的工具调用与异常处理我们的简单实现里工具调用失败只有一个简单的异常捕获。在生产环境中这远远不够。重试机制网络请求可能临时失败。对于非幂等操作如支付需谨慎对于查询类操作可以设置指数退避重试。超时控制每个工具调用必须设置超时防止一个慢速工具拖垮整个Agent会话。结果验证与格式化工具返回的结果可能是混乱的JSON、HTML或纯文本。需要有一套机制来清洗和标准化结果再喂给LLM否则可能导致LLM解析错误。熔断与降级如果某个工具持续失败应能暂时将其“熔断”避免持续请求并尝试使用备用工具或给出降级回答。# 增强版工具调用示例 def safe_tool_call(tool_func, params, max_retries3, timeout10): for attempt in range(max_retries): try: # 使用带超时的执行方式具体实现取决于工具 result tool_func(**params) # 验证结果格式 validated_result validate_and_format_result(result) return validated_result except TimeoutError: if attempt max_retries - 1: return Error: Tool call timed out. except Exception as e: if attempt max_retries - 1: return fError: Tool call failed after {max_retries} attempts. Last error: {str(e)} time.sleep(2 ** attempt) # 指数退避 return Error: Max retries exceeded.3.2 拼图二可持续的会话与记忆管理我们之前的conversation_history是一个简单的列表存在很大问题上下文长度限制LLM有token限制历史对话不能无限增长。信息重要性不同不是所有历史对话都对当前任务同等重要。长期记忆与短期记忆用户可能希望Agent记住一些长期信息如偏好而不只是最近几次对话。企业级应用需要更复杂的记忆系统摘要式记忆当对话历史过长时自动将早期对话总结成一段摘要保留核心信息节省token。向量记忆将对话中的关键信息如用户提到的产品、需求存入向量数据库实现基于语义的长期记忆检索。分层记忆区分会话级记忆本次聊天和用户级记忆该用户的长期信息。3.3 拼图三全面的可观测性与调试支持当Agent在线上出现逻辑错误、性能低下或给出奇怪回答时如何快速定位问题你需要可观测性。全链路日志记录每一轮循环的完整信息用户输入、LLM的原始响应、解析后的Thought/Action、工具调用的输入输出、最终答案。这些日志需要结构化存储便于查询。性能指标监控每个环节的耗时LLM响应时间、工具调用时间、Token消耗量、工具调用成功率等。追踪与可视化能够像分布式系统调用链一样可视化一次用户请求在Agent内部经历了哪些步骤每个步骤的输入输出是什么。这对于调试复杂任务流至关重要。3.4 拼图四任务分解、规划与多Agent协作简单Agent只能处理线性任务。复杂任务如“帮我规划一个三天的北京旅游行程并预订第一天的酒店和机票”需要任务分解与规划能力。规划模块让LLM先将大目标拆解成一系列有序的子任务。子任务执行与状态管理依次或并行执行子任务并管理整体任务状态哪些完成了哪些失败了下一步该做什么。多Agent协作对于超复杂任务可以引入多个具有专长的Agent如一个负责信息收集一个负责规划一个负责执行让它们通过通信机制协同工作。这涉及到更复杂的架构设计如基于Actor模型或发布订阅模式。补上这四块拼图你的Agent才初步具备了处理真实业务场景的“体质”。它不再是一个脆弱的脚本而是一个有弹性、可追溯、能处理一定复杂度的软件服务。4. 框架选型与实战LangChain / Dify / 自研如何选择理解了底层原理和工程化要求后我们再来看具体的工具和框架选择。市面上选择很多主要分为三类特性维度LangChain / LlamaIndex (开发框架)Dify / Coze / 扣子 (低代码平台)完全自研核心定位为开发者提供的SDK和框架高度灵活可深度定制。提供可视化界面的应用构建平台开箱即用强调快速搭建。从零开始完全控制。灵活性极高。可以自定义每一个组件集成任何模型、工具、记忆系统。较低。受限于平台提供的组件、工作流和模型支持。最高。但也最复杂。开发成本中等。需要编写代码但框架处理了大量样板代码。极低。拖拽式配置无需或只需少量代码。极高。所有轮子都要自己造。可控性与深度高。可以深入底层优化性能实现复杂逻辑。低。底层是黑盒遇到平台限制或特殊需求时无能为力。最高。适合场景1. 复杂、定制化需求高的企业应用。2. 需要与现有系统深度集成。3. 研究和探索前沿Agent架构。1. 快速原型验证和内部工具搭建。2. 对编程不熟悉的业务人员构建简单应用。3. 功能需求完全在平台能力范围内。1. 有极特殊的性能、安全或架构要求。2. 技术实力雄厚且Agent是核心业务壁垒。工程化支持需要自己搭建日志、监控、部署、扩展。但社区生态丰富有大量参考。平台通常提供基础的发布、监控和版本管理。全部需要自己实现。给开发者的建议学习与原型阶段可以从LangChain开始。它的抽象层次很好能让你快速搭建出结构清晰的Agent同时又不屏蔽底层细节适合学习。用它实现我们第二章的“天气Agent”代码会简洁很多。内部工具与快速交付如果需求不复杂且追求速度Dify这类平台是很好的选择。可以在几小时内搭建一个可用的聊天机器人或内容生成工具。严肃的企业级项目LangChain通常是更稳妥的选择。它提供了坚实的基础组件同时允许你在需要时替换或自定义任何部分。你可以基于LangChain构建同时逐步融入你自己的记忆系统、工具调用层和监控模块。自研除非你有非常充分的理由如极致的性能要求、特殊硬件环境、或Agent本身就是你的核心产品否则不建议从头自研。LangChain等开源框架的生态和社区支持能节省你大量时间。以LangChain为例快速重构天气Agentfrom langchain.agents import initialize_agent, AgentType from langchain.tools import Tool from langchain.llms import OpenAI # 或其他LLM from langchain.memory import ConversationBufferMemory # 1. 定义工具和之前类似 def get_weather(city: str) - str: weather_data {北京: 晴15-25°C, 上海: 多云18-28°C} return weather_data.get(city, 未找到信息) weather_tool Tool( nameGetWeather, funcget_weather, description查询城市天气。输入应为城市名称字符串。 ) # 2. 初始化LLM和记忆 llm OpenAI(temperature0, openai_api_keyyour_key) memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 3. 创建并运行Agent tools [weather_tool] agent initialize_agent( tools, llm, agentAgentType.CONVERSATIONAL_REACT_DESCRIPTION, # 选择一种Agent类型 memorymemory, verboseTrue # 打印详细执行过程便于调试 ) response agent.run(北京天气如何) print(response) # LangChain会帮你处理ReAct格式的解析、工具调用、历史管理。使用框架后代码简洁性大幅提升但你必须通过阅读文档和源码理解其背后的AgentExecutor是如何工作的这样才能在出问题时进行有效调试。5. 避坑指南新手搭建Agent最常遇到的五个“坑”结合大量实践我总结了新手在搭建Agent时最容易踩的五个坑以及如何规避。5.1 坑一盲目追求复杂忽视单点验证现象一开始就想做一个“全能助理”集成十几个工具规划复杂任务链。问题复杂度爆炸任何一个工具或逻辑出错都难以定位。建议从“一个工具一个明确任务”开始。先让Agent能稳定可靠地完成“查天气”这一件事。确保它的提示词、工具调用、结果解析全链路畅通。然后再逐步增加第二个工具如“查航班”并测试两个工具间的协作。采用增量式开发。5.2 坑二提示词过于简单或混乱现象Agent行为不可控经常不按预期调用工具或胡言乱语。问题提示词没有清晰定义角色、约束和输出格式。建议明确指令在系统提示词开头就定下基调。“你是一个专注于完成XXX任务的助手必须严格按照以下步骤和格式工作。”结构化输出强制要求LLM以Thought:Action:Final Answer:等格式输出。这能极大提高解析的可靠性。提供示例在提示词中提供1-2个完整的对话示例Few-shot Learning让LLM更好地理解你的期望。5.3 坑三忽视上下文管理与Token消耗现象对话进行到后面Agent“失忆”了或者API调用因超长而失败、费用激增。问题没有对会话历史进行有效的管理和裁剪。建议设定历史窗口只保留最近N轮对话。实现摘要功能当历史过长时调用LLM对早期对话进行总结用摘要替代原始文本。选择性记忆只将与当前任务强相关的历史信息放入上下文。可以利用向量检索来实现。5.4 坑四工具调用没有防御性编程现象工具API变更、网络波动、输入异常导致整个Agent崩溃。问题工具调用层缺乏异常处理、重试、超时和结果验证。建议如第三章所述为每个工具调用包装一层健壮的安全调用器处理各类异常并返回结构化的错误信息供LLM或上层逻辑处理。5.5 坑五没有规划评估与监控体系现象Agent上线后不知道它运行得好不好哪里慢用户常问什么经常出什么错。问题缺乏可观测性。建议在开发初期就引入日志和监控。至少记录用户Query、Agent的完整思考过程、工具调用详情输入、输出、耗时、状态、最终回复。这些数据是后续优化提示词、改进工具、分析用户需求的黄金资料。搭建一个能用的AI Agentdemo可能只需要一个下午。但构建一个能在真实业务中创造价值、稳定运行的企业级智能体是一个系统工程。它考验的不仅仅是你对LLM API的调用能力更是你对软件架构、异常处理、状态管理和用户体验的综合理解。我的建议是不要急于求成从最小闭环开始。先深入理解“感知-思考-行动”这个核心循环亲手实现它。然后像搭积木一样逐步为你的Agent加上健壮的工具层、可持续的记忆系统、可观测的监控模块。在这个过程中善用LangChain这样的成熟框架来提升效率但永远保持对底层原理的好奇。AI Agent的世界才刚刚开始真正的挑战和乐趣不在于复现一个炫酷的演示而在于让这些智能体真正理解我们的意图可靠地执行任务并无缝融入我们复杂的工作流之中。这条路需要更多的工程师带着系统的思维和务实的态度一步步去探索和构建。 
