大模型应用开发这两年最热闹的方向就是 AI Agent。很多人手里捏着 API Key把几个模型的聊天接口调通了然后就不知道该往哪儿走是直接套 LangChain 模板还是自己写工具调用要不要上 RAG多个 Agent 到底怎么配合黄佳的《大模型应用开发动手做 AI Agent》给了一条相对完整的路线用 7 个实战项目从最简单的模型调用出发一路做到带检索、带工具、能协作的智能体系统。这篇文章不打算复述目录而是把我自己照着这条路线重新做一遍之后的拆解笔记和实操心得整理出来每个项目解决什么问题、背后的核心机制是什么、真正的坑在哪一次性讲透。适合刚开始接触大模型应用、或者写完几个 Demo 之后想往工程化方向走的开发者参考。1. 先理解一件事Agent 与大模型应用的真正分界线1.1 从 ChatBot 到 Agent多出来的不是“对话”而是“执行”大模型应用开发刚入门的时候大家做的事情基本都差不多把一段 Prompt 丢给模型把返回结果打印出来。这个东西叫 ChatBot 可能更准确因为模型只是做了一次单向的文本生成。Agent 不一样它的核心是“执行”——不仅要理解任务还要把一个任务拆成几步按顺序或按条件调用工具把每步的结果拿回来继续推理最后给出一个可交付的结果。我习惯用一个类比ChatBot 是问路Agent 是托人办事。问路的时候你说一遍对方告诉你方向交流就结束了。托人办事的时候对方要自己判断路线、查地图、遇到岔路还要回来问你、最后给你带回结果。这个过程中“工具”“记忆”“规划”“反馈”四个词是关键。工具让模型能查数据、能执行动作记忆让它在多轮里不丢上下文规划让它在复杂目标前不慌反馈让它在出错时能自我修正。这四个能力才是一个 Agent “智能”的来源也是 7 个实战项目反复训练的东西。1.2 7 个项目的设计逻辑不是堆功能是铺能力阶梯我看过很多大模型相关的资料最大的问题是上来就丢给你一个 LangChain 全家桶结果你连 Prompt 和 Function Calling 的关系都没搞清楚就被 Agent、Chain、Tool、Memory 这些词砸晕了。这本书的路线聪明在它不急着上框架而是先用几个非常朴素的实战项目把“裸模型”的能力边界摸清楚再逐步叠加外部能力。按我自己的理解这条路线可以分成四段阶梯。第一段是“让模型说人话”对应最开始的模型调用和 Prompt 实战第二段是“让模型记东西”解决上下文和知识注入的问题第三段是“让模型会动手”引入工具调用和流程编排第四段是“让模型能协作”把多个 Agent 组织起来一起干活。七个项目分别落在这四段里每一个都只解决一个核心问题没有花哨功能这样学到的东西才是可迁移的。这个设计逻辑本身就是这本书最重要的“元知识”构建 Agent 的正确顺序是先裸奔再用框架先单一再协作。很多人在第一步就犯了错误——直接上 LangGraph 写复杂图结果基础没打牢出问题根本不知道是模型的问题、Prompt 的问题还是框架的问题。2. 7 个实战项目的能力阶梯与拆解思路2.1 一张表看懂 7 个项目的定位为了后面拆起来不晕我先用自己的话把 7 个项目的定位整理成一张表。注意这里的“项目几”不代表原书章节顺序我按能力维度重新归了一下类。阶段项目主题核心关键词你要掌握的机制一第一个 Agent模型调用、补全生成Chat Completion、System Prompt一业务问答助手提示词实战结构化输出、角色设定二文档小助手对话与上下文多轮消息、短期记忆二知识库问答RAG 检索增强切分、向量化、召回三工具型 AgentFunction Calling工具定义、调用循环三工作任务规划流程编排Chain、State、条件分支四多智能体协作Multi-Agent规划者-执行者模式、结果汇聚这种归类方式的好处是你可以清楚地看到每个项目到底在训练哪种能力。把表格里每一项单独拎出来其实都能对应到生产环境中的一个具体模块客服机器人要对话管理企业知识库要 RAG自动化运营要工具调用复杂任务处理要流程编排。也就是说这本书 7 个项目学完你不是学了 7 个 Demo而是学了一组可以自由拼装的零件。2.2 第一段阶梯先彻底摸清模型的“脾气”前几个项目看起来最“简单”无非是把用户输入发给模型再把返回结果解析出来。但恰恰是这一步最容易暴露出很多人对大模型应用的错误理解。你可能会觉得一个 Chat Completion 接口有什么好学的真正上手就会发现模型的行为和你想象中并不一致你以为给了明确指令它就一定能听话实际上它经常丢信息、改格式、甚至自作主张地补充内容。这些行为不亲手试一遍是不会真正有体感的。所以这类项目看似基础实际上是在帮你建立对模型行为的基本信任感。第二个项目引入角色设定和格式约束比如要求模型扮演某个行业专家并且必须输出 JSON 结构。JSON 输出这件事看起来是小事实际上是 Agent 能够稳定运行的前提。因为在真正的业务流程里模型输出的内容不是给人看的是给代码解析的。你定义一个action字段、一个arguments字段然后代码里根据字段内容去执行不同函数这就是最朴素的“模型驱动执行”。我在做这个项目的时候踩过坑明明在 Prompt 里写了“只输出 JSON”模型偶尔还是会夹带解释文字解析器一跑就崩。后来学会了在解析前先做一次格式清洗再配置结构化输出相关的参数稳定性才有明显提升。2.3 中间项目知识库与工具是 Agent 真正“干活”的开始很多讲大模型应用的教程都会提 RAG但真正上手之后才发现RAG 的难点根本不在“检索”这两个字上而在文档处理和相关性判断。做知识库问答项目时你拿到一份几百页的 PDF第一步是决定怎么切分按固定长度切还是按标题层级切切成多少大小重叠多少个字符这些参数没有绝对标准要看你的文档类型和模型上下文长度去调。固定长度切分最省事但经常把完整段落拦腰截断导致语义信息丢失按结构切分效果好但对文档格式要求高PDF 转出来的文本经常是乱的需要先做清洗。切分之外第二个大坑是召回质量。向量检索召回的内容经常和问题“主题相似但不相关”这时候必须加一个重排环节或者至少提高召回数量然后让模型自己二次判断。我在复现这个项目时发现不要把全部文档都一股脑向量化先做一遍清洗去掉页眉页脚和重复段落检索质量会有肉眼可见的提升。这个项目做完之后你会理解为什么说 RAG 是“三分配置、七分数据”。工具调用项目又是另一个台阶。前面所有项目模型都在“说”到了这个项目模型开始“做”。实现方式很简单你提前定义几个函数比如查天气、查订单、发邮件把函数的名称、参数说明、含义告诉模型模型在需要的时候不直接回答问题而是返回一个调用请求你的代码收到请求后执行真实函数再把结果交给模型组织语言。这个循环是最核心的 Agent 机制之一。书里把这一步放在 RAG 之后很合理因为知识检索本质上就是 Agent 可以调用的一个特殊工具。2.4 后半程项目流程编排与多 Agent 协作单个 Agent 做得再聪明业务一复杂也会撑不住。工作任务规划项目会让你体验如何把一个大的目标拆成多个小的步骤每一步由一个动作完成动作间有依赖关系。比如“整理本周市场竞品动态并生成周报”这个任务可以拆成抓取资讯、筛选相关条目、汇总改写、排版输出四个子任务。在代码层面这就是一个状态机每一步执行完把结果写进当前状态下一步读取它继续处理。多智能体协作项目则更进一步。常见实现是“规划者-执行者”模式一个总控 Agent 负责理解用户意图生成任务清单多个子 Agent 各管一个领域比如一个负责检索、一个负责计算、一个负责撰写最后再由汇总 Agent 把结果合并成最终答案。做这个项目时最需要注意的是状态传递和职责边界。子 Agent 之间的中间结果如果一股脑塞进同一个上下文很快会超过模型窗口限制也会让模型不知道应该参考哪段信息。更合理的方式是给每个子 Agent 独立的输入输出槽位只把关键结果汇总传递给下一步。到这里你再回看那 7 个项目会发现它们其实是在反复训练同一套循环感知、规划、行动、观察、再规划。书里把这套循环拆到不同项目里去强化每一轮循环都比上一轮更复杂。这就是“7 个实战项目构建智能 Agent”这条路线最核心的内核。3. 核心技术的落地细节与参数选择3.1 模型选型先想清楚你要让模型做什么书里用的是当时的主流模型 API但今天你在复现这条路线时其实可以选择的范围更广。选模型不是越强越好而是要看项目需要。第一梯队的大模型比如 GPT 系、Claude 系以及国内可用的几个商用模型在复杂推理和工具调用上表现更稳适合后面几个项目轻量模型速度快、成本低适合前面练手。如果你想省成本可以把简单任务交给轻量模型只有复杂任务才让大模型处理这在生产环境里叫模型路由是非常实用的省钱手段。我在实操中有一个经验同一个 Agent 系统里不同环节可以用不同模型。比如信息提取用便宜的小模型因为输出格式简单最终的摘要生成用大模型因为需要更强的语言组织能力。这样能省不少 token而且不会明显掉质量。但要注意模型切换时 Prompt 要重新调一版因为不同模型对指令的服从度差异很大不能直接一套 Prompt 通吃。3.2 Prompt 工程在 Agent 中的真正作用定义边界而不是背“套路”网上聊 Prompt 经常把“角色扮演”“思维链”这类技巧放在最前面但如果你站在 Agent 的视角看Prompt 的第一使命是定义边界模型能做什么、不能做什么、输出格式是什么、遇到不确定信息时怎么办。这些边界如果定义不清楚后面代码写得再漂亮行为也会失控。举个例子在工具调用项目里我把 Agent 的 System Prompt 写得非常具体包括“你必须通过工具查询实时信息禁止凭记忆猜测”“如果工具返回空结果明确告知用户找不到不要编造”。这两句话让最终效果发生了质变。因为大模型本质上是一个“填空机器”你给它的约束越清晰它就越不容易在真实业务场景里闯祸。所以不要把 Prompt 当成咒语模板背要当成一份“岗位说明书”来写里面写清楚职责、权限、输出规范。另外Prompt 的版本管理也很重要。我给每个 Agent 的 Prompt 单独建一个文本文件文件名带版本号改动记录写在文件头注释里。这样当模型行为突然变化时你能快速回滚到上一个可用版本而不是靠记忆去猜。3.3 RAG 落地切分、向量化、召回、重排不是四步是四个坑RAG 的链路看起来很简单文档切分、向量化、存库、检索、拼接、生成。但每一步都有很多细节。先说切分优先按文档结构切比如标题、章节、段落如果某一段太长再继续往下切同时保留一个可配置的重叠区域让相邻块之间的语义有衔接。重叠字符数一般控制在块长度的 10% 到 20%太小了没效果太大了检索时容易返回大量重复内容。向量化时要注意 embedding 模型和主模型尽量保持同一生态跨生态不是不行只是检索效果需要重新验证。召回环节别急着只拿 top 3先多召回几段比如 top 10再用重排模型或规则把不相关的内容挤出去。你会发现同样的检索条件下重排前后答案质量差得不是一点半点。最后不要忘记给检索到的内容附带来源信息。项目里为了让答案“可追溯”我会让模型在回答末尾附上引用的文档标题和段落序号。这一步对生产环境尤其重要因为企业内部的 AI 应用信任往往比技术更重要。如果你的 Agent 给结论不告诉用户依据是什么用户很难真正用起来。3.4 Function Calling 与多 Agent 编排掌握“工具调用循环”就掌握了 Agent 的命门工具调用循环其实只有四步模型判断需要工具→生成工具调用请求→代码执行工具并拿到结果→把结果交回模型生成最终回复。代码写起来也不复杂核心是维护好一个消息列表把工具结果作为一个新的消息角色塞回去。用 Python 写大致是这个思路messages [{role: system, content: 你是一个智能助手可以通过工具获取订单信息。}] messages.append({role: user, content: 帮我查订单 10086 的状态}) resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolstools, ) msg resp.choices[0].message if msg.tool_calls: for call in msg.tool_calls: result execute_tool(call.function.name, call.function.arguments) messages.append({ role: tool, tool_call_id: call.id, content: str(result), }) resp client.chat.completions.create(modelgpt-4o-mini, messagesmessages) print(resp.choices[0].message.content)这里最容易被忽略的是“工具返回结果要尽量结构化”。你从数据库查到的订单状态不要拼成一大段自然语言再丢给模型直接返回 JSON让模型自己总结既省 token 又不容易出错。还有一点工具描述写得越仔细模型越不容易选错工具。每个工具的description都要说明它适用什么场景、参数格式是什么这比你后面写一堆异常处理都管用。多 Agent 编排则是在循环外面再包一层调度逻辑。可以用 LangGraph 这类框架来管理状态和边也可以自己写一个简单的工作流类。书里的做法很值得借鉴先用简单的方式实现一遍再去看框架的抽象这样你才能理解框架为什么要设计 State、Node、Edge 这些概念而不是跟着教程瞎填参数。4. 实操踩坑记录与生产化建议4.1 环境准备与依赖管理版本不对等于白干照着路线复现项目时最容易出问题的就是版本。LangChain 这个框架改名和接口变动非常频繁一段教程里的代码过两个月就可能因为 API 变化跑不起来了。我的建议是先用一个 Python 虚拟环境锁定依赖版本跟着教程跑通后再升级。不要一上来就装最新版很多时间就浪费在这种地方。项目里还会用到 OpenAI SDK 这类依赖记得把 API Key 放到环境变量里不要硬编码进代码。另外建议自己封装一个get_client()函数统一管理模型名、base_url、超时时间。这样后面换模型、换供应商你只需要改一个地方不用满项目翻。这看起来是个小习惯但在项目数量变多之后能省掉大量重复劳动。4.2 并发和长任务处理Agent 变“贵”之后要面对的硬问题做 Demo 的时候一次请求几分钟也就忍了。但一旦 Agent 要接入真实业务并发和时长就会变成大问题。工具调用循环里一次任务可能包含好几次模型请求如果每个子任务平均 3 秒一个 10 步的任务就要 30 秒用户那边早就不耐烦了。很多人问“AI Agent 怎么扛并发”本质上就是在问这个问题。我自己的处理思路有三条。一是能并行的子任务不要串行比如多 Agent 协作里的几个检索任务可以同时发出去最后再汇总。二是给中间过程加流式输出把“正在调用工具”“正在检索文档”这些过程实时推给前端用户至少知道系统没死。三是给每个 Agent 步骤设置超时和重试次数避免一个工具接口卡住整个任务卡死。这几条听起来都很朴素但在真实系统里能救命。4.3 从 Demo 到可上线还差日志、评估、成本控制三件事很多人把 7 个项目做完觉得终于可以上线了。但 Demo 和生产之间还有一段不小的距离。第一件事是日志。模型调用的输入输出、工具调用参数、耗时、token 消耗这些都要记录。有了日志你才能排查问题才能知道用户遇到的 bad case 是哪一步出的错。第二件事是评估。给 Agent 准备一批测试用例每次改完 Prompt 或代码都跑一遍对比一下回答质量有没有下降。没有评估你的优化就是盲人摸象。第三件事是成本控制。给每个用户请求设置 token 上限给模型路由设置价格阈值这些都是很基础但必须做的活儿。这些内容书里未必每一页都讲到了但它们恰恰是“实战项目”走向“生产项目”的必经之路。学完 7 个项目之后我建议你立刻挑一个真实小场景再用完整工程标准做一遍收益会非常大。5. 常见问题速查与独家心得5.1 高频问题排查表现象可能原因处理方式模型不调用工具直接回答工具描述不清晰 / 模型版本不支持检查 tools 参数格式、升级到支持 Function Calling 的模型工具返回了数据但模型回答瞎编工具结果未正确塞回 messages确认 tool_call_id 和 role 设置正确RAG 检索结果不相关切分粒度不合理 / 向量模型不匹配按结构切分增加重排环节JSON 输出偶尔解析失败模型夹带解释文字 / 转义问题使用结构化输出参数解析前做清洗多 Agent 卡死或互相覆盖状态传递混乱 / 上下文太长拆分状态槽位只传必要的中转信息API 调用频繁超时并发过高 / 网络不稳定加队列、加重试、设置合理超时这张表里的每一种情况我都在实际项目中遇到过。排查的时候记住一个原则先看数据再看代码最后怀疑模型。很多时候你以为模型在胡说其实是工具返回的数据本身有问题你以为检索不准其实是文档切分就没切对。5.2 几个屡试不爽的实践心得最后分享几个我自己的小习惯不算什么高深技巧但真的很省事。第一个把所有“角色说明”集中放在 System Prompt 里把“当前任务的具体要求”放在 User Prompt 里不要混在一起。这样你调试的时候能一眼看清模型的指令到底是怎么组成的换场景也方便。第二个工具结果返回给模型之前尽量裁剪成短文本。比如查库返回 200 行数据不要全量塞给模型先聚合、取 top N、转成摘要再丢给模型。否则上下文膨胀之后后面的任务质量会明显下降。第三个给 Agent 的每一步留一个“逃逸口”。所谓逃逸口就是当模型发现条件不满足或结果异常时能够明确回退到用户确认而不是硬着头皮往下走。我在做多 Agent 项目时给规划 Agent 加了一条规则如果子任务数量超过 5 个先让用户确认再执行。这种设计能避免不少失控场景。第四个书里的项目做完之后强烈建议自己重写一遍不看书、不看代码。因为照着敲代码和独立写出来是两种完全不同的体验重写的过程才是真正把知识变成能力的过程。说实话我最初拿到这本书的标题时也以为又是一本“教你调 API”的教程。真正顺着这条路做下来才发现7 个项目不是 7 个孤立 Demo而是一条完整的、从模型能力到工程能力的进阶路径。尤其是工具调用和多 Agent 协作那部分让我在后来给实际业务设计智能体时少走了不少弯路。如果你正准备入坑大模型应用开发我的个人建议是不要跳着做项目前几个看着简单但那些对模型行为的观察才是后面所有设计的依据。延伸一下说这本书只是一个起点。Agent 这个领域还在快速变化比如更强的上下文模型、更成熟的 Agent 协议、更多的端侧落地场景都在不断刷新我们构建应用的方式。但不管工具怎么变“把大模型变成能执行任务的系统”这条主线不会变。把这 7 个实战项目吃透你会发现自己面对新框架、新平台时不再是一张白纸而是能一眼看穿它背后那套“感知—规划—行动—观察”的循环。到那时候你手里握的就不再是一堆零散的 API而是一套可以持续复用的构建方法论。