1. 从最小循环开始理解 AI Agent1.1 为什么大多数人学 Agent 都卡在第一步我接触过不少想入门 AI Agent 的朋友发现一个很普遍的现象看了大量概念文章知道 Agent 等于“大模型加工具加记忆”但真让自己动手搭一个完全不知道从哪下手。问题出在哪出在大家把 Agent 当成了一个“系统”去理解而不是一个“循环”。你去看市面上讲 Agent 的内容动不动就是多 Agent 协作、任务规划、长期记忆、向量数据库一上来就铺得特别大。但真正跑起来的最小可用 Agent核心逻辑其实简单到令人发指给大模型一个目标让它决定下一步做什么执行把结果喂回去再让它决定下一步直到任务完成。就这么个循环。我自己的经验是如果你能把最小循环跑通后面加记忆、加工具、加多 Agent 协作都是在这个循环上做增量。反过来如果最小循环没跑通就去搞架构大概率会陷入“看起来什么都有但什么都跑不起来”的困境。1.2 最小循环到底长什么样用最直白的话描述这个循环用户给一个任务描述把任务描述和可用工具列表一起发给大模型大模型返回一个决策要么调用某个工具要么直接给出最终答案如果调用了工具执行工具拿到结果把工具结果追加到对话历史里再次发给大模型重复 3-5直到大模型给出最终答案或达到最大轮次这个循环在英文社区里通常叫Agent Loop是所有 Agent 框架的底层骨架。LangChain 的 AgentExecutor、AutoGPT 的主循环、Claude 的 tool use 流程剥开外壳看都是这个结构。为什么是这个结构因为大模型本身只能做“文本进、文本出”的映射它没有手没有脚不能真的去查天气、读文件、发请求。工具调用Function Calling就是给模型装上的“手”而循环就是让这只手能连续动作的“神经回路”。1.3 一个能跑的最小实现我用 Python 写一个不依赖任何框架的最小版本你复制过去改改就能跑。这里用 OpenAI 风格的接口举例其他模型接口逻辑一致import json def agent_loop(task, tools, max_turns10): messages [{role: user, content: task}] for turn in range(max_turns): response call_llm(messages, toolstools) if response.tool_calls: for call in response.tool_calls: result execute_tool(call.name, call.arguments) messages.append(response.message) messages.append({ role: tool, tool_call_id: call.id, content: str(result) }) else: return response.content return 达到最大轮次任务未完成这段代码不到 20 行但它就是 Agent 的心脏。call_llm和execute_tool需要你自己实现前者调模型 API后者根据工具名分发到具体函数。注意max_turns这个参数千万别省。我见过太多人忘了设上限结果模型陷入死循环一晚上烧掉几十刀 API 费用。一般设 10 到 15 轮足够处理绝大多数任务。1.4 最小循环能做什么、不能做什么能做的单步或几步就能完成的任务比如“查一下北京今天天气然后告诉我穿什么”、“读这个 CSV 文件告诉我有多少行”、“搜索一下某个概念然后总结”。不能做的需要长期记忆的任务、需要并行处理多个子任务的任务、需要人工介入确认的任务。这些都需要在最小循环上做扩展但扩展的前提是你先把最小循环跑稳。我建议每个学 Agent 的人都先手写一遍这个循环不要用框架。框架帮你封装了太多东西你跑通了也不知道里面发生了什么。手写一遍你会对“消息历史怎么组织”、“工具结果怎么回传”、“模型什么时候决定停止”这些关键问题有肌肉记忆。2. Function Calling 与 Prompt 的配合机制2.1 Function Calling 不是魔法是结构化输出很多人第一次看到 Function Calling 觉得特别神奇模型怎么知道该调哪个函数其实原理很朴素你把工具的描述以特定格式塞进 prompt 里模型经过训练后学会了按照这个格式输出工具调用请求。以 OpenAI 的接口为例你传给模型的 tools 参数大概长这样{ type: function, function: { name: get_weather, description: 查询指定城市的当前天气, parameters: { type: object, properties: { city: {type: string, description: 城市名称} }, required: [city] } } }模型看到这个描述后如果判断需要查天气就会返回一个结构化的 tool_call 对象里面包含函数名和参数。你的代码解析这个对象执行对应函数把结果塞回去。关键点在于description 字段写得好不好直接决定模型会不会在正确的时机调用正确的工具。我踩过的坑是 description 写得太模糊比如写“获取信息”结果模型在该查天气的时候调了搜索工具在该搜索的时候调了天气工具。2.2 工具描述怎么写才靠谱我总结了几条实操经验动词开头说清楚做什么写“查询指定城市的实时天气”不要写“天气工具”说明什么时候用在 description 里加一句“当用户询问天气、温度、是否下雨时使用此工具”参数描述要具体city参数写“城市名称如北京、上海”不要只写“城市”限制参数格式如果参数是枚举值在 description 里列出来比如“单位只能是 celsius 或 fahrenheit”还有一个容易被忽略的点工具数量不要太多。我试过给模型塞 20 多个工具结果它经常选错。后来精简到 5 个以内准确率明显提升。如果确实需要很多工具考虑做一层路由先用一个分类 prompt 判断该用哪类工具再加载对应的工具集。2.3 Prompt 在 Agent 里的三个层次Agent 里的 prompt 不是只有一段通常分三层第一层是系统 prompt定义 Agent 的角色、行为边界、输出格式要求。比如“你是一个数据分析助手只能使用提供的工具不要编造数据”。第二层是工具描述就是上面说的 Function Calling 的 schema它本质上也是 prompt 的一部分只是以结构化形式呈现。第三层是对话历史包括用户输入、模型输出、工具调用结果这些会随着循环不断累积。三层配合的核心原则是系统 prompt 定边界工具描述定能力对话历史定上下文。任何一层出问题Agent 的行为都会跑偏。2.4 常见的 prompt 报错与规避热词里有个“invalid prompt: your prompt was flagged as potentially violating our usage”这是模型服务商的内容审核拦截。触发原因通常是 prompt 里包含了敏感词或疑似违规内容。规避方法不要在 prompt 里放用户原始输入中可能违规的部分先做一层清洗系统 prompt 里避免使用可能被误判的表述如果做的是面向用户的产品在调用模型前加一层本地关键词过滤另一个常见问题是“prompt 闪退”通常是因为 prompt 太长超出了模型的上下文窗口。解决办法是控制对话历史长度超过阈值时做摘要压缩只保留最近几轮和关键信息。实操心得我习惯在系统 prompt 末尾加一句“如果任务无法用现有工具完成直接说明原因不要尝试编造工具调用”。这句话能显著减少模型“幻觉调用”的情况。3. 从循环到系统可靠性的关键改造3.1 最小循环的三个致命缺陷最小循环能跑通 demo但直接上生产会出问题。我总结下来有三个致命缺陷第一没有错误处理。工具执行失败怎么办模型返回格式不对怎么办API 超时怎么办最小循环里这些都没考虑一出错整个流程就崩了。第二没有状态管理。对话历史无限增长很快就会超出上下文窗口。而且如果 Agent 需要跨会话记住信息最小循环完全做不到。第三没有可观测性。你根本不知道 Agent 每一步在干什么出了问题只能靠猜。这在调试阶段是灾难。3.2 错误处理与重试策略工具执行失败是最常见的问题。我的做法是分三层处理工具内部捕获异常返回结构化的错误信息而不是直接抛出。比如返回{error: 城市名称无法识别, suggestion: 请提供有效的城市名}把错误信息喂回模型让它决定是重试、换工具还是放弃。模型看到错误信息后通常会调整参数重试设置重试上限同一个工具连续失败 3 次就强制终止避免无限循环API 调用失败则用指数退避重试第一次等 1 秒第二次 2 秒第三次 4 秒最多重试 3 次。这个策略能覆盖绝大多数网络抖动。3.3 上下文窗口管理对话历史管理我试过几种方案最后稳定下来的是“滑动窗口加摘要”保留最近 N 轮完整对话N 一般设 5 到 8更早的对话做摘要压缩只保留关键结论和事实系统 prompt 和工具描述始终保留摘要的 prompt 可以这样写“请用不超过 100 字总结以下对话的关键信息和结论忽略寒暄和中间过程。”这样能把历史长度控制在可控范围内。3.4 可观测性建设可观测性我建议至少做三件事结构化日志每一步的输入输出都记下来包括模型请求、模型响应、工具调用、工具结果。用 JSON 格式方便后续检索分析关键指标监控每轮耗时、总轮次、工具调用成功率、token 消耗量。这些指标能帮你快速定位性能瓶颈回放能力把一次完整的 Agent 执行过程存下来能重新回放。调试的时候特别有用你可以逐步看模型在每一步看到了什么、做了什么决策我自己的项目里日志直接打到文件用trace_id串联一次完整执行。出问题的时候 grep 一下 trace_id整个流程一目了然。4. Workflow 编排与 Agent 的边界4.1 什么时候用 Workflow什么时候用 Agent这是被问得最多的问题之一。我的判断标准很简单任务步骤固定、可预测的用 Workflow。比如“收到邮件后提取关键信息填入表格发送通知”这个流程是确定的用 Workflow 编排又稳又快。任务步骤需要根据中间结果动态决定的用 Agent。比如“帮我分析这份销售数据找出问题并给出建议”中间需要查什么、怎么分析事先不知道得让模型自己决定。实际项目中两者经常混用。外层用 Workflow 控制主流程某些需要灵活处理的节点嵌入 Agent。这样既有确定性又有灵活性。4.2 Workflow 编排的常见工具与选型Workflow 编排工具我按场景分几类场景推荐方案理由代码内编排直接写函数调用链最简单可控性最强可视化编排n8n、Dify非技术人员也能改流程复杂状态机LangGraph支持条件分支、循环、人工介入企业级集成各类低代码平台和现有系统对接方便选型的时候别追求“最强大”追求“最合适”。我见过用 LangGraph 做三步固定流程的纯属杀鸡用牛刀调试成本还高。4.3 Agent 与 Workflow 的混合架构一个典型的混合架构长这样用户请求进来先走 Workflow 做预处理清洗输入、判断意图根据意图路由到不同的处理分支需要灵活处理的节点调用 AgentAgent 的输出回到 Workflow做后处理和格式化最终结果返回给用户这种架构的好处是主流程可控可观测Agent 只在必要的地方发挥灵活性。出问题的时候你能快速定位是 Workflow 的问题还是 Agent 的问题。4.4 编排中的状态传递Workflow 和 Agent 之间传递状态是个容易出问题的地方。我的经验是定义清晰的数据契约。比如 Agent 的输入固定为{task: str, context: dict}输出固定为{result: str, status: str, metadata: dict}。这样两边解耦各自可以独立修改。状态传递用 JSON 序列化不要传 Python 对象。我踩过的坑是直接传对象引用结果 Agent 内部修改了状态Workflow 那边拿到的是被改过的数据排查了半天才发现。5. 实操搭建一个可用的 Agent 小项目5.1 项目选型从练手项目开始热词里有“ai agent 练手小项目”我推荐从这几个方向选信息查询助手给定一个话题自动搜索、汇总、生成简报文件处理助手读取指定目录的文件提取关键信息生成报告数据分析助手给定 CSV 文件自动做基础统计并回答问题这三个项目的共同点是工具需求明确、任务边界清晰、容易验证结果。适合作为第一个完整项目。5.2 完整搭建步骤以信息查询助手为例完整步骤如下第一步定义工具。需要两个工具web_search和fetch_page。前者搜索关键词返回结果列表后者抓取指定 URL 的正文内容。第二步写系统 prompt。核心内容是“你是一个信息查询助手。用户给你一个话题你需要搜索相关信息抓取有价值的页面最后生成一份简报。简报要包含关键事实和来源链接。”第三步实现 Agent Loop。用第 1 节的最小循环加上错误处理和轮次限制。第四步加日志。每一步的输入输出都记下来方便调试。第五步测试与调优。用不同的话题测试观察模型的行为调整工具描述和系统 prompt。5.3 关键参数设置几个关键参数的经验值max_turns10 到 15。信息查询类任务一般 5 到 8 轮能完成temperature0.2 到 0.5。太低会死板太高会乱调工具max_tokens单次响应限制在 2000 以内避免模型输出过长工具超时单个工具执行不超过 30 秒超时返回错误让模型决定下一步5.4 测试与迭代测试的时候重点看几个指标任务完成率、平均轮次、工具调用准确率。我一般跑 20 个测试用例统计这些指标然后针对性优化。优化优先级先修工具描述影响最大再调系统 prompt最后调参数。我见过有人一上来就调 temperature结果调了半天不如把工具描述改清楚来得有效。实操心得测试用例要包含边界情况比如“搜索一个不存在的话题”、“工具返回空结果”、“用户输入很模糊”。这些情况最能暴露问题。6. 常见问题与排查技巧实录6.1 模型不调用工具怎么办这是最常见的问题。模型直接用自己的知识回答了没有调用你提供的工具。原因通常是工具描述不够清晰模型没意识到该用工具系统 prompt 没有强调“必须使用工具获取信息”模型本身能力不足对 Function Calling 支持不好解决办法在系统 prompt 里明确写“对于需要实时信息的问题必须先调用搜索工具不要依赖你的训练数据”。同时在工具描述里写清楚适用场景。6.2 模型反复调用同一个工具模型陷入循环一直调同一个工具。原因通常是工具返回的结果没有解决模型的问题它以为再调一次能拿到不同结果。解决办法在工具结果里加提示比如“这是搜索的最终结果没有更多信息了”。或者在系统 prompt 里写“同一个工具连续调用两次后如果结果仍不满足需求请基于现有信息给出答案”。6.3 工具调用参数格式错误模型返回的参数格式不对比如该传字符串传了数字该传数组传了对象。这是模型能力问题但可以通过以下方式缓解在参数描述里写清楚类型和格式在工具执行前做参数校验和类型转换校验失败时返回明确的错误信息让模型重新生成6.4 常见问题速查表问题现象可能原因排查方向模型不调工具描述不清、prompt 未强调检查工具 description 和系统 prompt反复调同一工具结果未满足、缺少终止条件加结果提示、设调用上限参数格式错误模型能力不足、描述不明确加参数校验、细化描述响应超时工具执行慢、轮次过多加超时、限制轮次上下文溢出历史过长加滑动窗口和摘要内容审核拦截prompt 含敏感词加本地过滤、清洗输入6.5 独家避坑技巧最后分享几个我踩坑总结出来的技巧技巧一给工具加“使用示例”。在工具描述里加一个调用示例模型模仿示例的准确率明显更高。技巧二用 few-shot 引导。在系统 prompt 里放一两个完整的“用户提问-工具调用-结果-最终回答”的示例模型会照着这个模式走。技巧三日志里记录 token 消耗。每个步骤的 token 消耗都记下来你会发现某些步骤消耗特别大针对性优化能省不少成本。技巧四先跑通再优化。不要一开始就追求完美架构先用最小循环跑通再逐步加错误处理、状态管理、可观测性。我见过太多人卡在架构设计上最后什么都没跑起来。技巧五保留人工介入的接口。生产环境里Agent 遇到不确定的情况应该能暂停并请求人工确认而不是硬着头皮往下走。这个接口在最小循环里就要预留。这些经验都是实际项目中积累的不一定适用于所有场景但大方向应该能帮你少走些弯路。Agent 这个领域变化很快但底层的最小循环和核心问题相对稳定把基础打牢上层的东西学起来就快了。