AI Agent 从零搭建实战：架构、成本控制与故障排查

1. 先搞清楚AI Agent 到底是个什么东西1.1 从“会聊天的模型”到“会干活的系统”很多人第一次接触 AI Agent 这个词脑子里浮现的还是那个对话框——你问一句它答一句聊得挺热闹但关掉窗口之后什么也没留下。如果只是这样那它跟一个普通的聊天机器人没有本质区别。我刚开始也这么以为直到我在一个自动化任务上连续烧掉了几百块的调用费用才真正理解 Agent 和 Chatbot 之间的鸿沟在哪里。用一句话概括AI Agent 是一个能自己拆解目标、调用工具、观察结果、调整策略直到把任务真正做完的系统。注意这里的几个关键词——“自己拆解”“调用工具”“观察结果”“调整策略”。普通对话模型只负责“生成一段看起来合理的文本”而 Agent 要对“任务是否完成”负责。这个差别听起来不大但落到工程实现上是两套完全不同的架构。举个生活化的类比。普通模型像一个知识渊博但只会动嘴的顾问你问他“怎么订机票”他能给你讲一套流程而 Agent 像一个真正的助理你说“帮我订下周三去上海的机票”他会去查你的日程、打开订票渠道、比价、下单、把确认信息发给你中间遇到航班取消还会自己改签。前者输出的是信息后者交付的是结果。1.2 为什么这一年它突然成了热词Agent 这个概念其实不新早几年就有学术论文在讨论。但真正让它从论文走进工程实践靠的是三件事凑齐了模型本身的推理能力上来了工具调用也就是让模型能操作外部函数、接口、文件的协议标准化了以及上下文窗口大到能塞进足够多的中间状态。这三者缺一个Agent 都跑不起来。我自己的体感是2024 年之后身边做开发的朋友聊的不再是“怎么调 prompt”而是“怎么设计 Agent 的循环”“怎么防止它陷入死循环”“token 怎么烧得这么猛”。话题的转变本身就说明大家已经从“玩模型”进入到“用模型干活”的阶段了。而一旦进入干活阶段成本、稳定性、可观测性这些工程问题就全冒出来了——这也是我这一年烧掉几千块换来的最真实的教训。1.3 这篇文章适合谁看如果你是完全没接触过 Agent 的小白这篇能帮你建立一套不跑偏的认知框架知道它是什么、能干什么、坑在哪。如果你已经在动手搭那里面关于架构选型、token 控制、常见故障排查的部分应该能帮你少走一些我走过的弯路。我不打算把它写成一篇学术综述而是当成一次项目复盘——把我踩过的坑、算过的账、试过的方案原原本本摊开讲。2. 拆开看一个 Agent 的骨架长什么样2.1 主流架构的四个核心部件不管市面上把 Agent 讲得多花哨落到代码层面一个能跑起来的 Agent 基本都逃不出这四个部件规划器Planner、记忆Memory、工具集Tools、执行循环Loop。我见过不少号称“全新架构”的方案拆开一看还是这四样只是换了个包装。规划器负责把用户那句模糊的指令拆成可执行的步骤。比如“帮我整理这周的行业新闻并发到群里”规划器要把它拆成“抓取新闻源→筛选去重→摘要→格式化→发送”。记忆负责存住中间状态和历史否则 Agent 每走一步就忘了前面干了什么。工具集是它真正能伸出去的手搜索、读写文件、调接口、执行代码都算。执行循环则是那个“做一步、看一眼、再决定下一步”的引擎是整个 Agent 的心跳。我一开始图省事只写了规划器和工具没做记忆结果 Agent 做到第三步就忘了第一步的目标反复绕圈。后来补上记忆模块token 消耗反而降了——因为它不用每次重新推理上下文。这个反直觉的结论值得记一下合理的记忆设计是省钱的不是费钱的。2.2 规划、记忆、工具、循环各自的分工规划器最容易被低估。很多人以为把任务丢给模型让它“自己想办法”就行实测下来没有约束的规划器会生成又长又啰嗦的步骤中间还夹着一堆无效动作。我的做法是给它一个步骤上限比如最多 8 步超过就强制收敛逼它做取舍。记忆分短期和长期。短期记忆就是当前任务的上下文通常直接塞进 prompt长期记忆需要落到外部存储比如向量库或者简单的键值对。这里有个经验不是所有东西都值得存长期记忆。我早期把所有中间结果都往向量库里塞结果检索出来的全是噪音反而干扰判断。后来只存“结论性”的信息比如“用户偏好”“已完成的关键节点”效果立刻好转。工具集的设计原则是“少而精”。每多一个工具模型的选择空间就大一分选错的概率也高一分。我见过一个 Agent 挂了二十几个工具结果它在“用搜索还是用数据库”之间反复横跳光纠结就烧掉一大截 token。后来砍到五个核心工具准确率明显上升。执行循环是烧钱的重灾区。循环次数、单步超时、失败重试策略这三个参数直接决定你的账单。我后面会专门用一节讲怎么算这笔账。2.3 为什么“循环”才是 Agent 的灵魂如果只能保留一个部件我会选执行循环。因为规划可以简化、记忆可以外挂、工具可以硬编码但“做一步看一步”这个机制是 Agent 区别于一次性生成的根本。它让系统具备了纠错能力——第一步做错了第二步能发现并补救。但这个能力是有代价的。每一次循环都意味着一次完整的模型调用token 消耗是线性叠加的。我做过一个统计一个平均 6 步完成的任务如果每步都带完整上下文总 token 消耗是单次问答的 8 到 12 倍。这就是为什么很多人第一次跑 Agent看到账单会吓一跳。所以循环设计的核心矛盾是给它足够的自主性去纠错又要用约束防止它无限绕圈。我的解法是设置“硬预算”——每个任务给一个 token 上限快超了就强制它输出当前最优结果并结束。这个机制救过我好几次尤其是在处理那些边界模糊、模型容易钻牛角尖的任务时。3. 动手之前搭建 Agent 的技术选型3.1 语言和框架怎么选热词里出现了“基于 Rust 语言 AI Agent”我专门花时间试过。Rust 的优势在于性能和内存安全如果你的 Agent 要处理高并发、低延迟的场景比如实时响应大量请求Rust 确实有吸引力。但代价是生态还在早期很多现成的模型 SDK、向量库客户端不如 Python 成熟开发效率会打折扣。我的建议是分场景做原型验证、快速迭代用 Python生态最全遇到问题搜一下基本都有答案做生产部署、对性能和资源占用敏感可以考虑 Rust 或者 Go但要接受前期踩坑成本更高。我自己主力还是 PythonRust 只在一个对延迟要求极高的子模块上用了。框架层面市面上的选择很多但我不建议一上来就上重型框架。先用最朴素的方式——一个 while 循环加几个函数调用——把最小可用的 Agent 跑通理解每一步在干什么再去考虑引入框架。我见过太多人直接套框架结果出了问题完全不知道从哪查因为框架把细节全藏起来了。3.2 模型选型的三个维度选模型不能只看“哪个最强”要看三个维度推理能力、工具调用稳定性、单位成本。推理能力决定它能不能正确拆解任务工具调用稳定性决定它会不会把参数传错单位成本直接决定你一个月烧多少钱。我的实测经验是复杂规划用强模型简单执行用便宜模型做“模型路由”。比如任务拆解这一步用能力最强的具体的信息提取、格式转换用轻量模型。这样整体成本能降一半以上效果几乎不受影响。这个思路叫“大小模型协同”是我这一年最值钱的优化之一。还有一个容易被忽略的点工具调用的稳定性比推理能力更影响体验。一个推理很强但老是传错参数的模型用起来比一个推理一般但参数传得准的模型更让人抓狂。选型时一定要拿真实任务压测别只看榜单分数。3.3 部署方式本地还是云端本地部署的好处是数据不出门、调试方便、没有网络延迟坏处是要自己维护环境、模型能力受限于本地硬件。云端部署省心、能用到最新最强的模型但按量计费跑起来心里没底。我最后采用的是混合方案开发和调试阶段本地跑小模型快速验证逻辑正式跑任务时切到云端强模型保证效果。这样既控制了调试成本又保证了生产质量。如果你刚开始我建议先用云端 API 把流程跑通别一上来就折腾本地部署那会消耗掉你大部分精力却学不到 Agent 的核心。4. 真金白银token 成本到底怎么算4.1 token 是什么为什么它等于钱token 是模型处理文本的最小单位你可以粗略理解成“字或词的一部分”。中文里一个汉字大约对应一到两个 token英文一个单词大约一个多 token。你发给模型的每一段文字、模型生成的每一个字都按 token 计费。输入和输出的单价通常不一样输出往往更贵。Agent 烧钱就烧在这里它每循环一次都要把“任务目标历史步骤工具返回结果当前指令”打包发给模型这个包会随着循环次数越来越大。第一步可能只花几百 token到第六步可能就上万了。这就是为什么单次问答很便宜Agent 任务却可能花掉几十块。4.2 一次典型任务的成本拆解我拿一个真实任务算过账让 Agent 抓取五个新闻源、去重、生成摘要、整理成固定格式。整个过程跑了 7 步总输入 token 约 4.2 万输出约 6 千。按当时用的模型单价折算单次任务成本大约一块多。听起来不多但如果这个任务每天跑十次一个月就是三百多块。要是任务更复杂、循环更多轻松上千。这里的关键洞察是Agent 的成本不是线性的是随循环次数加速增长的因为上下文在累积。控制成本的核心就是控制“每步带多少历史”和“总共走多少步”。4.3 我踩过的三个烧钱大坑第一个坑是无上限重试。有一次工具调用失败Agent 自己决定重试结果因为参数一直错它重试了十几次每次都是完整上下文那一个任务烧掉了我平时一周的量。后来我加了硬性重试上限最多两次超了就报错退出。第二个坑是把大文件整个塞进上下文。我让它处理一个几万字的文档直接把全文塞进去光输入就爆了。正确做法是先做检索或分块只把相关片段喂给它。第三个坑是没有缓存。同样的子任务反复执行每次都重新调模型。后来我加了一层结果缓存命中就直接返回成本立降三成。这三个坑每一个都是用真金白银换来的。5. 从零搭一个能跑的 Agent完整实操5.1 环境准备与最小依赖先把环境搭起来。我用的是 Python核心依赖就几个模型 SDK、一个 HTTP 请求库、一个简单的存储。不需要一上来就装一堆重型库。下面是最小化的依赖清单pip install openai requests如果你要用向量记忆再加一个向量库客户端如果只是验证逻辑先用内存字典存记忆就够了。我的原则是能用标准库解决的绝不引入第三方依赖因为每多一个依赖就多一个出问题的地方。5.2 定义工具函数与调用协议工具就是普通的 Python 函数关键是要把它的用途、参数、返回值描述清楚让模型能看懂。我一般用 JSON Schema 来描述工具这样模型调用时参数格式最稳定。下面是一个搜索工具的简化示例def search_news(keyword: str, limit: int 5) - list: 根据关键词搜索新闻返回标题和链接列表。 keyword: 搜索关键词 limit: 返回条数默认5 # 实际实现略返回结构化列表 return results描述里的每个字都影响模型能不能正确调用。我踩过的坑是描述写得太模糊模型传参时把“条数”传成了字符串导致报错。后来我把类型和含义写死问题就没了。5.3 编写主循环与终止条件主循环是整个 Agent 的心脏。核心逻辑就是把当前状态发给模型模型决定下一步动作执行动作把结果写回状态判断是否结束。终止条件必须明确否则它会一直跑下去。max_steps 8 for step in range(max_steps): action model_decide(state) if action.type finish: break result execute(action) state.append(result) if state.token_used budget: break这里max_steps和budget是两个保命参数。我建议新手把max_steps设小一点比如 5先跑通再说。等逻辑稳定了再逐步放开。5.4 记忆模块的落地方式最简单的记忆就是一个列表把每一步的结果 append 进去。但列表会越来越长token 会爆。所以要做“记忆压缩”定期把历史步骤总结成一句话替换掉原始记录。我用的策略是每三步压缩一次把“做了什么、得到什么结论”提炼出来丢弃中间过程。长期记忆我用的是一张简单的表存“用户偏好”“常用配置”这类跨任务的信息。检索时只取最相关的几条不搞全量召回。这个设计让我的 Agent 在保持“记得住”的同时token 消耗控制在了可接受范围。6. 让它真正干活几个落地场景6.1 内容自动化从抓取到发布这是我跑得最久的一个场景。Agent 每天定时抓取指定来源的内容去重、摘要、按模板排版最后生成待发布的内容草稿。整个流程里模型只负责“摘要”和“排版判断”这两个需要理解力的环节抓取和去重都用确定性代码完成。这个分工很重要能用代码确定性完成的绝不交给模型。模型只做它擅长的模糊判断这样既省钱又稳定。我早期试图让模型包办所有环节结果它连去重都做得时好时坏还费钱。6.2 开发辅助用 Agent 写 Django 接口热词里有“用 AI Agent 开发 Django”我试过。让 Agent 根据需求描述生成模型、视图、路由确实能省不少重复劳动。但要注意它生成的代码必须人工审查尤其是涉及数据库操作和权限的部分。我的用法是让它生成骨架我来填业务逻辑和做安全校验。实测下来Agent 在“生成样板代码”上效率很高在“理解复杂业务规则”上还差得远。把它当成一个手速极快的初级开发而不是架构师心态就对了。6.3 消息自动化的边界与风险热词里提到“让小红书自动发消息”这类场景。这里我必须提醒任何涉及自动向他人发送消息的操作都要极其谨慎。平台通常有严格的风控规则自动化操作很容易触发限制甚至导致账号受影响。而且从合规角度未经对方同意批量发送消息本身就有问题。我的建议是把 Agent 用在“辅助自己”的场景上比如整理素材、生成草稿、提醒自己而不是代替自己去和他人交互。技术能力是一回事用在哪里是另一回事这条线要守住。7. 上线之后常见故障与排查7.1 死循环与无限重试这是最常见的故障。表现是 Agent 反复执行同一个动作或者在不同动作间来回跳。根因通常是目标描述模糊、工具返回结果不符合预期、或者没有终止条件。排查思路先看日志里最近几步的动作序列如果发现重复模式基本就是死循环。解法是加“动作去重”——如果连续两步动作相同强制中断并让模型重新规划。我还会在 prompt 里明确写“不要重复已经失败的动作”这句话能挡掉不少问题。7.2 工具调用参数错误表现是工具报错或者返回了明显不对的结果。根因多半是工具描述不清或者模型对参数含义理解有偏差。排查时把模型实际传的参数打出来和预期对比一眼就能看出问题。解法有两个一是把工具描述写得更死明确类型和取值范围二是在工具函数里加参数校验传错就直接返回清晰的错误信息让模型知道错在哪。我后来养成了习惯每个工具函数开头都做一次参数检查省了大量排查时间。7.3 上下文超限与截断表现是模型突然“失忆”忘了前面的步骤或者报上下文长度错误。根因是历史累积太多。解法就是前面说的记忆压缩定期把长历史总结成短结论。另外工具返回的大段内容要先截断或摘要再塞进上下文别原样丢进去。7.4 排查速查表故障现象可能原因排查动作解决方向反复执行同一动作目标模糊、无终止条件看动作序列是否重复加动作去重、明确终止条件工具报参数错描述不清、类型不符打印实际传参细化描述、加参数校验突然失忆上下文超限看 token 用量记忆压缩、结果截断成本异常高循环过多、无缓存统计每步 token设预算、加缓存、模型路由任务做一半停预算耗尽、超时看终止原因调整预算、拆分任务这张表是我从几十次故障里总结出来的基本覆盖了八成以上的问题。遇到新故障先往这几类里套能省不少时间。8. 学习路线从入门到能自己搭8.1 第一阶段理解概念跑通最小示例别急着看复杂框架。先找一个最简单的例子比如“让模型调用一个计算器函数”把“模型决定调用工具→执行→返回结果”这个闭环跑通。这一步的目的是建立直觉知道 Agent 到底在干什么。我当初就是卡在这一步太久总想一步到位搭个完整的结果反而绕了远路。8.2 第二阶段动手实现核心循环自己从零写一个主循环不要用框架。哪怕只有几十行代码只要它能完成一个两步任务你就理解了 Agent 的本质。这个阶段重点练三件事工具定义、状态管理、终止条件。这三样搞明白了后面用什么框架都是锦上添花。8.3 第三阶段优化成本与稳定性等能跑通了再开始抠成本和稳定性。加缓存、做模型路由、设预算、加日志。这个阶段的提升最明显也最能体现工程能力。我见过很多人停在第二阶段就满足了结果一上生产就被账单和故障打回来。8.4 第四阶段场景落地与持续迭代最后才是找真实场景落地。从一个小而明确的任务开始比如“每天整理一份行业简报”跑稳了再扩展。别一上来就搞大而全的系统那几乎必然失败。我的第一个落地场景就是每天生成一份简报跑了三个月没出大问题才敢往更复杂的方向走。9. 一些没人告诉你但很重要的经验9.1 日志比什么都重要Agent 出问题时你唯一能依靠的就是日志。每一步的输入、输出、token 用量、耗时都要记下来。我早期没做日志出了问题只能靠猜效率极低。后来加了结构化日志排查时间从小时级降到分钟级。在 Agent 项目里可观测性不是可选项是必需品。9.2 别追求全自动留个人工确认点全自动听起来很美但风险也大。我的做法是在关键节点留人工确认比如“发送前”“删除前”“付款前”。这样既享受了自动化的效率又守住了安全底线。实测下来加了确认点之后我对系统的信任度反而更高敢让它处理更重要的任务。9.3 小步快跑别憋大招Agent 项目最忌讳憋一个大而全的设计然后一次性实现。因为它的行为有很强的涌现性很多问题只有跑起来才会暴露。我的节奏是每周加一个小能力跑一周看效果稳定了再加下一个。这样风险可控学习曲线也平缓。9.4 关于“主流架构”的冷静看法热词里“AI Agent 主流架构”被反复提及但我想说架构是长出来的不是选出来的。你去看那些跑得稳的 Agent架构都是在解决具体问题的过程中逐步演化出来的不是一开始就照着某个“标准架构”搭的。先跑通再优化最后回头看你会发现自己的架构自然就成型了。9.5 白皮书可以看但别照搬阿里云出过 AI Agent 相关的白皮书内容有参考价值尤其是工程实践部分。但白皮书面向的是通用场景你的具体业务有它的特殊性。我的建议是把它当参考书遇到具体问题时去翻对应章节而不是当成施工图纸照搬。照搬的结果往往是水土不服。10. 最后聊几句实在的这一年下来我最大的体会是AI Agent 不是一个“装上就变强”的魔法它是一个需要你持续投入、持续调试、持续算账的工程系统。它确实能帮你省下大量重复劳动但前提是你愿意花时间去理解它的脾气接受它会犯错并且为它设计好边界。烧掉的那几千块与其说是成本不如说是学费。每一笔异常账单背后都对应着一个我没考虑到的设计缺陷。把这些缺陷一个个补上之后系统才慢慢变得可靠。如果你正准备入这个坑我的建议是从小处着手把账算清楚把日志做扎实把安全线守住。剩下的交给时间和迭代。这个领域变化很快今天好用的方案明天可能就被更好的替代。但底层的那些东西——循环、记忆、工具、成本控制——短期内不会变。把这些吃透你换什么框架、什么模型都能快速上手。