1. 大模型Agent开发入门从零到一构建你的第一个智能体过去一年我身边不少做后端、做前端甚至做硬件的朋友都在问同一个问题大模型Agent到底怎么入门是不是得先把Transformer啃透要不要先学PyTorch我的回答通常很直接——不用。Agent开发和大模型训练是两条路前者更像是在一个已经通电的房子里做装修你不需要会发电但得懂电路怎么走、开关装在哪、家具怎么摆才顺手。这篇内容就是写给那些想动手做Agent、但被各种框架和概念绕晕的人。我会从整体设计思路讲起拆解核心模块然后带你走一遍完整的实操流程最后把我在实际项目中踩过的坑和排查经验整理出来。不管你是刚接触大模型的新手还是已经用过API调用的开发者都能从中找到可以直接抄作业的部分。2. 整体设计思路Agent不是“更聪明的聊天机器人”2.1 Agent和普通LLM调用的本质区别很多人第一次接触Agent会觉得它就是给大模型加了个循环让它多跑几轮。这个理解不算错但漏掉了最关键的部分。普通的大模型调用是“一问一答”你给一个prompt模型返回一个结果结束。Agent的核心在于它有了自主决策和工具使用的能力——模型不只是生成文本它还能判断“我现在该不该调用某个工具”“调用哪个工具”“拿到结果后下一步做什么”。打个比方普通LLM调用像你问路对方告诉你“往前走两百米左转”Agent则像你雇了一个向导他不仅知道路还会看天气、查公交、帮你叫车甚至在发现封路时自己换一条路线。这个“自己换路线”的能力就是Agent的灵魂。从技术架构上看一个最小可用的Agent通常包含四个部分规划模块、记忆模块、工具调用模块、执行循环。规划模块负责把用户的大目标拆成小步骤记忆模块负责记住上下文和历史操作工具调用模块负责和外部世界交互执行循环则把这些串起来让Agent能一轮一轮地推进任务。2.2 为什么选择“框架API”而不是从零手写市面上Agent框架很多从轻量的到重型的都有。我的建议是入门阶段不要从零手写循环也不要一上来就上最复杂的框架。原因很简单——你需要先理解Agent的工作流而不是被框架的抽象层淹没。从零手写的问题在于你会花大量时间处理异常、重试、状态管理这些和Agent核心逻辑无关的事情。而直接上重型框架的问题在于你还没搞清楚“为什么需要这个组件”就被迫接受了一堆设计决策。比较稳妥的路径是先用一个轻量框架跑通最小闭环理解每个环节的作用然后再根据需求逐步替换或增强组件。具体到工具选型Python生态里比较适合入门的有几类一类是提供基础Agent抽象和工具注册的轻量库一类是带可视化编排的平台还有一类是直接基于API自己封装。我个人的习惯是先用轻量库把流程跑通等遇到性能或扩展性问题时再考虑引入更完整的框架。2.3 一个容易被忽略的设计原则让Agent“可观测”这是我在实际项目中感受最深的一点。Agent和普通程序最大的不同在于它的行为带有随机性——同样的输入可能走出不同的路径。如果你不能清楚地看到它每一步在做什么、为什么做这个决定调试会变成噩梦。所以从第一天起就要把日志和追踪做进去。每次Agent决定调用某个工具时记录下它的推理过程每次工具返回结果时记录下原始输出每次循环结束时记录下当前状态。这些记录不只是为了调试它们也是你后续优化prompt、调整工具描述、改进规划策略的依据。我见过不少团队一开始图快Agent跑起来就行结果上线后出了问题完全不知道从哪查起。这个坑完全可以避免代价只是多写几行日志代码。3. 核心模块拆解规划、记忆、工具、执行3.1 规划模块让Agent学会“拆任务”规划模块是Agent的大脑。它的核心任务是把用户的一句话目标转化成一系列可执行的步骤。比如用户说“帮我查一下北京明天天气如果下雨就提醒我带伞”规划模块需要拆成查天气→判断是否下雨→如果下雨则生成提醒。实现规划有两种常见思路。一种是显式规划让模型直接输出一个步骤列表然后按列表执行。这种方式结构清晰适合任务边界明确的场景。另一种是隐式规划不预先列出所有步骤而是让模型在每一轮根据当前状态决定下一步做什么。这种方式更灵活但更难控制。入门阶段我建议用显式规划因为它更容易调试。你可以把规划的结果打印出来一眼就能看出模型有没有理解错任务。等你对Agent的行为模式比较熟悉了再尝试隐式规划。规划模块的prompt设计有几个要点。第一要明确告诉模型“你是一个规划器不是执行器”避免它直接给出最终答案而不是步骤。第二要限制步骤数量防止模型生成过于冗长的计划。第三要提供几个示例让模型知道什么样的拆解是合理的。3.2 记忆模块短期记忆和长期记忆的分工记忆模块经常被新手忽略但它直接决定了Agent能不能处理多轮任务。短期记忆就是当前对话的上下文通常直接放在prompt里。长期记忆则是跨会话的信息需要额外的存储和检索机制。短期记忆的管理核心是上下文窗口的分配。你不能把所有历史都塞进去那样既浪费token又容易让模型分心。常见的做法是保留最近N轮对话或者用摘要的方式压缩历史。我一般会保留最近5到10轮再加上一个任务状态的摘要。长期记忆的实现方式就比较多样了。简单一点可以用向量数据库做语义检索复杂一点可以结合知识图谱。入门阶段我建议先用最简单的方案把重要信息存成结构化数据需要时直接查。比如用户偏好、历史任务结果这些用JSON文件或SQLite存就够了不必一上来就上向量库。注意记忆模块最容易出的问题是“记了不该记的”。比如把工具的原始输出全部塞进上下文导致prompt迅速膨胀。我的做法是只保留工具输出的关键字段其余丢弃。3.3 工具调用Agent和外部世界的接口工具调用是Agent最实用的能力。没有工具Agent只能“说”有了工具Agent才能“做”。工具可以是任何东西查天气的API、读文件的函数、执行计算的脚本、发送消息的接口。定义工具时最关键的是描述要清晰。模型是根据你的描述来决定要不要调用、怎么调用的。如果描述模糊模型要么不调用要么传错参数。一个好的工具描述应该包含工具做什么、什么时候用、参数是什么含义、返回什么格式。我通常会给每个工具写一段“使用场景”说明而不是只写功能。比如不要只写“查询天气”而要写“当用户询问某地天气、需要根据天气做决策时使用此工具”。这样模型更容易判断调用时机。工具调用的另一个要点是错误处理。工具可能失败API可能超时返回格式可能不符合预期。Agent需要能处理这些情况而不是一失败就崩溃。常见的做法是让工具返回结构化的结果包含成功标志和错误信息然后让模型根据错误信息决定重试还是换方案。3.4 执行循环Agent的心跳执行循环把前面三个模块串起来。一个典型的循环是接收用户输入→规划→选择工具→执行工具→观察结果→判断是否完成→如果未完成则继续循环。这个循环看起来简单但有几个细节容易出问题。第一是循环终止条件什么情况下认为任务完成了是模型说“完成”就算还是需要外部验证我一般会设置双重条件模型判断完成且没有待执行的工具调用。第二是最大循环次数防止Agent陷入死循环通常设5到10次就够了。第三是状态传递每一轮的结果要正确传递给下一轮不能丢失关键信息。执行循环的实现方式可以很简单一个while循环加几个if判断就能跑起来。关键是要把每一步的状态记录下来方便调试和恢复。4. 实操过程从环境准备到跑通第一个Agent4.1 环境准备和依赖安装先说一下基础环境。Python 3.10以上是必须的因为很多大模型相关的库已经不再支持更早的版本。我习惯用虚拟环境隔离项目依赖conda或者venv都行看个人习惯。python -m venv agent-env source agent-env/bin/activate # Windows下用 agent-env\Scripts\activate然后安装核心依赖。入门阶段不需要装太多东西一个HTTP客户端、一个大模型SDK、一个轻量Agent库就够了。pip install openai requests python-dotenv如果你用的是其他模型提供方把openai换成对应的SDK即可。python-dotenv用来管理API密钥避免把密钥硬编码在代码里。提示API密钥一定要放在环境变量或.env文件里并且把.env加入.gitignore。我见过不止一次有人把密钥提交到公开仓库结果被滥用。4.2 定义你的第一个工具工具的定义方式取决于你用的框架。如果用的是轻量库通常就是一个带类型注解的Python函数加上一段描述。我以查询天气为例def get_weather(city: str) - dict: 查询指定城市的当前天气。 当用户询问天气、需要根据天气做决策时使用此工具。 参数: city: 城市名称如北京、上海 返回: 包含温度、天气状况、湿度的字典 # 实际项目中这里调用天气API # 这里用模拟数据演示 return { city: city, temperature: 22, condition: 多云, humidity: 65 }这个函数本身很简单但描述部分很重要。我特意写了“当用户询问天气、需要根据天气做决策时使用”而不是只写“查询天气”。这个差别在实际运行中很明显——前者能让模型更准确地判断调用时机。4.3 组装Agent并跑通第一个任务把工具注册到Agent设置好模型和系统提示词就可以跑第一个任务了。系统提示词的核心是告诉模型它的角色、可用工具、以及行为规范。SYSTEM_PROMPT 你是一个乐于助人的助手可以调用工具来帮助用户解决问题。 可用工具 - get_weather: 查询城市天气 行为规范 1. 先理解用户需求再决定是否需要调用工具 2. 调用工具时确保参数正确 3. 拿到工具结果后用自然语言回复用户 4. 如果工具调用失败尝试其他方案或告知用户 然后创建一个简单的执行循环def run_agent(user_input, max_turns5): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for turn in range(max_turns): response call_llm(messages) if response.has_tool_call: tool_name response.tool_name tool_args response.tool_args result execute_tool(tool_name, tool_args) messages.append(response.message) messages.append({role: tool, content: str(result)}) else: return response.content return 任务未在限定轮次内完成这段代码跑起来后你可以试试输入“北京今天天气怎么样”观察Agent是否调用了get_weather工具以及最终回复是否符合预期。4.4 参数选择与调优的实操记录模型参数里对Agent行为影响最大的是temperature。规划阶段我一般用0.2到0.3让输出更稳定工具调用阶段用0.1甚至0减少参数传错的概率最终回复阶段可以稍微高一点0.5到0.7让语言更自然。max_tokens也要注意。规划阶段的输出通常不长设500就够了但如果工具返回的结果很长需要留足空间。我一般设2000作为默认值特殊场景再调整。还有一个容易被忽略的参数是超时时间。工具调用可能因为网络问题卡住如果不设超时整个Agent就挂在那里了。我一般给每个工具调用设10到30秒的超时具体看工具的性质。5. 常见问题与排查技巧实录5.1 Agent不调用工具怎么办这是新手遇到最多的问题。模型明明知道有工具但就是不用直接用自己的知识回答。原因通常有三个工具描述不够清晰、系统提示词没有强调工具的使用、或者模型本身的能力限制。排查顺序是这样的先看工具描述是不是只写了功能没写使用场景再看系统提示词有没有明确说“需要实时信息时必须调用工具”最后换一个能力更强的模型试试。我实测下来工具描述的改进对调用率的影响最大有时候改一句话就能从50%提升到90%。5.2 工具调用参数传错怎么排查参数传错通常表现为字段名不对、类型不对、必填项缺失。排查方法是把模型输出的工具调用请求完整打印出来和工具定义逐一对照。一个常见原因是工具参数的命名不够直观。比如你定义了一个参数叫q模型很可能不知道这是查询词。改成query或者search_term准确率会明显提升。另一个原因是参数描述缺失模型只能靠猜。每个参数都应该有明确的类型和说明。5.3 Agent陷入循环怎么处理循环的典型表现是Agent反复调用同一个工具或者在不同工具之间来回跳转始终不给出最终答案。原因可能是规划不清晰、工具返回的结果让模型困惑、或者终止条件没设好。我的处理方式是设一个硬性的最大轮次限制比如5轮。超过就强制终止返回当前状态。同时在系统提示词里加一句“如果连续两次调用同一工具且结果相同请停止调用并告知用户”。这个简单的规则能解决大部分循环问题。5.4 上下文膨胀导致响应变慢Agent跑了几轮之后prompt会越来越长响应时间明显增加。这是因为每一轮的工具结果都追加到了消息历史里。解决办法是只保留关键信息丢弃冗余内容。比如天气API返回了20个字段你只需要温度和天气状况那就只把这两个字段放进上下文。另外可以定期对历史做摘要用一段简短的文字代替多轮对话。我一般每5轮做一次摘要压缩。5.5 常见问题速查表问题现象可能原因排查方法解决思路不调用工具描述不清、提示词未强调检查工具描述和系统提示补充使用场景说明参数传错参数名不直观、缺描述打印调用请求对照定义重命名参数、补充说明陷入循环规划不清、终止条件缺失查看每轮决策日志设最大轮次、加停止规则响应变慢上下文膨胀统计每轮token数精简工具输出、定期摘要工具报错后崩溃缺少错误处理查看异常堆栈工具返回结构化错误信息6. 进阶方向从能跑到好用6.1 多工具协作与工具链设计当Agent需要多个工具配合时设计就变得更重要了。比如一个“帮我规划旅行”的Agent可能需要查天气、查航班、查酒店、算预算。这些工具之间有依赖关系顺序不能乱。我的做法是把工具分成几类信息获取类、计算类、执行类。信息获取类可以并行调用计算类依赖前面的结果执行类放在最后。在系统提示词里说明这个分类模型会更容易做出合理的调用顺序。6.2 记忆的持久化与检索短期记忆解决的是单次会话的问题长期记忆解决的是跨会话的问题。入门阶段可以先用简单的键值存储把用户偏好、历史任务结果存下来。等数据量大了再考虑向量检索。持久化记忆的关键是写入时机和检索策略。不是所有信息都值得记我一般只记三类用户明确表达的偏好、任务的关键结果、以及反复出现的信息。检索时用语义相似度找最相关的几条不要全部塞进上下文。6.3 安全边界与权限控制Agent能调用工具就意味着它能产生实际影响。如果工具包括发邮件、改文件、执行命令那安全边界就非常重要。我的原则是最小权限。Agent只应该拥有完成任务所必需的权限不多给。具体做法包括工具层面做参数校验拒绝危险操作执行层面加确认机制重要操作需要二次确认日志层面记录所有工具调用方便审计。这些在入门阶段可能觉得多余但等到Agent真正处理实际任务时你会庆幸自己提前做了。6.4 性能优化并发与缓存当Agent需要处理多个任务时串行执行会很慢。这时候可以考虑并发。信息获取类的工具调用可以并行发出等所有结果返回后再进入下一步。Python里用asyncio或者线程池都能实现。缓存也很重要。同样的工具调用如果参数相同短时间内可以复用结果。比如天气查询5分钟内重复查询同一城市直接返回缓存结果就行。这能显著减少API调用次数和响应时间。7. 我个人的实操体会做Agent开发这段时间最大的感受是Agent的能力上限不取决于模型而取决于你怎么设计它的工作流。同样的模型工具描述改一改、提示词调一调、循环逻辑优化一下效果可能天差地别。另一个体会是不要追求一步到位。先跑通最小闭环哪怕只能查天气、只能做一件事也比一个功能齐全但跑不起来的系统强。跑通之后再逐步加工具、加记忆、加规划每一步都验证效果。最后分享一个小技巧给Agent加一个“思考日志”。每次它做决策时让它用一句话说明理由记录到日志里。这个日志在调试时非常有用你能清楚地看到它为什么选择这个工具、为什么跳过那个步骤。很多时候问题就藏在这些理由里。 大模型Agent开发入门：从零构建智能体与核心模块拆解
1. 大模型Agent开发入门从零到一构建你的第一个智能体过去一年我身边不少做后端、做前端甚至做硬件的朋友都在问同一个问题大模型Agent到底怎么入门是不是得先把Transformer啃透要不要先学PyTorch我的回答通常很直接——不用。Agent开发和大模型训练是两条路前者更像是在一个已经通电的房子里做装修你不需要会发电但得懂电路怎么走、开关装在哪、家具怎么摆才顺手。这篇内容就是写给那些想动手做Agent、但被各种框架和概念绕晕的人。我会从整体设计思路讲起拆解核心模块然后带你走一遍完整的实操流程最后把我在实际项目中踩过的坑和排查经验整理出来。不管你是刚接触大模型的新手还是已经用过API调用的开发者都能从中找到可以直接抄作业的部分。2. 整体设计思路Agent不是“更聪明的聊天机器人”2.1 Agent和普通LLM调用的本质区别很多人第一次接触Agent会觉得它就是给大模型加了个循环让它多跑几轮。这个理解不算错但漏掉了最关键的部分。普通的大模型调用是“一问一答”你给一个prompt模型返回一个结果结束。Agent的核心在于它有了自主决策和工具使用的能力——模型不只是生成文本它还能判断“我现在该不该调用某个工具”“调用哪个工具”“拿到结果后下一步做什么”。打个比方普通LLM调用像你问路对方告诉你“往前走两百米左转”Agent则像你雇了一个向导他不仅知道路还会看天气、查公交、帮你叫车甚至在发现封路时自己换一条路线。这个“自己换路线”的能力就是Agent的灵魂。从技术架构上看一个最小可用的Agent通常包含四个部分规划模块、记忆模块、工具调用模块、执行循环。规划模块负责把用户的大目标拆成小步骤记忆模块负责记住上下文和历史操作工具调用模块负责和外部世界交互执行循环则把这些串起来让Agent能一轮一轮地推进任务。2.2 为什么选择“框架API”而不是从零手写市面上Agent框架很多从轻量的到重型的都有。我的建议是入门阶段不要从零手写循环也不要一上来就上最复杂的框架。原因很简单——你需要先理解Agent的工作流而不是被框架的抽象层淹没。从零手写的问题在于你会花大量时间处理异常、重试、状态管理这些和Agent核心逻辑无关的事情。而直接上重型框架的问题在于你还没搞清楚“为什么需要这个组件”就被迫接受了一堆设计决策。比较稳妥的路径是先用一个轻量框架跑通最小闭环理解每个环节的作用然后再根据需求逐步替换或增强组件。具体到工具选型Python生态里比较适合入门的有几类一类是提供基础Agent抽象和工具注册的轻量库一类是带可视化编排的平台还有一类是直接基于API自己封装。我个人的习惯是先用轻量库把流程跑通等遇到性能或扩展性问题时再考虑引入更完整的框架。2.3 一个容易被忽略的设计原则让Agent“可观测”这是我在实际项目中感受最深的一点。Agent和普通程序最大的不同在于它的行为带有随机性——同样的输入可能走出不同的路径。如果你不能清楚地看到它每一步在做什么、为什么做这个决定调试会变成噩梦。所以从第一天起就要把日志和追踪做进去。每次Agent决定调用某个工具时记录下它的推理过程每次工具返回结果时记录下原始输出每次循环结束时记录下当前状态。这些记录不只是为了调试它们也是你后续优化prompt、调整工具描述、改进规划策略的依据。我见过不少团队一开始图快Agent跑起来就行结果上线后出了问题完全不知道从哪查起。这个坑完全可以避免代价只是多写几行日志代码。3. 核心模块拆解规划、记忆、工具、执行3.1 规划模块让Agent学会“拆任务”规划模块是Agent的大脑。它的核心任务是把用户的一句话目标转化成一系列可执行的步骤。比如用户说“帮我查一下北京明天天气如果下雨就提醒我带伞”规划模块需要拆成查天气→判断是否下雨→如果下雨则生成提醒。实现规划有两种常见思路。一种是显式规划让模型直接输出一个步骤列表然后按列表执行。这种方式结构清晰适合任务边界明确的场景。另一种是隐式规划不预先列出所有步骤而是让模型在每一轮根据当前状态决定下一步做什么。这种方式更灵活但更难控制。入门阶段我建议用显式规划因为它更容易调试。你可以把规划的结果打印出来一眼就能看出模型有没有理解错任务。等你对Agent的行为模式比较熟悉了再尝试隐式规划。规划模块的prompt设计有几个要点。第一要明确告诉模型“你是一个规划器不是执行器”避免它直接给出最终答案而不是步骤。第二要限制步骤数量防止模型生成过于冗长的计划。第三要提供几个示例让模型知道什么样的拆解是合理的。3.2 记忆模块短期记忆和长期记忆的分工记忆模块经常被新手忽略但它直接决定了Agent能不能处理多轮任务。短期记忆就是当前对话的上下文通常直接放在prompt里。长期记忆则是跨会话的信息需要额外的存储和检索机制。短期记忆的管理核心是上下文窗口的分配。你不能把所有历史都塞进去那样既浪费token又容易让模型分心。常见的做法是保留最近N轮对话或者用摘要的方式压缩历史。我一般会保留最近5到10轮再加上一个任务状态的摘要。长期记忆的实现方式就比较多样了。简单一点可以用向量数据库做语义检索复杂一点可以结合知识图谱。入门阶段我建议先用最简单的方案把重要信息存成结构化数据需要时直接查。比如用户偏好、历史任务结果这些用JSON文件或SQLite存就够了不必一上来就上向量库。注意记忆模块最容易出的问题是“记了不该记的”。比如把工具的原始输出全部塞进上下文导致prompt迅速膨胀。我的做法是只保留工具输出的关键字段其余丢弃。3.3 工具调用Agent和外部世界的接口工具调用是Agent最实用的能力。没有工具Agent只能“说”有了工具Agent才能“做”。工具可以是任何东西查天气的API、读文件的函数、执行计算的脚本、发送消息的接口。定义工具时最关键的是描述要清晰。模型是根据你的描述来决定要不要调用、怎么调用的。如果描述模糊模型要么不调用要么传错参数。一个好的工具描述应该包含工具做什么、什么时候用、参数是什么含义、返回什么格式。我通常会给每个工具写一段“使用场景”说明而不是只写功能。比如不要只写“查询天气”而要写“当用户询问某地天气、需要根据天气做决策时使用此工具”。这样模型更容易判断调用时机。工具调用的另一个要点是错误处理。工具可能失败API可能超时返回格式可能不符合预期。Agent需要能处理这些情况而不是一失败就崩溃。常见的做法是让工具返回结构化的结果包含成功标志和错误信息然后让模型根据错误信息决定重试还是换方案。3.4 执行循环Agent的心跳执行循环把前面三个模块串起来。一个典型的循环是接收用户输入→规划→选择工具→执行工具→观察结果→判断是否完成→如果未完成则继续循环。这个循环看起来简单但有几个细节容易出问题。第一是循环终止条件什么情况下认为任务完成了是模型说“完成”就算还是需要外部验证我一般会设置双重条件模型判断完成且没有待执行的工具调用。第二是最大循环次数防止Agent陷入死循环通常设5到10次就够了。第三是状态传递每一轮的结果要正确传递给下一轮不能丢失关键信息。执行循环的实现方式可以很简单一个while循环加几个if判断就能跑起来。关键是要把每一步的状态记录下来方便调试和恢复。4. 实操过程从环境准备到跑通第一个Agent4.1 环境准备和依赖安装先说一下基础环境。Python 3.10以上是必须的因为很多大模型相关的库已经不再支持更早的版本。我习惯用虚拟环境隔离项目依赖conda或者venv都行看个人习惯。python -m venv agent-env source agent-env/bin/activate # Windows下用 agent-env\Scripts\activate然后安装核心依赖。入门阶段不需要装太多东西一个HTTP客户端、一个大模型SDK、一个轻量Agent库就够了。pip install openai requests python-dotenv如果你用的是其他模型提供方把openai换成对应的SDK即可。python-dotenv用来管理API密钥避免把密钥硬编码在代码里。提示API密钥一定要放在环境变量或.env文件里并且把.env加入.gitignore。我见过不止一次有人把密钥提交到公开仓库结果被滥用。4.2 定义你的第一个工具工具的定义方式取决于你用的框架。如果用的是轻量库通常就是一个带类型注解的Python函数加上一段描述。我以查询天气为例def get_weather(city: str) - dict: 查询指定城市的当前天气。 当用户询问天气、需要根据天气做决策时使用此工具。 参数: city: 城市名称如北京、上海 返回: 包含温度、天气状况、湿度的字典 # 实际项目中这里调用天气API # 这里用模拟数据演示 return { city: city, temperature: 22, condition: 多云, humidity: 65 }这个函数本身很简单但描述部分很重要。我特意写了“当用户询问天气、需要根据天气做决策时使用”而不是只写“查询天气”。这个差别在实际运行中很明显——前者能让模型更准确地判断调用时机。4.3 组装Agent并跑通第一个任务把工具注册到Agent设置好模型和系统提示词就可以跑第一个任务了。系统提示词的核心是告诉模型它的角色、可用工具、以及行为规范。SYSTEM_PROMPT 你是一个乐于助人的助手可以调用工具来帮助用户解决问题。 可用工具 - get_weather: 查询城市天气 行为规范 1. 先理解用户需求再决定是否需要调用工具 2. 调用工具时确保参数正确 3. 拿到工具结果后用自然语言回复用户 4. 如果工具调用失败尝试其他方案或告知用户 然后创建一个简单的执行循环def run_agent(user_input, max_turns5): messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input} ] for turn in range(max_turns): response call_llm(messages) if response.has_tool_call: tool_name response.tool_name tool_args response.tool_args result execute_tool(tool_name, tool_args) messages.append(response.message) messages.append({role: tool, content: str(result)}) else: return response.content return 任务未在限定轮次内完成这段代码跑起来后你可以试试输入“北京今天天气怎么样”观察Agent是否调用了get_weather工具以及最终回复是否符合预期。4.4 参数选择与调优的实操记录模型参数里对Agent行为影响最大的是temperature。规划阶段我一般用0.2到0.3让输出更稳定工具调用阶段用0.1甚至0减少参数传错的概率最终回复阶段可以稍微高一点0.5到0.7让语言更自然。max_tokens也要注意。规划阶段的输出通常不长设500就够了但如果工具返回的结果很长需要留足空间。我一般设2000作为默认值特殊场景再调整。还有一个容易被忽略的参数是超时时间。工具调用可能因为网络问题卡住如果不设超时整个Agent就挂在那里了。我一般给每个工具调用设10到30秒的超时具体看工具的性质。5. 常见问题与排查技巧实录5.1 Agent不调用工具怎么办这是新手遇到最多的问题。模型明明知道有工具但就是不用直接用自己的知识回答。原因通常有三个工具描述不够清晰、系统提示词没有强调工具的使用、或者模型本身的能力限制。排查顺序是这样的先看工具描述是不是只写了功能没写使用场景再看系统提示词有没有明确说“需要实时信息时必须调用工具”最后换一个能力更强的模型试试。我实测下来工具描述的改进对调用率的影响最大有时候改一句话就能从50%提升到90%。5.2 工具调用参数传错怎么排查参数传错通常表现为字段名不对、类型不对、必填项缺失。排查方法是把模型输出的工具调用请求完整打印出来和工具定义逐一对照。一个常见原因是工具参数的命名不够直观。比如你定义了一个参数叫q模型很可能不知道这是查询词。改成query或者search_term准确率会明显提升。另一个原因是参数描述缺失模型只能靠猜。每个参数都应该有明确的类型和说明。5.3 Agent陷入循环怎么处理循环的典型表现是Agent反复调用同一个工具或者在不同工具之间来回跳转始终不给出最终答案。原因可能是规划不清晰、工具返回的结果让模型困惑、或者终止条件没设好。我的处理方式是设一个硬性的最大轮次限制比如5轮。超过就强制终止返回当前状态。同时在系统提示词里加一句“如果连续两次调用同一工具且结果相同请停止调用并告知用户”。这个简单的规则能解决大部分循环问题。5.4 上下文膨胀导致响应变慢Agent跑了几轮之后prompt会越来越长响应时间明显增加。这是因为每一轮的工具结果都追加到了消息历史里。解决办法是只保留关键信息丢弃冗余内容。比如天气API返回了20个字段你只需要温度和天气状况那就只把这两个字段放进上下文。另外可以定期对历史做摘要用一段简短的文字代替多轮对话。我一般每5轮做一次摘要压缩。5.5 常见问题速查表问题现象可能原因排查方法解决思路不调用工具描述不清、提示词未强调检查工具描述和系统提示补充使用场景说明参数传错参数名不直观、缺描述打印调用请求对照定义重命名参数、补充说明陷入循环规划不清、终止条件缺失查看每轮决策日志设最大轮次、加停止规则响应变慢上下文膨胀统计每轮token数精简工具输出、定期摘要工具报错后崩溃缺少错误处理查看异常堆栈工具返回结构化错误信息6. 进阶方向从能跑到好用6.1 多工具协作与工具链设计当Agent需要多个工具配合时设计就变得更重要了。比如一个“帮我规划旅行”的Agent可能需要查天气、查航班、查酒店、算预算。这些工具之间有依赖关系顺序不能乱。我的做法是把工具分成几类信息获取类、计算类、执行类。信息获取类可以并行调用计算类依赖前面的结果执行类放在最后。在系统提示词里说明这个分类模型会更容易做出合理的调用顺序。6.2 记忆的持久化与检索短期记忆解决的是单次会话的问题长期记忆解决的是跨会话的问题。入门阶段可以先用简单的键值存储把用户偏好、历史任务结果存下来。等数据量大了再考虑向量检索。持久化记忆的关键是写入时机和检索策略。不是所有信息都值得记我一般只记三类用户明确表达的偏好、任务的关键结果、以及反复出现的信息。检索时用语义相似度找最相关的几条不要全部塞进上下文。6.3 安全边界与权限控制Agent能调用工具就意味着它能产生实际影响。如果工具包括发邮件、改文件、执行命令那安全边界就非常重要。我的原则是最小权限。Agent只应该拥有完成任务所必需的权限不多给。具体做法包括工具层面做参数校验拒绝危险操作执行层面加确认机制重要操作需要二次确认日志层面记录所有工具调用方便审计。这些在入门阶段可能觉得多余但等到Agent真正处理实际任务时你会庆幸自己提前做了。6.4 性能优化并发与缓存当Agent需要处理多个任务时串行执行会很慢。这时候可以考虑并发。信息获取类的工具调用可以并行发出等所有结果返回后再进入下一步。Python里用asyncio或者线程池都能实现。缓存也很重要。同样的工具调用如果参数相同短时间内可以复用结果。比如天气查询5分钟内重复查询同一城市直接返回缓存结果就行。这能显著减少API调用次数和响应时间。7. 我个人的实操体会做Agent开发这段时间最大的感受是Agent的能力上限不取决于模型而取决于你怎么设计它的工作流。同样的模型工具描述改一改、提示词调一调、循环逻辑优化一下效果可能天差地别。另一个体会是不要追求一步到位。先跑通最小闭环哪怕只能查天气、只能做一件事也比一个功能齐全但跑不起来的系统强。跑通之后再逐步加工具、加记忆、加规划每一步都验证效果。最后分享一个小技巧给Agent加一个“思考日志”。每次它做决策时让它用一句话说明理由记录到日志里。这个日志在调试时非常有用你能清楚地看到它为什么选择这个工具、为什么跳过那个步骤。很多时候问题就藏在这些理由里。