1. 大模型Agent开发入门从概念到第一个可运行项目大模型Agent这个词最近一年被聊得太多但真正动手写过的人比例并不高。很多人对Agent的理解还停留在“会调用工具的ChatGPT”这个层面实际上Agent的核心远不止于此。我过去大半年时间一直在做Agent相关的项目从最简单的ReAct循环到多Agent协作编排都踩过一遍这篇文章就把我积累的经验完整梳理出来给准备入门的朋友一条相对平滑的路径。先说清楚这篇文章适合谁看。如果你已经能熟练调用大模型API知道什么是system prompt、什么是function calling但还没真正搭建过一个能自主决策、能调用外部工具、能多步推理的Agent系统那这篇内容就是为你准备的。如果你连API都还没调过建议先花半天时间把基础跑通再回来。整篇文章会从Agent的本质讲起然后一步步带你搭出一个可运行的Agent最后聊一聊实际项目里最容易踩的坑。Agent这个词翻译过来叫“智能体”但我觉得叫“代理”更贴切——它代替你去完成一件事过程中自己决定怎么做。传统程序是你写死每一步逻辑Agent是你给它一个目标它自己规划步骤、选择工具、执行、观察结果、再决定下一步。这个“自主决策”的能力就是Agent和普通脚本最本质的区别。2. Agent到底是什么拆开看它的四个核心部件2.1 从“会聊天的模型”到“会干活的Agent”大模型本身只是一个文本生成器你问它答它没有手没有脚不能帮你查天气、不能帮你发邮件、不能帮你操作数据库。Agent做的事情就是给这个大模型装上“手脚”和“记忆”让它能真正去执行任务。我习惯用一个类比来解释大模型是一个很聪明但被关在房间里的人你只能通过门缝递纸条跟他交流。Agent就是给这个人配了电话、电脑、纸笔还告诉他房间外面有哪些资源可以用。这时候他就不只是回答问题了他能主动打电话查信息、用电脑操作文件、把结果记在纸上供后续参考。具体来说一个完整的Agent系统包含四个核心部件大脑LLM、规划Planning、工具Tools、记忆Memory。这四个部件缺一不可后面我会逐个拆开讲。2.2 大脑选对模型比选贵的模型更重要大脑就是大语言模型它负责理解任务、推理、决策。选模型的时候很多人第一反应是“用最强的”但实际项目里要考虑的因素远不止能力。我做过一个对比测试同一个Agent任务分别用不同模型跑结果差异很大。有些模型function calling格式经常出错有些模型在多步推理时容易“忘记”前面的步骤有些模型虽然能力强但响应太慢导致整个Agent循环卡顿。所以选模型的核心原则是优先选function calling稳定、指令遵循能力强的模型而不是单纯看跑分。对于入门项目我建议先用一个中等规模的模型把流程跑通确认Agent逻辑没问题之后再根据实际效果决定要不要换更强的模型。很多新手一上来就用最贵的模型结果调试阶段烧掉大量费用最后发现是prompt写错了。2.3 规划Agent的“思考方式”决定了它的上限规划是Agent最核心也最难的部分。简单说规划就是Agent决定“先做什么、再做什么、用什么做”的能力。目前主流的规划模式有几种我按复杂度从低到高排一下。第一种是ReAct模式全称Reasoning Acting。它的逻辑很简单让模型先输出一段思考Reasoning然后决定调用哪个工具Acting拿到工具结果后再思考循环直到任务完成。这个模式实现起来最简单适合入门。第二种是Plan-and-Execute模式先让模型制定一个完整的计划然后按计划逐步执行。这种模式适合步骤明确的任务但缺点是计划一旦制定就很难动态调整。第三种是多Agent协作模式把不同职责分配给不同的Agent比如一个负责规划、一个负责执行、一个负责审核。这种模式最复杂但处理复杂任务时效果最好。入门阶段我强烈建议从ReAct开始把这一种模式吃透比每种都浅尝辄止强得多。2.4 工具与记忆Agent的“手脚”和“笔记本”工具就是Agent能调用的外部能力。最简单的工具是一个函数比如查天气的函数、计算器的函数、搜索的函数。复杂一点的工具可以是调用某个API、操作数据库、执行代码。写工具的时候有个关键原则工具的描述比工具本身更重要。模型是根据你给的描述来决定要不要调用这个工具的描述写得含糊模型就不知道该什么时候用。我见过太多人工具函数写得没问题但description就写了一句“查询信息”结果模型根本不知道怎么用。记忆分短期记忆和长期记忆。短期记忆就是当前对话的上下文这个靠模型的context window来维护。长期记忆是把重要信息存到外部存储里需要的时候再检索出来。入门阶段先把短期记忆做好长期记忆可以后面再加。3. 动手搭建第一个Agent完整实操流程3.1 环境准备与依赖安装我假设你已经有了Python基础并且能正常调用大模型API。如果还没有API key可以先用一些提供免费额度的平台练手等流程跑通了再考虑付费。先建一个干净的项目目录然后安装必要的依赖。我习惯用虚拟环境避免污染全局环境。python -m venv agent-env source agent-env/bin/activate # Windows用 agent-env\Scripts\activate pip install openai requests这里我只装了最基础的依赖。很多教程一上来就让你装LangChain、AutoGPT这些框架我的建议是第一个Agent不要用框架。框架封装了太多细节你出了问题根本不知道是哪一层出的错。先用原生API把ReAct循环手写一遍理解每一步在做什么之后再用框架效率会高很多。3.2 定义工具函数从最简单的开始我们先定义两个最简单的工具一个查天气一个做数学计算。实际项目里你的工具可能是查数据库、调内部API但原理完全一样。import json def get_weather(city: str) - str: 查询指定城市的天气情况 # 实际项目里这里会调用天气API入门阶段先用模拟数据 weather_data { 北京: 晴25摄氏度, 上海: 多云28摄氏度, 深圳: 阵雨30摄氏度 } return weather_data.get(city, f暂时查不到{city}的天气) def calculate(expression: str) - str: 计算数学表达式支持加减乘除和括号 try: result eval(expression) return f计算结果是{result} except Exception as e: return f计算出错{str(e)}注意每个函数的docstring这就是给模型看的工具描述。描述要写清楚这个工具是干什么的、什么时候用。我试过把描述写得很简略结果模型该调用的时候不调用不该调用的时候乱调用。3.3 构建ReAct循环Agent的心脏接下来是核心部分把工具注册给模型然后实现思考-行动-观察的循环。from openai import OpenAI client OpenAI(api_key你的API_KEY, base_url你的API地址) tools [ { type: function, function: { name: get_weather, description: 查询指定城市的天气情况, parameters: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } } }, { type: function, function: { name: calculate, description: 计算数学表达式支持加减乘除和括号, parameters: { type: object, properties: { expression: {type: string, description: 数学表达式} }, required: [expression] } } } ] def run_agent(user_input: str, max_steps: int 5): messages [ {role: system, content: 你是一个能调用工具的助手。根据用户需求决定是否调用工具拿到结果后给出最终回答。}, {role: user, content: user_input} ] for step in range(max_steps): response client.chat.completions.create( model你的模型名称, messagesmessages, toolstools, tool_choiceauto ) msg response.choices[0].message messages.append(msg) # 如果没有工具调用说明Agent给出了最终回答 if not msg.tool_calls: return msg.content # 执行所有工具调用 for tool_call in msg.tool_calls: func_name tool_call.function.name func_args json.loads(tool_call.function.arguments) if func_name get_weather: result get_weather(**func_args) elif func_name calculate: result calculate(**func_args) else: result f未知工具{func_name} messages.append({ role: tool, tool_call_id: tool_call.id, content: result }) return 达到最大步数限制任务未完成这段代码就是最基础的ReAct循环。跑起来之后你可以试试问它“北京天气怎么样”或者“帮我算一下(1527)*3等于多少”看它能不能正确调用工具。3.4 参数选择与调试技巧max_steps这个参数很关键。设太小复杂任务跑不完设太大万一Agent陷入死循环会浪费大量token。我一般入门项目设5到8步实际项目根据任务复杂度调整。tool_choice参数控制模型是否必须调用工具。设成auto让模型自己决定设成required强制调用。调试阶段我建议先用auto观察模型在什么情况下会主动调用工具什么情况下不会。还有一个容易忽略的点是system prompt的写法。上面那段system prompt很简单但实际项目里你需要根据任务类型仔细设计。比如做客服Agentsystem prompt里要写清楚业务范围、回答风格、什么情况下转人工。这些细节直接决定Agent的表现。4. 进阶方向从能跑到好用之间差了什么4.1 多步推理与错误恢复基础版Agent跑通之后你会发现它在简单任务上表现不错但遇到需要多步推理的任务就容易出问题。比如“帮我查一下北京和上海哪个城市更适合今天出门”它需要先查两个城市的天气然后对比最后给出建议。这个任务用上面的代码其实也能跑但模型可能会在第一步就试图给出最终答案而不是先调用两次天气工具。解决办法是在system prompt里明确要求“如果需要多个信息先收集完所有信息再回答”。错误恢复是另一个重点。工具调用失败是常态网络超时、参数格式错误、API限流都会发生。好的Agent应该能识别错误并尝试修复而不是直接把错误信息抛给用户。我通常会在工具执行层加一层try-except把错误信息格式化后返回给模型让模型决定是重试还是换一种方式。4.2 记忆管理别让上下文爆掉Agent跑多轮对话时messages列表会越来越长最终超出模型的context window。解决办法有几种一是定期总结历史对话把摘要存下来二是只保留最近N轮对话三是把重要信息抽取出来存到外部需要时再检索。我实际项目里用的是组合方案最近5轮对话保留原文更早的对话做摘要关键实体信息比如用户ID、订单号单独存到一个字典里。这样既控制了token消耗又不会丢失重要信息。4.3 从单Agent到多Agent协作当你需要处理的任务复杂到单个Agent搞不定时就要考虑多Agent了。常见的拆分方式是按职责拆一个规划Agent负责拆解任务多个执行Agent分别处理子任务一个审核Agent负责检查结果。多Agent的难点在于通信和协调。Agent之间怎么传递信息、怎么避免死锁、怎么处理某个Agent失败的情况这些都需要仔细设计。入门阶段不建议碰多Agent先把单Agent做扎实。5. 常见问题与排查技巧实录5.1 Agent不调用工具怎么办这是新手遇到最多的问题。模型该调用工具的时候不调用直接凭自己的知识回答。排查思路按顺序来先检查工具描述是否清晰再检查system prompt是否明确要求使用工具最后检查模型本身是否支持function calling。我遇到过一次工具描述写的是“获取信息”模型完全不知道这个工具是干什么的。改成“查询指定城市的实时天气情况返回温度和天气状况”之后立刻就正常了。工具描述要具体到模型一看就知道什么时候该用。5.2 工具调用参数格式错误模型生成的参数格式不对比如该传字符串的传了数字该传数组的传了对象。这个问题通常是因为参数的JSON Schema定义不够明确。在parameters里把每个字段的类型、描述、示例都写清楚能大幅降低出错概率。如果还是出错可以在工具执行层加参数校验和自动修复。比如模型传了{city: 123}你可以在代码里转成{city: 123}再执行。5.3 Agent陷入死循环Agent反复调用同一个工具或者在两个工具之间来回跳。常见原因是工具返回的结果没有让模型得到它需要的信息模型就不断重试。解决办法是设置max_steps上限同时在工具返回结果里加上明确的提示比如“如果这个结果不满足需求请尝试其他方式或直接告知用户”。5.4 响应速度太慢Agent的响应时间等于所有步骤的模型调用时间之和。一个5步的任务如果每步模型响应要3秒总共就是15秒。优化方向有几个用更快的模型、减少不必要的步骤、把可以并行的工具调用并行执行。我实测下来把工具调用从串行改成并行在需要查多个信息的场景下能省一半时间。不过并行调用要注意工具之间是否有依赖关系有依赖的不能并行。常见问题排查方向解决方案不调用工具工具描述、system prompt细化描述明确要求参数格式错误JSON Schema定义补充类型和示例加校验层死循环工具返回内容设max_steps优化返回提示响应慢模型选择、步骤数换快模型并行工具调用上下文超限对话轮数摘要历史限制保留轮数6. 我踩过的坑和给你的建议第一个建议是不要一上来就追求完美架构。我见过太多人花两周设计了一套复杂的多Agent架构结果连最简单的单Agent循环都没跑通。先用100行代码跑通一个能用的Agent然后再逐步迭代。第二个建议是日志要打全。Agent的调试比普通程序难得多因为它的行为是不确定的。每次模型调用、每次工具执行、每次决策结果都要记日志。我现在的习惯是把完整的messages列表在每一步都打印出来出问题的时候一眼就能看出是哪一步跑偏了。第三个建议是测试用例要覆盖边界情况。正常任务跑通不代表Agent没问题要专门测试工具调用失败、参数缺失、多轮对话、超长输入这些边界情况。我一般会准备20个左右的测试用例每次改完prompt或工具都跑一遍回归。第四个建议是成本要提前算。Agent的token消耗比普通对话高得多因为每一步都要把完整上下文发给模型。一个5步的任务token消耗可能是单次对话的5到10倍。入门阶段用免费额度练手没问题但上线前一定要算清楚成本。最后说一个我自己的体会Agent开发最难的不是写代码而是设计好模型和工具之间的“接口”。这个接口包括工具描述、system prompt、返回格式、错误处理每一处细节都会影响Agent的表现。代码写错了可以改接口设计不好整个Agent就是不可用的。所以每次动手写代码之前先花时间想清楚这几个问题Agent要完成什么任务、需要哪些工具、每个工具什么时候用、出错怎么办。想清楚了再写效率会高很多。