1. 为什么现在聊 AI Agent 正是时候过去一年我断断续续做了四五个 Agent 相关的项目有给内部用的运维助手也有面向业务侧的流程自动化工具。踩过的坑从“模型死活不按格式输出”到“工具调用循环把自己绕死”基本把能犯的错都犯了一遍。所以当有人问我“AI Agent 到底怎么从零搭”的时候我不太想再讲那些“Agent 等于 LLM 加记忆加工具”的教科书定义而是想把这套东西拆开讲讲每个零件为什么这么设计、实际落地时会遇到什么。先把概念对齐一下。AI Agent说白了就是一个能自己决定“下一步做什么”的程序它和普通脚本最大的区别在于脚本的流程是你写死的Agent 的流程是模型在运行时动态决定的。你给它一个目标它自己拆解、自己选工具、自己判断做完了没有。这里面LLM是大脑Workflow是骨架DevOps是让它能稳定跑在生产环境的那套工程实践。这三个词基本覆盖了从原型到上线的全链路。这篇文章适合谁看如果你已经会调 API、写过后端服务但一直没搞明白 Agent 和普通 LLM 应用的区别那这篇能帮你把思路理顺。如果你已经在做 Agent 了但总觉得它“不太听话”“跑着跑着就崩”那中间关于工具设计和状态管理的部分应该对你有用。我不会只讲概念每个环节都会给出可复现的做法和参数选择的理由。2. 拆解 AI Agent 的核心架构与设计取舍2.1 Agent 和 Workflow 到底是不是一回事这是我最常被问到的问题也是很多团队一开始就走偏的地方。Workflow 编排指的是你把步骤提前定义好比如“先查数据库再调模型总结最后发邮件”每一步的输入输出都是确定的。而 Agent 的核心特征是控制流由模型决定——它可能查完数据库觉得信息不够又去调了个搜索工具这个分支你事先没写。那是不是 Agent 就一定比 Workflow 高级完全不是。我自己的判断标准很简单如果任务的步骤可以穷举就用 Workflow如果步骤数量不确定、依赖运行时信息才上 Agent。举个例子一个“每天定时汇总销售数据发日报”的需求用 Workflow 就够了硬套 Agent 反而增加了不确定性和调试成本。但如果是“帮我排查这台服务器为什么响应慢”你没法预知要查哪些指标、看哪些日志这种才需要 Agent 的自主决策能力。实际项目里更常见的是混合模式外层用 Workflow 保证主流程可控某个需要灵活判断的节点内部嵌一个 Agent。这样既拿到了 Agent 的灵活性又不至于整个系统变成黑盒。2.2 一个 Agent 最少需要哪几个零件抛开那些花哨的框架一个能跑起来的 Agent 核心就四样东西LLM 推理核心负责理解目标、做决策、生成动作。选型上如果任务涉及复杂的多步推理用能力强的模型如果只是简单的工具路由小模型甚至本地模型就够。工具集ToolsAgent 能调用的外部能力比如搜索、读写文件、调 API。工具的描述质量直接决定 Agent 会不会用错。记忆Memory短期记忆就是当前对话的上下文长期记忆通常靠外部存储向量库、知识库实现。循环控制Loop决定 Agent 什么时候继续、什么时候停。这是最容易被忽视但最容易出事的部分。我见过太多人一上来就找框架结果被框架的抽象层绕晕。我的建议是先用最朴素的方式手写一个循环把上面四个零件跑通再去考虑要不要上框架。手写一遍你对整个链路的理解会完全不一样。2.3 为什么我建议从手写循环开始框架确实能省事但它也把很多关键细节藏起来了。比如工具调用的错误怎么处理、上下文超长了怎么截断、模型输出了非法格式怎么办——这些在框架里往往是默认行为你不看源码根本不知道它怎么处理的。而这些问题恰恰是 Agent 上线后最容易出故障的地方。手写一个最小循环大概长这样伪代码逻辑messages [system_prompt, user_goal] while not done: response llm.chat(messages, toolstool_schemas) if response.has_tool_call: result execute_tool(response.tool_call) messages.append(response) messages.append(result) else: done True final_answer response.content就这么十几行但它包含了 Agent 的全部本质。你把这个跑通了再去看任何框架都会觉得清晰。而且手写的过程中你会被迫思考循环最多跑几轮工具报错了要不要把错误信息喂回给模型这些决策在框架里可能是一个配置项但你必须知道它背后的权衡。3. 核心细节解析与实操要点3.1 工具设计Agent 好不好用八成看这里工具是 Agent 和外界交互的唯一通道工具设计得好不好直接决定了 Agent 的可靠性。我踩过的最大的坑就是工具描述写得太随意导致模型经常选错工具或者传错参数。一个好的工具定义要包含三部分清晰的用途说明、明确的参数约束、可预期的返回格式。用途说明不是写给人看的是写给模型看的所以要具体。比如“查询用户信息”就不如“根据用户 ID 查询该用户的基本资料包括姓名、注册时间和会员等级”来得清楚。参数约束方面能用枚举就别用自由文本。比如一个“设置日志级别”的工具参数直接限定为debug/info/warn/error四个值模型就不会瞎编一个verbose出来。返回格式也要稳定最好统一成结构化的 JSON并且在工具描述里说明返回的字段含义这样模型才能正确解读结果。还有一个经验工具数量不要贪多。我做过一个实验当工具数量从 5 个增加到 20 个时模型选错工具的概率明显上升。如果确实需要很多能力可以考虑分层——先让 Agent 选一个大类再在大类里选具体工具。3.2 上下文管理别让记忆把窗口撑爆Agent 跑多轮之后上下文会越来越长这是必然的。如果不做管理要么超出模型窗口报错要么 token 成本飙升。我一般用三种策略组合第一种是滑动窗口只保留最近 N 轮对话。简单粗暴但有效适合大多数场景。N 的取值要看任务复杂度我一般从 10 轮开始调。第二种是摘要压缩把早期的对话让模型总结成一段话替换掉原始消息。这样既保留了关键信息又大幅缩短了长度。缺点是摘要本身也要花一次模型调用而且可能丢细节。第三种是外部记忆把重要信息存到向量库或结构化存储里需要的时候再检索回来。这就是RAG的思路适合知识密集型的 Agent。实际操作中我会把三者结合近期对话用滑动窗口中期用摘要长期知识放外部存储。关键是在系统提示里明确告诉模型它有哪些记忆可用否则模型不知道自己能去查。3.3 循环终止条件防止 Agent 陷入死循环Agent 最危险的行为就是无限循环——反复调同一个工具或者在不同工具之间来回横跳。我见过一个 Agent 因为工具一直返回错误它就一直重试半小时烧掉了几十块钱的 token。防护措施有几层。最基础的是设置最大轮数比如 15 轮还没结束就强制停止并返回当前结果。其次是检测重复动作如果连续两次调用了相同的工具和参数就打断它把情况反馈给模型让它换个思路。再进一步可以做成本监控token 消耗超过阈值就熔断。这些防护不是限制 Agent 的能力而是给它划一个安全边界。就像给新员工定规矩一样不是不信任他而是让整个系统可控。4. 实操过程与核心环节实现4.1 从需求到 Agent 的第一步任务拆解拿到一个需求我第一件事不是写代码而是判断它到底适不适合用 Agent。判断方法前面说过——步骤能不能穷举。如果能穷举老老实实写 Workflow。假设确认要用 Agent 了下一步是把任务拆成“模型能决策的最小单元”。比如“帮我分析这份销售报表并给出建议”拆解下来是读取文件、理解数据结构、做统计分析、结合业务知识给建议。其中“做统计分析”可能需要调计算工具“结合业务知识”可能需要查知识库。拆完之后你就知道需要哪些工具、需要什么记忆。这一步做扎实了后面的开发会顺很多。我见过太多人跳过这步直接写代码结果写到一半发现工具设计不合理推倒重来。4.2 系统提示的写法给 Agent 立规矩系统提示是 Agent 的“行为准则”写得好能省掉大量调试。我的系统提示一般包含这几块角色定义一句话说清楚它是谁、负责什么。比如“你是一个数据分析助手负责帮用户分析销售数据并给出可执行的建议”。能力边界明确告诉它不能做什么。比如“你只能基于提供的工具获取数据不要编造任何数字”。工作流程给出推荐的做事顺序。比如“先确认数据来源再做分析最后给建议”。输出格式规定最终答案的结构。比如“用 Markdown 格式先给结论再给依据”。异常处理告诉它遇到问题怎么办。比如“如果工具返回错误先检查参数是否正确连续两次失败就向用户说明情况”。这几块写下来系统提示通常会有几百字。别嫌长这是最划算的投入——系统提示写清楚后面能少调很多次。4.3 工具调用的错误处理实战工具调用失败是家常便饭网络超时、参数错误、权限不足都可能发生。关键是怎么把错误信息有效地反馈给模型让它能自我修正。我的做法是把错误分成两类。一类是模型能自己修的比如参数格式不对、缺少必填字段这类错误要把具体的错误信息返回给模型它看到“缺少 user_id 字段”就知道要补上。另一类是模型修不了的比如服务不可用、权限被拒这类要明确告诉模型“这个工具暂时不可用请尝试其他方式或告知用户”。这里有个细节错误信息不要直接抛原始堆栈模型看不懂还浪费 token。要转成自然语言描述比如把KeyError: user_id转成“调用失败缺少必填参数 user_id”。4.4 用 DevOps 思路管理 Agent 的迭代Agent 和传统软件最大的不同是它的行为不完全确定所以迭代方式也不一样。我一般会做三件事记录完整轨迹每次 Agent 运行的完整消息序列、工具调用、耗时、token 消耗都存下来。这些数据是后续优化的基础。建立评测集挑一批有代表性的任务每次改动后跑一遍看成功率有没有下降。这个评测集不用很大二三十个案例就能发现大部分回归问题。灰度发布Agent 的改动不要一次性全量先放一小部分流量观察几天再扩大。因为有些问题只在特定输入下才暴露。这套做法其实就是把DevOps的理念搬到 Agent 上——可观测、可回滚、可迭代。5. 常见问题与排查技巧实录5.1 模型不按格式输出怎么办这是最高频的问题。模型有时候会忘记用工具直接开始“编”答案有时候工具调用的参数格式不对。我的排查顺序是先看系统提示有没有明确要求。很多时候是提示里没写清楚模型就自由发挥了。其次看工具描述是不是有歧义模型可能理解错了工具的用途。如果都没问题可以在提示里加几个示例也就是 few-shot让模型照着模仿。还有一个技巧是用模型的“工具选择”能力而不是“文本生成”能力。现在主流模型都支持结构化的工具调用接口走这个接口比让模型自己拼 JSON 要可靠得多。5.2 Agent 反复调用同一个工具这通常是因为工具返回的结果没有让模型满意它以为再调一次会有不同结果。解决办法是在工具返回里加上明确的信号比如“这是最终结果无需重复查询”。或者在循环控制里加检测连续相同调用就打断。5.3 上下文超长导致报错前面讲过上下文管理策略这里补充一个实操细节在截断上下文之前先把关键信息提取出来。比如把已经确认的事实、已经完成的步骤存到一个结构化的“工作记忆”里截断对话历史时保留这个工作记忆。这样模型不会因为丢了历史而重复劳动。5.4 常见问题速查表问题现象可能原因排查方向模型不调用工具系统提示未强调、工具描述不清检查提示词和工具定义工具参数错误参数约束不明确用枚举替代自由文本无限循环缺少终止条件加最大轮数和重复检测上下文超长未做记忆管理滑动窗口加摘要压缩结果不稳定温度参数过高降低 temperature响应太慢工具串行调用考虑并行化独立工具5.5 几个我踩过的坑第一个坑是过度依赖模型的“常识”。有次我让 Agent 处理日期没给它日期工具结果它自己算错了闰年。后来我学乖了凡是涉及精确计算的一律给工具不让模型自己算。第二个坑是工具返回的数据量太大。有次一个查询工具返回了几万行数据直接把上下文撑爆了。后来我在工具层面做了分页和摘要只返回模型需要的关键信息。第三个坑是没有做超时控制。某个外部 API 偶尔会卡住导致整个 Agent 挂起。后来给所有工具调用都加了超时超时就返回错误让模型决定下一步。6. 关于框架选型和后续扩展的一些想法框架这东西我的态度是能用标准库解决的就别上框架。但有些场景确实需要框架比如你要做复杂的多 Agent 协作、需要可视化的编排界面、团队协作需要统一的抽象。这时候选框架要看几点抽象是否清晰、错误处理是否透明、是否方便调试。至于后续扩展我觉得有几个方向值得投入。一是评测体系的完善Agent 的效果很难用单一指标衡量需要建立多维度的评估。二是成本优化通过缓存、模型分级、并行调用等手段把单次任务的成本降下来。三是安全边界特别是当 Agent 能执行写操作的时候权限控制必须做扎实。最后分享一个我自己的习惯每次 Agent 出问题我都会把完整的轨迹存下来过一段时间回头分析。很多问题不是孤立的而是有模式。积累多了你就能预判哪些地方容易出问题提前做好防护。这个习惯帮我省了很多重复排查的时间。