AI Agent 这个词这两年从论文里的概念一路杀进了日常开发，我身边不少朋友从最初"这不就是个套壳 GPT 的机器人"的怀疑，到现在开始认真琢磨怎么把它塞进自己的业务流里。我自己也是从踩坑开始的——最早以为 Agent 就是给大模型加个循环调用工具，结果真上手才发现，光一个"什么时候该停"的判断就能把整个流程搞崩。这篇不聊虚的架构图，就聊聊我在实际搭建、调试、部署 AI Agent 过程中攒下的一些小经验，包括选型思路、Token 消耗的坑、主流架构的取舍、以及怎么让它真正跑起来而不是停在 Demo 阶段。不管你是刚听说 AI Agent 想入门，还是已经写过几版想优化，这些从实战里抠出来的细节应该都能对上你的某些困惑。

1. 先搞清楚 AI Agent 到底比普通调用多了什么

1.1 从"一问一答"到"自己决定下一步"

大多数人第一次接触大模型，用的都是最朴素的模式：给一个 prompt，拿一个回复，结束。这种模式我管它叫"单次问答"，它的特点是控制流完全在你手里——你决定问什么、问几次、拿到结果后干什么。而 AI Agent 的核心变化在于，控制流的一部分交给了模型自己。

举个具体的例子。你要做一个"帮我把这份周报整理成邮件"的功能。单次问答的做法是：你把周报内容拼进 prompt，让模型输出邮件正文，你拿到后自己复制粘贴。而 Agent 的做法是：模型先判断"我需要先读取周报文件"，然后调用一个读文件的工具；读完发现格式乱，它决定"先做一次结构化整理"；整理完再判断"现在可以生成邮件了"，调用写邮件的工具；最后它自己判断"任务完成"，停下来。

这个"自己判断下一步做什么、什么时候停"的能力，就是 Agent 和普通调用的本质区别。用一句话概括：普通调用是你写好的流水线，Agent 是模型自己拿着地图找路。理解这一点非常关键，因为后面所有的坑——Token 爆炸、死循环、工具乱调——全都是从这个"自主决策"里长出来的。

1.2 一个 Agent 最少需要哪几个零件

我拆过不少开源实现，也自己从零写过，一个能跑的最小 Agent 其实就四样东西：

• 一个能调用工具的大模型：这是大脑，负责推理和决策。它必须支持 function calling 或者类似的工具调用协议，否则你只能靠解析文本，稳定性会差很多。
• 一组工具（Tools）：这是手脚，是 Agent 和外部世界交互的接口。读文件、查数据库、发请求、算数，都算工具。
• 一段系统提示词（System Prompt）：这是行为准则，告诉它"你是谁、你能干什么、你该怎么干、什么时候该停"。
• 一个循环控制器：这是骨架，负责把"模型输出→执行工具→把结果喂回模型→再输出"这个循环转起来，同时管住最大轮数、超时、异常。

很多人一上来就去研究什么多 Agent 协作、什么记忆系统，结果连最基础的四件套都没调明白。我的建议是：先用这四样东西跑通一个"能查天气、能算数、能自己决定先查还是先算"的最小 Agent，把循环跑顺了，再去加花活。基础不牢，后面加的东西越多越乱。

1.3 为什么"什么时候停"是最难的部分

我踩过最深的坑就在这。早期我写的 Agent，系统提示词里只写了"你要帮用户完成任务"，没写"完成后要输出什么信号"。结果模型干完活之后不知道该干嘛，要么继续瞎调工具，要么开始自言自语，要么把已经做过的事再做一遍。有一次我让它整理一份数据，它把同一个文件读了七遍，Token 直接烧掉一大半。

后来我总结出一个原则：Agent 的停止条件必须显式、明确、可被模型识别。常见做法有两种。一种是约定一个特殊的终止工具，比如finish_task，模型认为任务完成时必须调用它，控制器收到这个调用就结束循环。另一种是在系统提示词里明确要求"当你认为任务已完成时，直接输出最终答案，不要再调用任何工具"，然后控制器检测到"这一轮没有工具调用"就停止。

两种都能用，但我更推荐第一种，因为工具调用是结构化的，比靠自然语言判断"它是不是说完了"要可靠得多。自然语言判断经常误判，模型说一句"好的，我完成了"你可能以为它停了，其实它下一轮还想继续。

2. Token 消耗：Agent 最容易被低估的成本黑洞

2.1 为什么 Agent 的 Token 消耗是普通调用的好几倍

这是我最想提醒新手的一点。普通调用一次问答，Token 消耗基本等于"输入 + 输出"。但 Agent 不一样，它是多轮循环，而且每一轮都要把完整的历史对话重新发给模型。

假设你的系统提示词加工具定义占了 2000 Token，用户任务 500 Token。第一轮发给模型是 2500 Token。模型决定调一个工具，工具返回结果 800 Token，第二轮你发过去的就是 2500 + 模型上轮输出 + 800，假设 3500 Token。第三轮又累加……如果这个任务跑了 8 轮，你实际消耗的输入 Token 是每一轮累加的总和，很容易就上万。

我做过一个粗略的对比：同样一个"整理数据并生成报告"的任务，用单次问答分三步手动做，大概消耗 3000 Token；用 Agent 自动跑，跑了 6 轮，消耗了 18000 Token。成本差了 6 倍，但省下的是我手动串联的时间。所以 Agent 不是"更省钱的方案"，它是"用钱换自动化"的方案，你得先想清楚这笔账划不划算。

2.2 控制 Token 的几个实操手段

既然 Token 是黑洞，那就得想办法堵。我常用的手段有这么几个，按性价比排序：

第一，精简系统提示词和工具定义。工具描述别写小作文，一句话说清楚"这个工具干什么、参数是什么"就够了。我见过有人给每个工具写三段描述，光工具定义就占了 3000 Token，纯属浪费。工具数量也要控制，能合并的合并，别搞二十个工具让模型挑花眼。

第二，给历史对话做截断或摘要。循环跑到后面，早期那些已经没用的工具返回结果可以丢掉。简单做法是只保留最近 N 轮，复杂做法是让模型对历史做一次摘要压缩。我一般用简单截断，因为摘要本身也要花 Token，而且可能丢信息。

第三，设置最大轮数硬上限。这是保命措施。不管任务多复杂，超过比如 15 轮就强制停止并返回当前结果。没有这个上限，一个死循环能把你账单跑爆。

第四，能不用 Agent 就不用。如果一个任务用固定流程三步就能搞定，那就写死流程，别上 Agent。Agent 的价值在于"路径不确定、需要模型临场判断"，如果路径是确定的，用 Agent 纯属杀鸡用牛刀，还费钱。

2.3 一个真实的 Token 账单复盘

说个我自己的真实案例。我做过一个"自动整理会议纪要并提取待办"的 Agent，最初版本跑一次平均消耗 12000 Token。我做了三件事优化：把工具从 8 个砍到 4 个、把系统提示词从 1500 字压到 400 字、加了历史截断只保留最近 3 轮。优化后平均消耗降到 4500 Token，效果几乎没变。

这里的关键认知是：Agent 的 Token 消耗里，很大一部分是"重复发送的固定内容"——系统提示词、工具定义、早期历史。这些内容每一轮都在重复计费。所以优化 Token 的第一优先级永远是"把固定内容压到最小"，而不是去抠模型输出的那点字数。

3. 主流架构怎么选：别一上来就上多 Agent

3.1 单 Agent 加工具：80% 场景的最优解

现在网上讲 AI Agent 架构，动不动就是多 Agent 协作、规划者加执行者、反思循环，看着很高级。但我实际做下来，80% 的需求用"单 Agent + 一组工具"就能解决，而且更稳、更便宜、更好调试。

单 Agent 架构的逻辑很简单：一个模型，拿着所有工具，自己决定调哪个、调几次、什么时候停。它的优势在于没有通信开销——多 Agent 之间要互相传消息，每次传递都是 Token 消耗，而且信息在传递中容易失真。单 Agent 所有上下文都在一个脑子里，决策连贯。

什么时候单 Agent 不够用？当任务复杂到"一个模型同时要管太多事，提示词写不下、工具太多挑不过来"的时候。比如你要做一个"既要写代码、又要审查代码、又要跑测试、又要写文档"的系统，塞进一个 Agent 会让它的系统提示词变成天书。这时候才考虑拆分。

3.2 多 Agent 协作的真实代价

我试过多 Agent，说实话，调试难度是指数级上升的。单 Agent 出问题，你看一遍完整对话历史就知道哪步错了。多 Agent 出问题，你得在几个 Agent 的对话之间来回跳，还得搞清楚"是 A 没传对信息，还是 B 理解错了，还是它们俩在互相甩锅"。

多 Agent 的典型模式有几种：一种是规划者 + 执行者，一个 Agent 负责拆任务，另一个负责干活；一种是流水线，每个 Agent 负责一个环节，像工厂流水线一样传递；还有一种是辩论式，多个 Agent 各抒己见然后投票。这些模式在特定场景下确实有效，但代价是：

• Token 消耗翻倍甚至更多，因为每个 Agent 都有自己的系统提示词和上下文。
• 延迟增加，Agent 之间来回通信需要时间。
• 错误定位困难，一个环节出错可能污染整条链。
• 状态管理复杂，你得设计好它们之间怎么共享信息。

我的建议是：先用单 Agent 做，做到真的撑不住了再拆。拆的时候也要克制，两个 Agent 能解决就别搞三个。

3.3 架构选型的一张对照表

为了让你更直观地判断，我整理了一张对照表，把常见架构和适用场景对应起来：

这张表的核心信息是：架构复杂度应该由任务复杂度决定，而不是由技术炫技决定。我见过太多项目，明明一个固定流程就能搞定，非要上多 Agent，最后维护成本高得离谱。

4. 工具设计：Agent 好不好用，一半看工具

4.1 工具描述是给模型看的，不是给人看的

这是很多人的误区。写工具描述的时候，我们习惯性地写得像给人看的 API 文档，什么"该函数用于……返回一个包含……的对象"。但工具描述的真正读者是模型，它需要的是"什么时候该用这个工具、参数填什么、会得到什么"。

我优化工具描述的经验是：用祈使句，说清楚触发条件。比如不要写"查询用户信息的工具"，而要写"当需要获取某个用户的姓名、邮箱、注册时间时调用此工具，参数 user_id 为用户唯一标识"。前者模型不知道什么时候该用，后者模型一看就知道场景。

参数描述也一样。每个参数都要说清楚"这是什么、什么格式、有没有默认值"。模型对格式很敏感，你不说清楚它可能传个字符串进去，而你的工具期望的是数字，直接报错。

4.2 工具粒度：太粗和太细都是坑

工具粒度是个需要反复调的东西。太粗，比如一个工具叫do_everything，模型不知道该传什么参数，也不知道调用后会怎样，基本没法用。太细，比如把"读文件"拆成"打开文件、读取内容、关闭文件"三个工具，模型得连着调三次，既费 Token 又容易出错。

我的经验法则是：一个工具对应一个完整的、有业务意义的动作。"读取文件内容"是一个好粒度，"发送一封邮件"是一个好粒度，"查询订单状态"是一个好粒度。判断标准是：这个动作是不是一个"人会说出口的完整请求"。如果人会说"帮我读一下这个文件"，那它就是一个工具；如果人不会单独说"帮我打开文件句柄"，那它就不该是独立工具。

4.3 工具报错怎么返回，直接影响 Agent 能不能自救

工具执行失败是常态，网络超时、参数错误、权限不足都会发生。关键在于你怎么把错误信息返回给模型。如果你只返回一个Error: 500，模型完全不知道发生了什么，只能瞎猜或者放弃。如果你返回读取文件失败：文件 /data/report.csv 不存在，请检查路径是否正确，模型就有机会自己修正——它可能会换个路径重试，或者先列一下目录看看有什么文件。

我踩过的坑是：早期工具报错直接抛异常，整个 Agent 崩了。后来改成捕获所有异常，把错误信息作为工具返回结果喂回模型，让模型自己决定怎么办。这个改动让 Agent 的"自救率"提升了很多。当然，要设置重试上限，不然模型可能对着一个永远失败的调用死磕。

提示：工具返回结果尽量结构化，比如统一用 JSON，字段名清晰。模型对结构化数据的理解比一大段自然语言要准。

5. 提示词工程在 Agent 里的特殊玩法

5.1 系统提示词要写"行为准则"而不是"任务描述"

普通调用里，提示词主要描述任务。但 Agent 的系统提示词，核心是描述行为准则——你希望它怎么思考、怎么决策、怎么处理异常。任务描述反而是次要的，因为任务是用户每轮传进来的。

我写 Agent 系统提示词的固定结构大概是这样：

• 角色定义：你是谁，你的职责边界在哪。
• 工具使用原则：什么时候该用工具，什么时候不该用，优先用哪个。
• 决策流程：遇到某类问题先做什么后做什么。
• 停止条件：什么情况下算完成，完成后怎么输出。
• 异常处理：工具失败了怎么办，信息不足怎么办。

这个结构不是死的，但停止条件和异常处理这两块绝对不能省。我见过太多 Agent 因为没写停止条件而陷入死循环，或者因为没写异常处理而一遇错就摆烂。

5.2 用少样本示例教它"怎么想"

光靠文字描述行为准则，模型有时候理解不到位。这时候给一两个完整的示例特别管用。示例要包含"用户说了什么、模型怎么想、调了什么工具、拿到什么结果、最后怎么收尾"的完整链路。

比如你想让 Agent 学会"先确认信息再行动"，就可以给一个示例：用户说"帮我订明天的会议室"，模型先调用"查询可用会议室"工具，发现有几个选项，然后回复用户"有以下会议室可用，请选择"，而不是直接随便订一个。这个示例比写十句"要先确认再行动"都有效。

示例不用多，一两个就够，但一定要覆盖你最在意的那个行为。示例太多反而占 Token，而且可能让模型过度模仿示例的具体内容而不是背后的原则。

5.3 提示词里的"防呆"设计

Agent 自主性越强，越需要"防呆"。我常用的几个防呆手段：

• 明确禁止某些行为：比如"不要在没有用户确认的情况下执行删除操作"。
• 要求它先复述再执行：对于高风险操作，要求模型先说出"我准备做什么"，再执行。
• 设置优先级：当多个工具都能用时，明确告诉它优先用哪个。
• 限制输出格式：要求它每次决策时先输出"思考"再输出"行动"，方便你调试。

这些防呆设计看起来啰嗦，但能省下大量调试时间。尤其是"先输出思考再行动"这一条，它让 Agent 的决策过程变得可观测，出问题时你能一眼看出它是在哪一步想歪的。

6. 从 Demo 到部署：那些没人告诉你的工程细节

6.1 本地跑通和线上稳定是两回事

Demo 阶段你在一台机器上跑，网络稳定、没有并发、失败了手动重来。线上完全不是这样：并发请求、网络抖动、模型接口限流、工具依赖的服务偶尔挂掉，每一个都能让你的 Agent 翻车。

我上线第一个 Agent 时，最没想到的是模型接口的限流。本地测试时请求少，没感觉；上线后并发一上来，直接被限流，大量请求失败。后来加了重试机制和请求队列才稳住。所以部署前一定要问自己：模型接口的 QPS 上限是多少？超了怎么办？工具依赖的服务挂了怎么办？

6.2 日志和可观测性必须提前做

Agent 的调试难度比普通程序高，因为它的行为有随机性。没有完善的日志，你根本不知道线上那次失败到底发生了什么。我的做法是：每一轮循环都记录完整的输入输出——发给模型的完整 prompt、模型的原始输出、调用了什么工具、工具返回了什么、耗时多少。

这些日志在本地看可能觉得冗余，但线上出问题时，它们就是你的救命稻草。我遇到过一次线上 Agent 偶尔返回空结果，靠日志才发现是某个工具在特定输入下返回了空字符串，模型拿到空字符串后不知道怎么办就卡住了。没有日志，这个问题能查一整天。

6.3 灰度发布和降级方案

Agent 上线千万别一次性全量。先灰度一小部分流量，观察它的表现，确认稳定了再逐步放量。灰度期间重点看几个指标：任务成功率、平均轮数、平均 Token 消耗、工具调用失败率、超时率。

同时一定要有降级方案。Agent 挂了怎么办？最简单的降级是"回退到固定流程"或者"直接返回一个提示让用户稍后重试"。别让 Agent 的失败直接变成用户看到的报错页面。我一般会设置一个开关，出问题时一键切回旧逻辑，给自己争取排查时间。

6.4 关于部署环境的一点经验

部署环境的选择上，我踩过的坑主要是依赖管理。Agent 往往依赖一堆东西：模型 SDK、各种工具的客户端库、可能还有向量数据库。这些依赖版本冲突是家常便饭。我的建议是用容器把环境固化下来，本地跑通什么版本，线上就用什么版本，别指望"线上装个最新的应该也行"。

另外，如果 Agent 要处理敏感数据，数据流向要提前理清楚——哪些数据会发给模型、哪些留在本地、日志里会不会记录敏感信息。这些在部署前就要设计好，事后补很麻烦。

7. 学习路线：别被"速成"带偏

7.1 先动手写一个最小的，再谈架构

网上 AI Agent 的学习资料现在多如牛毛，各种"三天精通""从入门到实战"。我的建议是：别一上来就啃架构理论，先动手写一个最小的能跑的 Agent。哪怕它只能查天气、只能算数，只要你亲手把"模型决策→调工具→喂回结果→再决策"这个循环跑通了，你对 Agent 的理解就超过了一大半只看文档的人。

写最小 Agent 的过程会逼你面对所有核心问题：怎么定义工具、怎么写系统提示词、怎么控制循环、怎么处理错误。这些问题在理论文章里都是一笔带过，但只有亲手做过才知道每个都有坑。

7.2 值得投入时间深入的方向

跑通最小 Agent 之后，有几个方向值得深入：

• 工具设计能力：这是 Agent 实用性的天花板。工具设计得好，Agent 就好用；设计得烂，再强的模型也救不了。
• 提示词的稳定性：怎么让 Agent 在不同输入下都表现稳定，是个需要反复打磨的活。
• 成本控制：Token 优化、缓存、模型选择，这些直接决定你的 Agent 能不能规模化。
• 可观测性：日志、追踪、评估，这些工程能力决定你能不能维护一个线上 Agent。

至于多 Agent、记忆系统、自我反思这些高级话题，等你真的遇到单 Agent 解决不了的问题时再学，那时候你带着具体问题去学，效率比现在盲目啃高得多。

7.3 一些我踩过的心态坑

最后说几个心态上的坑。第一，别追求一步到位。我见过有人第一个 Agent 就想做多 Agent 协作加长期记忆加自我进化，结果卡在工具调用上两周没进展。第二，别迷信框架。各种 Agent 框架确实能省事，但框架抽象掉了细节，出问题时你反而不知道从哪查。我的建议是先用原生方式写一遍，理解原理后再用框架提效。第三，接受 Agent 的不完美。它会有随机性，会偶尔犯傻，这不是 bug 是特性。你要做的是设计好兜底和降级，而不是追求 100% 正确。

Agent 这个领域变化很快，今天的最佳实践明天可能就过时了。但有些东西是稳定的：对任务的理解、对成本的敏感、对工程的敬畏。把这些基本功练扎实，工具和框架怎么变你都能跟上。我在实际项目里最大的体会就是，Agent 的难点从来不在模型有多强，而在你有没有把工程细节做扎实。模型是租来的，工程能力才是自己的。