1. 别急着装环境先搞清楚AI Agent到底在解决什么问题1.1 从“会聊天的模型”到“能办事的系统”很多人第一次接触AI Agent脑子里浮现的画面就是打开一个对话框输入问题模型给出回答。这个认知本身没错但它只覆盖了Agent能力光谱里最基础的那一段。真正让Agent这个词变得有价值的是它从“被动应答”跨到了“主动执行”。我打个比方。普通的对话模型像是一个坐在咨询台后面的顾问你问什么它答什么答完就结束了它不会站起来帮你把事办了。而Agent更像是一个你雇来的助理你说“帮我把下周出差的行程安排好”它会自己去查日历、比价、订票、发确认邮件中间遇到问题还会回来问你一句“经济舱没了商务舱可以吗”。这个差别听起来简单但背后涉及的东西完全不一样。对话模型只需要处理“输入到输出”的映射而Agent需要处理的是“目标到结果”的路径规划。路径规划意味着它得知道第一步做什么、第二步做什么中间某一步失败了怎么回退哪些操作需要用户确认哪些可以自主决定。这些问题的复杂度比单纯生成一段文字要高出一个量级。所以新手在入门阶段最应该先弄明白的一件事就是你手里的这个Agent它的自主边界在哪里。是完全自主执行还是每一步都需要人确认还是只在特定环节自主这个边界决定了你后面学什么、怎么学。1.2 为什么“先啃框架”是新手最容易踩的坑我见过太多人包括我自己早期也是这样一听说Agent火了第一反应就是去找一个框架然后照着文档跑一个Demo出来。跑通了就觉得自己入门了跑不通就开始怀疑自己是不是不适合搞这个。问题出在哪里出在框架本身是一个“封装层”。它把很多底层逻辑打包好了你调用一个接口就能得到一个看起来像模像样的Agent。但一旦出了问题你根本不知道是哪一层出了错。是提示词写得不对是工具调用的参数格式有问题是模型本身的理解能力不够还是框架在中间做了什么你没意识到的处理这就像学做菜你一上来就用料理机按一个按钮出来一锅汤。汤好喝你就觉得我会做饭了汤不好喝你连是食材的问题还是机器的问题都分不清。而如果你先从切菜、控火、调味这些基本功开始哪怕一开始做得不好吃你至少知道是盐放多了还是火太大了。框架不是不能学而是不应该作为起点。起点应该是那些不依赖任何框架就能理解和操作的核心概念。这些东西学扎实了后面看任何框架都是“哦它把这个步骤封装了一下”而不是“这黑盒里到底在干嘛”。1.3 一个合理的入门顺序长什么样基于我自己的经验和带过的一些新人的反馈我总结了一个相对稳妥的入门路径。这个路径不追求快追求的是每一步都踩实。第一步理解Agent的基本循环观察、思考、行动、再观察。这个循环不需要写代码用纸笔就能画出来。你要做的是拿一个具体的任务比如“帮我查一下明天北京的天气然后决定要不要带伞”手动把这个循环走一遍看看每一步需要什么信息、做什么判断。第二步学会写结构化的提示词。注意是结构化不是“请你帮我做某事”这种自然语言。结构化意味着你要明确告诉模型它的角色是什么、可用工具哪些、输出格式是什么、遇到什么情况该怎么处理。这一步不需要任何框架直接调模型的接口就能练。第三步手动实现一次工具调用。找一个最简单的工具比如一个查天气的接口自己写代码把模型的输出解析出来、调用接口、把结果拼回去再让模型生成最终回答。这个过程会让你真正理解Agent是怎么“动手”的。第四步引入记忆和状态管理。让Agent在多轮对话中记住之前说过什么、做过什么。这一步开始有复杂度了但依然可以不依赖框架用最简单的字典或者列表就能实现。第五步才是去看框架。这时候你看框架的文档会发现它帮你解决的就是你前面手动做过的那些事只是做得更通用、更健壮。你学起来会非常快而且知道什么时候该用框架、什么时候不该用。这个顺序的核心逻辑是先理解问题再理解解法最后才理解工具。反过来做工具就成了黑盒你永远在猜。2. 提示词不是“说话好听”而是“把话说清楚”2.1 结构化提示词的四个必备要素很多人对提示词的理解还停留在“把话说得客气一点、详细一点”。这个理解在对话场景下勉强够用但在Agent场景下远远不够。Agent的提示词更像是一份工作说明书它需要让模型清楚地知道你是谁、你能用什么、你要输出什么、遇到意外怎么办。我习惯把一份合格的Agent提示词拆成四个部分。第一部分是角色定义用一两句话说明这个Agent是干什么的。比如“你是一个帮助用户管理日程的助理可以查询日历、创建事件、发送提醒”。这部分不需要长但必须具体不能是“你是一个有用的助手”这种废话。第二部分是工具清单。把你提供给它的所有工具列出来每个工具说明它叫什么、接受什么参数、返回什么结果。这里的关键是参数格式要写死不能让模型自己猜。比如查天气的工具你要明确告诉它参数是城市名和日期格式是字符串而不是让它自己发挥。第三部分是输出规范。告诉模型它的回答应该是什么格式。是纯文本还是JSON需不需要包含特定的字段如果它要调用工具工具调用的格式是什么这部分是新手最容易忽略的但恰恰是最影响稳定性的。你不在提示词里把格式定死模型就会每次给你不一样的输出后面解析起来非常痛苦。第四部分是异常处理。告诉模型遇到不确定的情况该怎么办。是直接问用户还是先尝试一个默认方案工具调用失败了是重试还是放弃这部分决定了Agent的鲁棒性。没有异常处理的Agent一旦遇到预期外的情况就会胡言乱语。2.2 为什么“少即是多”在提示词里经常是错的网上有一种说法说提示词要尽量简短说多了模型会混乱。这个说法在特定场景下成立比如你只是让模型做一次简单的文本分类。但在Agent场景下我个人的经验是宁可写多不要写少。原因很简单。Agent要处理的任务链条比单次对话长得多中间涉及的判断也多得多。你少写一句“如果用户没有提供日期默认使用今天”模型就可能在某次调用中因为缺少日期参数而报错。你少写一句“工具返回结果为空时不要编造数据”模型就可能在你接口挂掉的时候给你编一个看起来很像真的答案。当然“写多”不等于“写乱”。我的做法是把提示词分成明确的段落每个段落用标题或者分隔符隔开。这样模型在理解的时候有清晰的结构不会把不同部分的信息混在一起。同时重要的约束我会在提示词的开头和结尾各强调一次因为模型对首尾信息的注意力通常更高。还有一个实操技巧把提示词当成代码来管理。什么意思就是每次修改提示词都记录一下改了什么、为什么改、改完之后效果有什么变化。我早期就是随手改改到最后自己都忘了哪版是哪版出了问题想回滚都找不到之前的版本。后来用最简单的文本文件加注释的方式管理效率高了很多。2.3 一个可以直接抄的提示词模板下面这个模板是我自己在用的适用于大多数工具调用型的Agent。你可以根据具体场景调整但结构建议保留。# 角色 你是一个[具体角色]负责[具体职责]。 # 可用工具 1. 工具名[名称] 描述[这个工具做什么] 参数[参数名][类型][说明] 返回[返回格式说明] 2. 工具名[名称] ... # 输出规范 - 当你需要调用工具时输出格式为{tool: 工具名, params: {...}} - 当你不需要调用工具时直接输出文本回答。 - 每次只调用一个工具等待结果后再决定下一步。 # 异常处理 - 如果用户请求缺少必要参数先向用户询问不要猜测。 - 如果工具返回错误向用户说明错误信息不要编造结果。 - 如果用户请求超出你的能力范围明确告知并建议替代方案。 # 重要提醒 - 不要编造工具返回的数据。 - 不要在没有调用工具的情况下声称你完成了需要工具才能完成的操作。这个模板看起来简单但它覆盖了Agent运行中最容易出问题的几个点。尤其是最后两条提醒能挡掉相当一部分“模型假装自己做了事”的情况。3. 工具调用Agent真正“动手”的地方3.1 工具调用的完整链路拆解工具调用是Agent从“说”到“做”的关键一步。很多新手觉得这一步很神秘其实拆开来看就是几个很朴素的环节。第一个环节是意图识别。模型根据用户的输入和当前的上下文判断是否需要调用工具、调用哪个工具。这个判断的质量取决于提示词写得好不好以及模型本身的能力。第二个环节是参数提取。模型从用户的自然语言里把工具需要的参数抽出来。比如用户说“帮我查一下后天上海的天气”模型需要提取出城市是上海、日期是后天。这里有个坑模型提取的日期往往是“后天”这种相对表述而工具接口通常需要“2025-06-15”这种绝对格式。所以你要么在提示词里要求模型转换成绝对日期要么在代码层做一次转换。第三个环节是工具执行。你的代码拿到模型输出的工具名和参数去调用对应的接口或函数。这一步是纯工程问题跟模型没关系了。第四个环节是结果回传。工具执行的结果需要被拼回对话上下文里让模型基于这个结果生成最终回答。这里要注意的是回传的结果最好做一次精简不要把接口返回的一大坨JSON原封不动塞回去否则会占用大量上下文窗口还可能干扰模型的判断。第五个环节是最终生成。模型拿到工具结果后结合原始问题生成一个自然语言的回答。这一步看起来简单但如果前面的结果格式不对模型很容易在这里胡编。整个链路走下来你会发现真正“智能”的部分其实只有第一和第二步后面三步都是工程实现。这也解释了为什么很多Agent Demo看起来很惊艳但一到实际使用就各种问题——因为工程实现的细节没处理好。3.2 参数校验别让模型“猜”你的接口我踩过最大的一个坑就是参数校验。早期我写工具的时候假设模型会按照我期望的格式传参数。结果实际跑起来模型有时候传字符串有时候传数字有时候多传一个字段有时候少传一个字段。接口那边一报错整个Agent就卡住了。后来我养成了一个习惯在工具执行的入口处做一层严格的参数校验。不管模型传什么过来先检查参数类型对不对、必填项有没有、值的范围是否合理。不合法就直接返回一个明确的错误信息给模型让它重新生成。这个错误信息也很关键。你不能只返回“参数错误”四个字要具体说“参数date的格式应该是YYYY-MM-DD你传的是‘后天’请转换后重试”。模型看到这种具体的反馈下一次生成正确的概率会高很多。还有一个技巧是在提示词里给每个参数加示例。比如“日期参数示例2025-06-15”。别小看这个示例它能显著降低模型传错格式的概率。人看文档的时候也喜欢看示例模型也一样。3.3 工具返回结果的处理艺术工具返回结果的处理直接决定了Agent的回答质量。我见过两种极端的做法都有问题。一种是完全不处理把接口返回的原始数据直接塞回给模型。比如查天气的接口返回了一百多行JSON包含温度、湿度、风速、气压、紫外线指数、日出日落时间等等。模型拿到这一大坨很容易抓不住重点回答里塞一堆用户没问的信息。另一种是过度处理在代码层就把结果总结成一句话再给模型。比如“上海后天晴25度”。这样做看起来干净但模型失去了原始数据如果用户追问“那湿度呢”模型就答不上来了。我的做法是折中保留关键字段去掉冗余字段同时保留一定的原始结构。比如天气接口我可能只保留温度、天气状况、湿度、风速这几个字段以简洁的JSON格式回传。这样模型既有足够的信息回答用户的直接问题也能应对一些简单的追问。另外工具返回结果里如果有时间戳、ID这类对用户无意义的字段最好在回传前去掉。模型看到这些字段可能会试图把它们编进回答里导致回答看起来很怪。4. 记忆与状态让Agent不再“金鱼脑”4.1 短期记忆和长期记忆的分工没有记忆的Agent每一轮对话都是重新开始。用户上一句说了“我叫张三”下一句问“我叫什么”它答不上来。这种体验在Demo里可能不明显但一到实际使用就会让人抓狂。Agent的记忆我习惯分成两类。一类是短期记忆就是当前这次对话的上下文。它决定了Agent能不能理解“它”“那个”“刚才说的”这些指代。短期记忆的实现最简单就是把历史消息按顺序拼在提示词里。但这里有个限制模型的上下文窗口是有限的对话轮次多了之后早期的消息会被挤掉。另一类是长期记忆就是跨对话保留的信息。比如用户的偏好、之前处理过的任务、常用的参数等等。长期记忆需要外部存储可以用最简单的文件也可以用数据库。关键是在每次对话开始时把相关的长期记忆检索出来拼进提示词里。新手容易犯的一个错误是把所有历史消息都塞进上下文觉得越多越好。实际上上下文越长模型对每条信息的注意力就越分散而且成本也越高。我的经验是短期记忆保留最近五到十轮就够了更早的内容要么总结成摘要要么直接丢弃。长期记忆则要有选择地检索只取跟当前任务相关的部分。4.2 状态管理的三种常见模式Agent的状态管理说白了就是“它现在处于什么阶段”。一个任务可能分好几步Agent需要知道自己走到哪了、下一步该干嘛。第一种模式是无状态。每一轮对话都是独立的Agent不记录任何跨轮次的信息。这种模式最简单适合那种一问一答就结束的场景。但稍微复杂一点的任务就搞不定了。第二种模式是会话状态。Agent记住当前会话里发生了什么但会话结束就清空。这是最常见的模式适合大多数对话式Agent。实现方式就是把历史消息存在内存里每次请求带上。第三种模式是任务状态。Agent不仅记住对话还记住任务的进度。比如一个订票任务Agent需要知道现在是“已确认出发地”还是“已确认日期”还是“已选好航班”。这种模式需要显式地维护一个状态变量每次模型输出后更新这个变量下次请求时把它拼进提示词。我个人的建议是新手先从无状态开始跑通基本流程后加上会话状态等遇到多步骤任务再引入任务状态。不要一上来就搞最复杂的容易把自己绕进去。4.3 记忆检索的一个实用技巧长期记忆的检索很多人第一反应是用向量数据库做语义搜索。这当然可以但对于新手来说引入向量数据库意味着额外的依赖和复杂度。我的建议是先用最简单的方式关键词匹配。具体做法是给每条长期记忆打上标签比如“用户偏好”“历史任务”“常用参数”。每次对话开始时根据当前用户输入的关键词去匹配标签把匹配到的记忆取出来。这种方式虽然粗糙但在记忆量不大的时候完全够用而且实现成本极低。等记忆量上来了、关键词匹配不够准了再考虑上向量检索。这时候你已经对记忆的结构和检索需求有了清晰的认识选型和调优都会更有方向。5. 新手最常遇到的五个坑和排查思路5.1 模型不调用工具直接编答案这是最高频的问题。你明明给了工具模型却不用直接凭自己的知识回答。原因通常有三个一是提示词里没有强调“必须使用工具”模型觉得自己的知识够用二是工具的描述不够清晰模型没看懂这个工具是干嘛的三是用户的问题本身模糊模型判断不需要工具。排查的时候先看提示词。在角色定义或者输出规范里加一句“对于需要实时数据或外部信息的问题必须先调用工具不得直接回答”。如果还不行检查工具描述确保每个工具的功能、参数、返回都写得足够具体。最后看用户输入如果问题本身有歧义模型确实可能判断失误这时候需要在提示词里加一些示例告诉它什么情况下该调用什么工具。5.2 工具调用参数格式错误模型传的参数格式跟接口要求的不一致导致调用失败。这个问题前面提过核心解法是在提示词里给每个参数加类型说明和示例同时在代码层做参数校验和转换。还有一个容易被忽略的点模型有时候会把参数包在多余的嵌套结构里。比如你期望的是{city: 上海}它给你的是{params: {city: 上海}}。这种问题靠提示词很难完全避免最好在代码层做一次兼容处理把常见的嵌套结构拍平。5.3 多轮对话后Agent“失忆”对话轮次多了之后Agent开始忘记之前说过的信息。这是上下文窗口限制导致的。解法有两个方向一是控制上下文长度只保留最近几轮更早的做摘要二是把关键信息提取出来存到外部每次请求时重新注入。我通常的做法是在每轮对话结束后让模型自己总结一下“这轮对话里有哪些关键信息需要记住”然后把总结存起来。下次请求时把最近的总结拼进提示词。这样既控制了长度又保留了关键信息。5.4 Agent陷入循环反复调用同一个工具有时候Agent会卡在一个循环里反复调用同一个工具每次都得到相同的结果但就是不停。这通常是因为提示词里没有定义“什么时候算完成”。模型不知道任务已经结束了就继续调用。解法是在提示词里明确写出任务的完成条件。比如“当你已经获取到用户需要的天气信息并生成了回答后任务结束不要再调用工具”。另外在代码层加一个最大调用次数的限制超过就强制终止避免无限循环消耗资源。5.5 回答里混入了工具返回的原始格式模型把工具返回的JSON或者代码直接贴进了回答里用户看到一堆花括号。这是因为提示词里没有要求模型“用自然语言重新组织工具返回的结果”。解法很简单在输出规范里加一句“工具返回的结果需要用自然语言重新表述不要直接粘贴原始格式”。如果加了这句还不行可能是模型对“自然语言”的理解有偏差。这时候可以在提示词里给一个正面示例展示什么样的回答是合格的。6. 什么时候该引入框架怎么选6.1 引入框架的三个信号前面说了那么多“别急着上框架”那什么时候该上呢我总结三个信号。第一个信号是你发现自己手动实现的那些逻辑开始重复了。比如每个Agent你都要写一遍工具调用的解析、参数校验、结果回传代码越写越像。这时候框架的价值就体现出来了它把这些通用逻辑封装好了。第二个信号是你需要管理的Agent数量超过了两三个。手动管理每个Agent的提示词、工具、记忆、状态很快就会乱。框架提供的统一管理能力能帮你省很多事。第三个信号是你需要更复杂的编排逻辑。比如多个Agent协作、条件分支、循环重试等等。这些逻辑手动实现不是不行但很容易写出bug用框架会更稳妥。6.2 选框架时看什么选框架的时候我建议重点看三个东西。第一看它的抽象层次。有些框架抽象得很高你只需要配置几个参数就能跑起来但出了问题很难排查。有些框架抽象得比较低需要你写不少代码但每一步都透明可控。新手建议选抽象层次适中的既能省事又不至于完全黑盒。第二看它的社区活跃度。Agent这个领域变化很快框架的更新频率很重要。一个半年没更新的框架很可能已经跟不上最新的模型能力了。去它的代码仓库看看最近的提交记录和issue回复速度能看出不少东西。第三看它的文档质量。文档好的框架你遇到问题能自己解决文档差的框架你只能去社区里问效率低很多。尤其要看它有没有完整的示例代码和常见问题解答。6.3 从手动到框架的过渡建议如果你已经手动实现过一个能跑的Agent过渡到框架会非常顺。我的建议是不要一上来就把手动实现的那套全部推倒重来而是先用框架重写其中一个最简单的Agent跑通之后对比一下两者的差异。重点对比几个方面框架帮你省了哪些代码、引入了哪些新的概念、哪些地方比手动实现更灵活、哪些地方反而不如手动实现可控。这个对比过程会让你对框架的理解深入很多后面用起来也更得心应手。如果对比下来发现框架带来的收益不明显那完全可以继续用手动实现。框架不是目的把Agent做好才是目的。我到现在还有一些简单的Agent是纯手动实现的因为需求太简单上框架反而是负担。7. 一个完整的练手项目从零到一实现天气助手Agent7.1 项目目标和拆解说了这么多理论最后给一个完整的练手项目把前面讲的东西串起来。项目目标很简单做一个天气助手Agent用户输入城市和日期它调用天气接口获取数据然后用自然语言回答。拆解一下这个项目需要四个模块。第一个是提示词模块定义Agent的角色、工具、输出规范。第二个是工具模块实现一个查天气的函数。第三个是对话循环模块处理用户输入、调用模型、解析输出、执行工具、回传结果。第四个是记忆模块让Agent记住当前对话的上下文。这四个模块加起来代码量大概在一百到两百行之间非常适合新手练手。7.2 关键代码结构说明提示词部分按照前面给的模板写角色是“天气查询助手”工具是“get_weather”参数是城市和日期输出规范要求模型在需要查天气时输出JSON格式的工具调用请求。工具部分用一个模拟的天气查询函数代替真实接口返回一个包含温度、天气状况、湿度的字典。真实项目里换成实际的接口调用即可。对话循环部分核心逻辑是一个while循环接收用户输入、拼装提示词、调用模型、解析模型输出、如果是工具调用就执行工具并把结果拼回上下文、如果是文本回答就输出给用户。记忆部分用一个列表存历史消息每次请求时把最近十条拼进提示词。7.3 跑通之后的扩展方向这个项目跑通之后你可以往几个方向扩展。一是加更多的工具比如查空气质量、查日出日落时间让Agent能回答更丰富的问题。二是加多轮对话能力让用户可以在一次会话里连续查询多个城市。三是加错误处理比如接口超时、城市名不存在等情况下的友好提示。每加一个功能你都会遇到新的问题解决这些问题的过程就是最好的学习。比看十篇教程都管用。我个人在实际操作中的体会是Agent这个领域看起来花哨但底层的东西其实很朴素。把提示词写清楚、把工具调用的链路走通、把记忆和状态管理好大部分场景就够用了。框架是加速器不是发动机。发动机得你自己先造出来哪怕是个简陋的版本也比直接开别人的车强。 
长河君 · 2026/10/22 15:32:58 · 阅读 1.2k AI Agent入门指南：从提示词到工具调用，手把手教你构建天气助手
1. 别急着装环境先搞清楚AI Agent到底在解决什么问题1.1 从“会聊天的模型”到“能办事的系统”很多人第一次接触AI Agent脑子里浮现的画面就是打开一个对话框输入问题模型给出回答。这个认知本身没错但它只覆盖了Agent能力光谱里最基础的那一段。真正让Agent这个词变得有价值的是它从“被动应答”跨到了“主动执行”。我打个比方。普通的对话模型像是一个坐在咨询台后面的顾问你问什么它答什么答完就结束了它不会站起来帮你把事办了。而Agent更像是一个你雇来的助理你说“帮我把下周出差的行程安排好”它会自己去查日历、比价、订票、发确认邮件中间遇到问题还会回来问你一句“经济舱没了商务舱可以吗”。这个差别听起来简单但背后涉及的东西完全不一样。对话模型只需要处理“输入到输出”的映射而Agent需要处理的是“目标到结果”的路径规划。路径规划意味着它得知道第一步做什么、第二步做什么中间某一步失败了怎么回退哪些操作需要用户确认哪些可以自主决定。这些问题的复杂度比单纯生成一段文字要高出一个量级。所以新手在入门阶段最应该先弄明白的一件事就是你手里的这个Agent它的自主边界在哪里。是完全自主执行还是每一步都需要人确认还是只在特定环节自主这个边界决定了你后面学什么、怎么学。1.2 为什么“先啃框架”是新手最容易踩的坑我见过太多人包括我自己早期也是这样一听说Agent火了第一反应就是去找一个框架然后照着文档跑一个Demo出来。跑通了就觉得自己入门了跑不通就开始怀疑自己是不是不适合搞这个。问题出在哪里出在框架本身是一个“封装层”。它把很多底层逻辑打包好了你调用一个接口就能得到一个看起来像模像样的Agent。但一旦出了问题你根本不知道是哪一层出了错。是提示词写得不对是工具调用的参数格式有问题是模型本身的理解能力不够还是框架在中间做了什么你没意识到的处理这就像学做菜你一上来就用料理机按一个按钮出来一锅汤。汤好喝你就觉得我会做饭了汤不好喝你连是食材的问题还是机器的问题都分不清。而如果你先从切菜、控火、调味这些基本功开始哪怕一开始做得不好吃你至少知道是盐放多了还是火太大了。框架不是不能学而是不应该作为起点。起点应该是那些不依赖任何框架就能理解和操作的核心概念。这些东西学扎实了后面看任何框架都是“哦它把这个步骤封装了一下”而不是“这黑盒里到底在干嘛”。1.3 一个合理的入门顺序长什么样基于我自己的经验和带过的一些新人的反馈我总结了一个相对稳妥的入门路径。这个路径不追求快追求的是每一步都踩实。第一步理解Agent的基本循环观察、思考、行动、再观察。这个循环不需要写代码用纸笔就能画出来。你要做的是拿一个具体的任务比如“帮我查一下明天北京的天气然后决定要不要带伞”手动把这个循环走一遍看看每一步需要什么信息、做什么判断。第二步学会写结构化的提示词。注意是结构化不是“请你帮我做某事”这种自然语言。结构化意味着你要明确告诉模型它的角色是什么、可用工具哪些、输出格式是什么、遇到什么情况该怎么处理。这一步不需要任何框架直接调模型的接口就能练。第三步手动实现一次工具调用。找一个最简单的工具比如一个查天气的接口自己写代码把模型的输出解析出来、调用接口、把结果拼回去再让模型生成最终回答。这个过程会让你真正理解Agent是怎么“动手”的。第四步引入记忆和状态管理。让Agent在多轮对话中记住之前说过什么、做过什么。这一步开始有复杂度了但依然可以不依赖框架用最简单的字典或者列表就能实现。第五步才是去看框架。这时候你看框架的文档会发现它帮你解决的就是你前面手动做过的那些事只是做得更通用、更健壮。你学起来会非常快而且知道什么时候该用框架、什么时候不该用。这个顺序的核心逻辑是先理解问题再理解解法最后才理解工具。反过来做工具就成了黑盒你永远在猜。2. 提示词不是“说话好听”而是“把话说清楚”2.1 结构化提示词的四个必备要素很多人对提示词的理解还停留在“把话说得客气一点、详细一点”。这个理解在对话场景下勉强够用但在Agent场景下远远不够。Agent的提示词更像是一份工作说明书它需要让模型清楚地知道你是谁、你能用什么、你要输出什么、遇到意外怎么办。我习惯把一份合格的Agent提示词拆成四个部分。第一部分是角色定义用一两句话说明这个Agent是干什么的。比如“你是一个帮助用户管理日程的助理可以查询日历、创建事件、发送提醒”。这部分不需要长但必须具体不能是“你是一个有用的助手”这种废话。第二部分是工具清单。把你提供给它的所有工具列出来每个工具说明它叫什么、接受什么参数、返回什么结果。这里的关键是参数格式要写死不能让模型自己猜。比如查天气的工具你要明确告诉它参数是城市名和日期格式是字符串而不是让它自己发挥。第三部分是输出规范。告诉模型它的回答应该是什么格式。是纯文本还是JSON需不需要包含特定的字段如果它要调用工具工具调用的格式是什么这部分是新手最容易忽略的但恰恰是最影响稳定性的。你不在提示词里把格式定死模型就会每次给你不一样的输出后面解析起来非常痛苦。第四部分是异常处理。告诉模型遇到不确定的情况该怎么办。是直接问用户还是先尝试一个默认方案工具调用失败了是重试还是放弃这部分决定了Agent的鲁棒性。没有异常处理的Agent一旦遇到预期外的情况就会胡言乱语。2.2 为什么“少即是多”在提示词里经常是错的网上有一种说法说提示词要尽量简短说多了模型会混乱。这个说法在特定场景下成立比如你只是让模型做一次简单的文本分类。但在Agent场景下我个人的经验是宁可写多不要写少。原因很简单。Agent要处理的任务链条比单次对话长得多中间涉及的判断也多得多。你少写一句“如果用户没有提供日期默认使用今天”模型就可能在某次调用中因为缺少日期参数而报错。你少写一句“工具返回结果为空时不要编造数据”模型就可能在你接口挂掉的时候给你编一个看起来很像真的答案。当然“写多”不等于“写乱”。我的做法是把提示词分成明确的段落每个段落用标题或者分隔符隔开。这样模型在理解的时候有清晰的结构不会把不同部分的信息混在一起。同时重要的约束我会在提示词的开头和结尾各强调一次因为模型对首尾信息的注意力通常更高。还有一个实操技巧把提示词当成代码来管理。什么意思就是每次修改提示词都记录一下改了什么、为什么改、改完之后效果有什么变化。我早期就是随手改改到最后自己都忘了哪版是哪版出了问题想回滚都找不到之前的版本。后来用最简单的文本文件加注释的方式管理效率高了很多。2.3 一个可以直接抄的提示词模板下面这个模板是我自己在用的适用于大多数工具调用型的Agent。你可以根据具体场景调整但结构建议保留。# 角色 你是一个[具体角色]负责[具体职责]。 # 可用工具 1. 工具名[名称] 描述[这个工具做什么] 参数[参数名][类型][说明] 返回[返回格式说明] 2. 工具名[名称] ... # 输出规范 - 当你需要调用工具时输出格式为{tool: 工具名, params: {...}} - 当你不需要调用工具时直接输出文本回答。 - 每次只调用一个工具等待结果后再决定下一步。 # 异常处理 - 如果用户请求缺少必要参数先向用户询问不要猜测。 - 如果工具返回错误向用户说明错误信息不要编造结果。 - 如果用户请求超出你的能力范围明确告知并建议替代方案。 # 重要提醒 - 不要编造工具返回的数据。 - 不要在没有调用工具的情况下声称你完成了需要工具才能完成的操作。这个模板看起来简单但它覆盖了Agent运行中最容易出问题的几个点。尤其是最后两条提醒能挡掉相当一部分“模型假装自己做了事”的情况。3. 工具调用Agent真正“动手”的地方3.1 工具调用的完整链路拆解工具调用是Agent从“说”到“做”的关键一步。很多新手觉得这一步很神秘其实拆开来看就是几个很朴素的环节。第一个环节是意图识别。模型根据用户的输入和当前的上下文判断是否需要调用工具、调用哪个工具。这个判断的质量取决于提示词写得好不好以及模型本身的能力。第二个环节是参数提取。模型从用户的自然语言里把工具需要的参数抽出来。比如用户说“帮我查一下后天上海的天气”模型需要提取出城市是上海、日期是后天。这里有个坑模型提取的日期往往是“后天”这种相对表述而工具接口通常需要“2025-06-15”这种绝对格式。所以你要么在提示词里要求模型转换成绝对日期要么在代码层做一次转换。第三个环节是工具执行。你的代码拿到模型输出的工具名和参数去调用对应的接口或函数。这一步是纯工程问题跟模型没关系了。第四个环节是结果回传。工具执行的结果需要被拼回对话上下文里让模型基于这个结果生成最终回答。这里要注意的是回传的结果最好做一次精简不要把接口返回的一大坨JSON原封不动塞回去否则会占用大量上下文窗口还可能干扰模型的判断。第五个环节是最终生成。模型拿到工具结果后结合原始问题生成一个自然语言的回答。这一步看起来简单但如果前面的结果格式不对模型很容易在这里胡编。整个链路走下来你会发现真正“智能”的部分其实只有第一和第二步后面三步都是工程实现。这也解释了为什么很多Agent Demo看起来很惊艳但一到实际使用就各种问题——因为工程实现的细节没处理好。3.2 参数校验别让模型“猜”你的接口我踩过最大的一个坑就是参数校验。早期我写工具的时候假设模型会按照我期望的格式传参数。结果实际跑起来模型有时候传字符串有时候传数字有时候多传一个字段有时候少传一个字段。接口那边一报错整个Agent就卡住了。后来我养成了一个习惯在工具执行的入口处做一层严格的参数校验。不管模型传什么过来先检查参数类型对不对、必填项有没有、值的范围是否合理。不合法就直接返回一个明确的错误信息给模型让它重新生成。这个错误信息也很关键。你不能只返回“参数错误”四个字要具体说“参数date的格式应该是YYYY-MM-DD你传的是‘后天’请转换后重试”。模型看到这种具体的反馈下一次生成正确的概率会高很多。还有一个技巧是在提示词里给每个参数加示例。比如“日期参数示例2025-06-15”。别小看这个示例它能显著降低模型传错格式的概率。人看文档的时候也喜欢看示例模型也一样。3.3 工具返回结果的处理艺术工具返回结果的处理直接决定了Agent的回答质量。我见过两种极端的做法都有问题。一种是完全不处理把接口返回的原始数据直接塞回给模型。比如查天气的接口返回了一百多行JSON包含温度、湿度、风速、气压、紫外线指数、日出日落时间等等。模型拿到这一大坨很容易抓不住重点回答里塞一堆用户没问的信息。另一种是过度处理在代码层就把结果总结成一句话再给模型。比如“上海后天晴25度”。这样做看起来干净但模型失去了原始数据如果用户追问“那湿度呢”模型就答不上来了。我的做法是折中保留关键字段去掉冗余字段同时保留一定的原始结构。比如天气接口我可能只保留温度、天气状况、湿度、风速这几个字段以简洁的JSON格式回传。这样模型既有足够的信息回答用户的直接问题也能应对一些简单的追问。另外工具返回结果里如果有时间戳、ID这类对用户无意义的字段最好在回传前去掉。模型看到这些字段可能会试图把它们编进回答里导致回答看起来很怪。4. 记忆与状态让Agent不再“金鱼脑”4.1 短期记忆和长期记忆的分工没有记忆的Agent每一轮对话都是重新开始。用户上一句说了“我叫张三”下一句问“我叫什么”它答不上来。这种体验在Demo里可能不明显但一到实际使用就会让人抓狂。Agent的记忆我习惯分成两类。一类是短期记忆就是当前这次对话的上下文。它决定了Agent能不能理解“它”“那个”“刚才说的”这些指代。短期记忆的实现最简单就是把历史消息按顺序拼在提示词里。但这里有个限制模型的上下文窗口是有限的对话轮次多了之后早期的消息会被挤掉。另一类是长期记忆就是跨对话保留的信息。比如用户的偏好、之前处理过的任务、常用的参数等等。长期记忆需要外部存储可以用最简单的文件也可以用数据库。关键是在每次对话开始时把相关的长期记忆检索出来拼进提示词里。新手容易犯的一个错误是把所有历史消息都塞进上下文觉得越多越好。实际上上下文越长模型对每条信息的注意力就越分散而且成本也越高。我的经验是短期记忆保留最近五到十轮就够了更早的内容要么总结成摘要要么直接丢弃。长期记忆则要有选择地检索只取跟当前任务相关的部分。4.2 状态管理的三种常见模式Agent的状态管理说白了就是“它现在处于什么阶段”。一个任务可能分好几步Agent需要知道自己走到哪了、下一步该干嘛。第一种模式是无状态。每一轮对话都是独立的Agent不记录任何跨轮次的信息。这种模式最简单适合那种一问一答就结束的场景。但稍微复杂一点的任务就搞不定了。第二种模式是会话状态。Agent记住当前会话里发生了什么但会话结束就清空。这是最常见的模式适合大多数对话式Agent。实现方式就是把历史消息存在内存里每次请求带上。第三种模式是任务状态。Agent不仅记住对话还记住任务的进度。比如一个订票任务Agent需要知道现在是“已确认出发地”还是“已确认日期”还是“已选好航班”。这种模式需要显式地维护一个状态变量每次模型输出后更新这个变量下次请求时把它拼进提示词。我个人的建议是新手先从无状态开始跑通基本流程后加上会话状态等遇到多步骤任务再引入任务状态。不要一上来就搞最复杂的容易把自己绕进去。4.3 记忆检索的一个实用技巧长期记忆的检索很多人第一反应是用向量数据库做语义搜索。这当然可以但对于新手来说引入向量数据库意味着额外的依赖和复杂度。我的建议是先用最简单的方式关键词匹配。具体做法是给每条长期记忆打上标签比如“用户偏好”“历史任务”“常用参数”。每次对话开始时根据当前用户输入的关键词去匹配标签把匹配到的记忆取出来。这种方式虽然粗糙但在记忆量不大的时候完全够用而且实现成本极低。等记忆量上来了、关键词匹配不够准了再考虑上向量检索。这时候你已经对记忆的结构和检索需求有了清晰的认识选型和调优都会更有方向。5. 新手最常遇到的五个坑和排查思路5.1 模型不调用工具直接编答案这是最高频的问题。你明明给了工具模型却不用直接凭自己的知识回答。原因通常有三个一是提示词里没有强调“必须使用工具”模型觉得自己的知识够用二是工具的描述不够清晰模型没看懂这个工具是干嘛的三是用户的问题本身模糊模型判断不需要工具。排查的时候先看提示词。在角色定义或者输出规范里加一句“对于需要实时数据或外部信息的问题必须先调用工具不得直接回答”。如果还不行检查工具描述确保每个工具的功能、参数、返回都写得足够具体。最后看用户输入如果问题本身有歧义模型确实可能判断失误这时候需要在提示词里加一些示例告诉它什么情况下该调用什么工具。5.2 工具调用参数格式错误模型传的参数格式跟接口要求的不一致导致调用失败。这个问题前面提过核心解法是在提示词里给每个参数加类型说明和示例同时在代码层做参数校验和转换。还有一个容易被忽略的点模型有时候会把参数包在多余的嵌套结构里。比如你期望的是{city: 上海}它给你的是{params: {city: 上海}}。这种问题靠提示词很难完全避免最好在代码层做一次兼容处理把常见的嵌套结构拍平。5.3 多轮对话后Agent“失忆”对话轮次多了之后Agent开始忘记之前说过的信息。这是上下文窗口限制导致的。解法有两个方向一是控制上下文长度只保留最近几轮更早的做摘要二是把关键信息提取出来存到外部每次请求时重新注入。我通常的做法是在每轮对话结束后让模型自己总结一下“这轮对话里有哪些关键信息需要记住”然后把总结存起来。下次请求时把最近的总结拼进提示词。这样既控制了长度又保留了关键信息。5.4 Agent陷入循环反复调用同一个工具有时候Agent会卡在一个循环里反复调用同一个工具每次都得到相同的结果但就是不停。这通常是因为提示词里没有定义“什么时候算完成”。模型不知道任务已经结束了就继续调用。解法是在提示词里明确写出任务的完成条件。比如“当你已经获取到用户需要的天气信息并生成了回答后任务结束不要再调用工具”。另外在代码层加一个最大调用次数的限制超过就强制终止避免无限循环消耗资源。5.5 回答里混入了工具返回的原始格式模型把工具返回的JSON或者代码直接贴进了回答里用户看到一堆花括号。这是因为提示词里没有要求模型“用自然语言重新组织工具返回的结果”。解法很简单在输出规范里加一句“工具返回的结果需要用自然语言重新表述不要直接粘贴原始格式”。如果加了这句还不行可能是模型对“自然语言”的理解有偏差。这时候可以在提示词里给一个正面示例展示什么样的回答是合格的。6. 什么时候该引入框架怎么选6.1 引入框架的三个信号前面说了那么多“别急着上框架”那什么时候该上呢我总结三个信号。第一个信号是你发现自己手动实现的那些逻辑开始重复了。比如每个Agent你都要写一遍工具调用的解析、参数校验、结果回传代码越写越像。这时候框架的价值就体现出来了它把这些通用逻辑封装好了。第二个信号是你需要管理的Agent数量超过了两三个。手动管理每个Agent的提示词、工具、记忆、状态很快就会乱。框架提供的统一管理能力能帮你省很多事。第三个信号是你需要更复杂的编排逻辑。比如多个Agent协作、条件分支、循环重试等等。这些逻辑手动实现不是不行但很容易写出bug用框架会更稳妥。6.2 选框架时看什么选框架的时候我建议重点看三个东西。第一看它的抽象层次。有些框架抽象得很高你只需要配置几个参数就能跑起来但出了问题很难排查。有些框架抽象得比较低需要你写不少代码但每一步都透明可控。新手建议选抽象层次适中的既能省事又不至于完全黑盒。第二看它的社区活跃度。Agent这个领域变化很快框架的更新频率很重要。一个半年没更新的框架很可能已经跟不上最新的模型能力了。去它的代码仓库看看最近的提交记录和issue回复速度能看出不少东西。第三看它的文档质量。文档好的框架你遇到问题能自己解决文档差的框架你只能去社区里问效率低很多。尤其要看它有没有完整的示例代码和常见问题解答。6.3 从手动到框架的过渡建议如果你已经手动实现过一个能跑的Agent过渡到框架会非常顺。我的建议是不要一上来就把手动实现的那套全部推倒重来而是先用框架重写其中一个最简单的Agent跑通之后对比一下两者的差异。重点对比几个方面框架帮你省了哪些代码、引入了哪些新的概念、哪些地方比手动实现更灵活、哪些地方反而不如手动实现可控。这个对比过程会让你对框架的理解深入很多后面用起来也更得心应手。如果对比下来发现框架带来的收益不明显那完全可以继续用手动实现。框架不是目的把Agent做好才是目的。我到现在还有一些简单的Agent是纯手动实现的因为需求太简单上框架反而是负担。7. 一个完整的练手项目从零到一实现天气助手Agent7.1 项目目标和拆解说了这么多理论最后给一个完整的练手项目把前面讲的东西串起来。项目目标很简单做一个天气助手Agent用户输入城市和日期它调用天气接口获取数据然后用自然语言回答。拆解一下这个项目需要四个模块。第一个是提示词模块定义Agent的角色、工具、输出规范。第二个是工具模块实现一个查天气的函数。第三个是对话循环模块处理用户输入、调用模型、解析输出、执行工具、回传结果。第四个是记忆模块让Agent记住当前对话的上下文。这四个模块加起来代码量大概在一百到两百行之间非常适合新手练手。7.2 关键代码结构说明提示词部分按照前面给的模板写角色是“天气查询助手”工具是“get_weather”参数是城市和日期输出规范要求模型在需要查天气时输出JSON格式的工具调用请求。工具部分用一个模拟的天气查询函数代替真实接口返回一个包含温度、天气状况、湿度的字典。真实项目里换成实际的接口调用即可。对话循环部分核心逻辑是一个while循环接收用户输入、拼装提示词、调用模型、解析模型输出、如果是工具调用就执行工具并把结果拼回上下文、如果是文本回答就输出给用户。记忆部分用一个列表存历史消息每次请求时把最近十条拼进提示词。7.3 跑通之后的扩展方向这个项目跑通之后你可以往几个方向扩展。一是加更多的工具比如查空气质量、查日出日落时间让Agent能回答更丰富的问题。二是加多轮对话能力让用户可以在一次会话里连续查询多个城市。三是加错误处理比如接口超时、城市名不存在等情况下的友好提示。每加一个功能你都会遇到新的问题解决这些问题的过程就是最好的学习。比看十篇教程都管用。我个人在实际操作中的体会是Agent这个领域看起来花哨但底层的东西其实很朴素。把提示词写清楚、把工具调用的链路走通、把记忆和状态管理好大部分场景就够用了。框架是加速器不是发动机。发动机得你自己先造出来哪怕是个简陋的版本也比直接开别人的车强。