1. 从“七要素”到“七个决策点”为什么 Agent 工程需要一套拆解框架AI Agent 这个词在过去一年多里被反复提及但真正落到工程实现层面很多人还是会卡在同一个地方知道它大概是什么却不知道从哪下手把它搭出来。我自己在带团队做 Agent 项目的时候最常听到的问题不是“LLM 怎么调”而是“循环怎么写才不会跑飞”“工具调用失败了怎么办”“记忆到底存什么”。这些问题背后其实指向同一件事——Agent 不是一个模型而是一套工程系统。把 Agent 拆成“七要素”是为了让你看清它由哪些零件组成把工程实现拆成“七个决策点”是为了让你知道每个零件在落地时要做哪些取舍。这两件事合起来才构成一个可复现的 Agent 工程路径。这篇文章面向的是已经了解 LLM 基本调用、想真正把 Agent 跑起来的开发者也适合正在做 Agent 架构选型的技术负责人。我会尽量把每个决策点背后的“为什么”讲清楚而不是只给一个结论。先说清楚一个前提Agent 和单纯的 LLM 调用最大的区别在于自主性。普通 LLM 调用是“输入一次、输出一次”而 Agent 是“给一个目标它自己决定走几步、用什么工具、什么时候停”。这个差异决定了 Agent 工程的核心难点不在模型本身而在循环机制、工具调用、状态管理这三件事的协同。热搜词里频繁出现的“agent架构”“agent框架与编排”“agent记忆”本质上都是在解决这个协同问题。我见过不少团队一开始就想上复杂框架结果被框架的抽象层拖慢调试速度。我的建议是先用最小可运行循环把七要素串起来再根据实际瓶颈决定要不要引入编排框架。这也是我后面讲七个决策点时反复强调的一个原则——先跑通再优化。2. Agent 七要素拆解每个零件到底在系统里干什么2.1 目标与指令Agent 的“任务定义层”目标与指令是 Agent 的起点但它比很多人想的要复杂。一个模糊的目标会让 Agent 在循环里反复试探浪费 token 还容易跑偏。我在实际项目里会把目标拆成三层最终目标、当前子目标、约束条件。最终目标是用户给的比如“帮我整理这份竞品分析”当前子目标是 Agent 自己拆的比如“先抓取三家竞品官网的产品页”约束条件是硬性的比如“不要访问需要登录的页面”。这三层分开写的好处是Agent 在每一轮循环里只需要关注当前子目标不会因为最终目标太远而迷失。约束条件则直接写进系统提示词作为不可逾越的边界。我试过把约束条件放在用户消息里结果模型经常在长对话中“忘记”后来改成系统提示词里的固定段落稳定性明显提升。注意目标描述里尽量避免“尽量”“最好”这类模糊词Agent 对这类词的处理方式很不稳定有时会过度追求有时会直接忽略。2.2 记忆短期上下文与长期知识的分离记忆是 Agent 工程里最容易做过头的地方。很多人一上来就想做“永久记忆”结果发现检索出来的内容要么不相关要么把上下文撑爆。我的做法是把记忆分成两层短期记忆就是当前会话的上下文窗口长期记忆是外部存储的向量库或结构化数据库。短期记忆的管理核心是裁剪策略。我一般用“滑动窗口 摘要”的组合保留最近 N 轮完整对话更早的内容压缩成一段摘要。N 的取值取决于任务复杂度简单任务 5 到 8 轮够用复杂任务可以到 15 轮。摘要的生成时机是在窗口滑动时触发用一次额外的 LLM 调用把被裁掉的内容压缩。长期记忆的写入要克制。我见过把每一轮对话都写进向量库的做法结果检索噪声极大。更合理的做法是只写入经过验证的事实、用户偏好、任务结论这三类内容。写入前加一个判断步骤让模型自己决定“这条信息值不值得长期保存”能过滤掉大量垃圾。2.3 工具调用Agent 与外部世界的手工具调用是 Agent 从“会说”变成“会做”的关键。热搜词里“工具调用”出现频率很高但真正落地时难点不在调用本身而在工具描述的设计。模型选择哪个工具几乎完全取决于工具描述写得好不好。我写工具描述时会遵循三个原则动词开头、说明输入输出、给出使用场景。比如不要写“天气查询工具”而要写“查询指定城市当前天气输入城市名返回温度和天气状况适用于需要实时天气信息的场景”。这样模型在决策时能更快匹配。工具调用的失败处理也是重点。我的经验是给每个工具设置超时和重试上限超时后返回一个结构化的错误信息给模型让它自己决定是换工具还是放弃。不要直接抛异常中断循环那样 Agent 就“死”了。2.4 规划把大目标拆成可执行步骤规划能力决定了 Agent 能不能处理多步任务。我一般把规划分成两种模式前置规划和边做边规划。前置规划是在任务开始时让模型输出一个步骤列表适合步骤明确的任务边做边规划是每一轮根据当前状态决定下一步适合探索性任务。实际项目里我更多用混合模式先做一次粗粒度的前置规划得到 3 到 5 个大步骤然后在每个大步骤内部用边做边规划。这样既有全局方向又保留了灵活性。规划的输出格式我建议用结构化 JSON方便后续解析和校验。2.5 执行循环机制的核心执行就是 Agent 的主循环。一个典型的循环是观察当前状态 → 决定下一步动作 → 执行动作 → 更新状态 → 判断是否结束。这个循环看起来简单但每个环节都有坑。循环的终止条件必须明确。我一般设置三个终止条件达到最终目标、达到最大轮数、连续 N 轮无有效进展。最大轮数是硬性保护防止无限循环无进展检测是软性保护防止 Agent 在原地打转。这两个条件缺一不可。2.6 反思让 Agent 自己发现错误反思是 Agent 从错误中恢复的机制。我的做法是在每轮执行后加一个轻量的自检步骤让模型判断“上一步的结果是否推进了当前子目标”。如果判断为否就触发一次反思分析原因并调整策略。反思不要做得太重否则每轮都调用一次大模型成本会失控。我的经验是只在检测到异常时触发反思比如工具返回错误、结果为空、或者连续两轮动作相似。这样既控制了成本又保留了纠错能力。2.7 输出结果的整理与交付输出是 Agent 的最后一环但很多人会忽略它。Agent 跑完一堆步骤后如果直接把中间结果丢给用户体验会很差。我一般会加一个结果整理步骤把执行过程中的关键信息汇总成用户能直接用的格式。整理步骤的提示词要明确告诉模型“面向最终用户”去掉中间过程的噪声只保留结论和必要的依据。如果任务有多个交付物还要按优先级排序。3. 七个决策点Agent 工程实现中的关键取舍3.1 决策点一循环用固定轮数还是动态判断这是 Agent 工程的第一个岔路口。固定轮数实现简单但要么浪费要么不够动态判断灵活但需要额外的判断逻辑。我的选择是动态判断为主、固定轮数为辅。具体做法是主循环用动态判断每轮结束后让模型输出一个continue或stop的标志同时设置一个最大轮数作为硬性上限比如 20 轮。动态判断的提示词要写清楚“如果当前子目标已完成或无法继续输出 stop”。实测下来这种组合在大多数任务上都能在 5 到 10 轮内收敛。提示动态判断的标志位不要和工具调用混在一起输出分开两次调用更稳定虽然多花一点 token但解析逻辑简单很多。3.2 决策点二工具是预定义还是动态发现预定义工具就是提前写好工具列表Agent 从里面选动态发现是让 Agent 自己去找可用工具。前者可控后者灵活。我的建议是生产环境用预定义探索场景可以试动态发现。预定义工具的关键是控制数量。我试过给 Agent 挂 30 多个工具结果模型选择准确率明显下降。后来精简到 8 到 12 个核心工具准确率回升。如果工具确实多可以分组让 Agent 先选组再选工具。3.3 决策点三记忆存向量库还是结构化存储向量库适合语义检索结构化存储适合精确查询。我的经验是两者结合事实类、偏好类信息存结构化数据库文档类、对话类信息存向量库。检索时先查结构化没有再查向量库。向量库的坑主要在分块策略。块太大检索不精准块太小丢失上下文。我一般按语义段落分块每块 200 到 500 字块之间保留 20% 重叠。嵌入模型的选择上中文场景我倾向用专门优化过中文的模型通用模型在中文短文本上表现不稳定。3.4 决策点四规划用一次性还是增量式一次性规划适合步骤明确的任务比如“生成一份报告”增量式规划适合探索性任务比如“调研某个市场”。我的做法是默认增量式任务明确时切一次性。增量式规划的实现要点是每轮都要重新评估当前状态而不是机械执行初始计划。我见过不少 Agent 一开始规划得很好但执行中环境变了还在按老计划走结果越走越偏。每轮重新评估能避免这个问题。3.5 决策点五错误处理用重试还是降级工具调用失败时重试和降级是两种思路。重试适合临时性错误降级适合持续性错误。我的策略是先重试一次再降级。重试要设置退避时间不要立即重试否则可能连续失败。降级则是换一个更简单的方案比如搜索工具失败就改用缓存结果。降级方案要提前准备好不要等出错了才想。3.6 决策点六状态管理用内存还是外部存储内存状态实现简单但 Agent 重启就丢外部存储持久但增加复杂度。我的选择是开发阶段用内存生产环境用外部存储。外部存储我一般用 Redis 存短期状态用数据库存长期状态。状态的结构要设计好我通常分成task_state、step_history、tool_results三部分方便调试时定位问题。3.7 决策点七输出用原始结果还是二次加工原始结果直接返回实现简单但体验差二次加工体验好但多一次调用。我的做法是默认二次加工简单任务可跳过。二次加工的提示词要明确“面向用户”去掉中间过程。如果任务有格式要求还要在提示词里写清楚格式规范。我一般会让模型输出 Markdown 格式方便直接展示。4. 从零搭建一个最小可运行 Agent完整实操流程4.1 环境准备与依赖选择我用的技术栈是 Python OpenAI 兼容接口 Redis。Python 生态成熟调试方便OpenAI 兼容接口意味着可以换任何兼容的模型服务Redis 用来存状态和缓存。依赖清单如下pip install openai redis pydantic如果你用的是其他模型服务把openai换成对应的 SDK 即可。我建议用pydantic定义工具和状态的结构类型检查能帮你提前发现很多问题。4.2 定义工具与工具注册表工具定义我用一个字典来管理每个工具包含名称、描述、参数 schema 和执行函数。下面是一个搜索工具的示例from pydantic import BaseModel class SearchArgs(BaseModel): query: str top_k: int 5 def search_tool(query: str, top_k: int 5): # 实际搜索逻辑 return results TOOLS { search: { description: 搜索指定关键词返回相关文档列表适用于需要外部信息的场景, args_model: SearchArgs, func: search_tool } }工具描述我反复强调过要写清楚“做什么、输入什么、输出什么、什么时候用”。这四要素齐了模型选择准确率会高很多。4.3 实现主循环主循环是整个 Agent 的心脏。我的实现分成四步构造提示词、调用模型、解析动作、执行动作。def agent_loop(task, max_turns20): state init_state(task) for turn in range(max_turns): prompt build_prompt(state) response call_llm(prompt) action parse_action(response) if action.type stop: break result execute_action(action) state update_state(state, action, result) if no_progress(state): break return finalize(state)build_prompt负责把当前状态、工具列表、历史步骤拼成提示词。parse_action负责从模型输出里提取动作我一般要求模型输出 JSON解析失败时重试一次。no_progress检测连续两轮动作是否相似相似就中断。4.4 状态更新与记忆写入状态更新要区分短期和长期。短期状态每轮都更新长期记忆只在特定条件下写入。def update_state(state, action, result): state[step_history].append({ action: action, result: result }) if should_write_long_term(action, result): write_to_long_term(state[task_id], action, result) return stateshould_write_long_term的判断逻辑我一般让模型来做给它一个简单的提示词“这条信息是否值得长期保存只回答是或否”。这样能过滤掉大部分临时信息。4.5 终止条件与结果整理终止条件我设置三个模型输出 stop、达到最大轮数、连续无进展。结果整理用一个单独的 LLM 调用提示词里明确“面向用户去掉中间过程输出 Markdown”。def finalize(state): prompt f根据以下执行记录整理成面向用户的最终结果{state[step_history]} return call_llm(prompt)整理步骤的提示词里我还会加上“如果任务未完成说明原因和已完成部分”这样即使 Agent 中途停止用户也能知道发生了什么。5. 常见问题与排查技巧实录5.1 Agent 陷入无限循环怎么办无限循环是最常见的问题。排查思路是看step_history如果连续几轮动作相似基本可以确定是循环。解决方法有三个加无进展检测、加最大轮数、在提示词里明确“不要重复已执行的动作”。我遇到过一次循环是因为工具返回的结果格式和模型预期不一致模型反复尝试同一个工具。后来在工具描述里加了返回格式示例问题就解决了。5.2 工具调用总是选错工具怎么办工具选错通常是描述问题。排查方法是把工具描述单独拿出来让模型做一次“给定任务选择工具”的测试。如果准确率低就优化描述。我一般会做两件事一是把相似工具合并或明确区分二是给每个工具加“不适用场景”的说明。比如搜索工具加一句“不适用于查询本地文件”能减少误选。5.3 记忆检索不相关怎么优化检索不相关的原因通常是分块策略或嵌入模型的问题。排查方法是手动测试几个查询看返回的块是否相关。如果不相关先调分块大小再考虑换嵌入模型。我的经验是中文场景下分块按语义段落切比按固定长度切效果好很多。另外检索时可以加一个重排序步骤用一个小模型对候选块重新打分能明显提升相关性。5.4 Token 消耗过快怎么控制Token 消耗主要来自三块提示词、历史上下文、工具返回结果。控制方法分别是精简提示词、裁剪历史、截断工具返回。我一般会把工具返回结果截断到 500 字以内超出部分只保留摘要。历史上下文用滑动窗口加摘要能省不少 token。提示词方面去掉所有不必要的示例和说明只保留核心指令。5.5 常见问题速查表问题可能原因排查方法解决方向无限循环无进展检测缺失查看 step_history加检测和最大轮数工具选错描述不清晰单独测试工具选择优化描述加不适用场景检索不相关分块或嵌入问题手动测试查询调分块加重排序Token 过快上下文过长统计各部分 token裁剪历史截断返回结果质量差整理步骤缺失检查 finalize加整理提示词5.6 几个我踩过的坑第一个坑是工具描述里用了太多技术术语。模型对术语的理解不如自然语言稳定后来我改成用大白话描述准确率反而提升了。第二个坑是状态更新时覆盖了历史。早期我用字典直接赋值结果历史丢了。后来改成列表追加问题解决。第三个坑是反思步骤触发太频繁。一开始我每轮都反思成本翻倍。后来改成只在异常时触发成本降了一半效果没差。6. 工程化扩展从能跑到好用还差什么6.1 可观测性日志与追踪Agent 跑起来之后最需要的是能看清它每一步在干什么。我一般会记录三类日志提示词日志、动作日志、结果日志。提示词日志用于调试模型行为动作日志用于追踪决策路径结果日志用于评估效果。如果条件允许可以接入追踪系统把每一步的耗时、token 消耗、工具调用结果都记录下来。这样出问题时能快速定位是模型问题还是工具问题。6.2 评估怎么判断 Agent 好不好用评估 Agent 比评估普通模型复杂因为它有多步交互。我的做法是定义一组任务集每个任务有明确的成功标准然后跑一遍看成功率。成功标准可以是“最终结果包含关键信息”或“在 N 轮内完成”。除了成功率我还会看平均轮数和平均 token 消耗。这两个指标能反映效率。如果成功率高但轮数多说明规划能力有优化空间。6.3 安全工具调用的边界控制工具调用是 Agent 与外部交互的通道必须设边界。我的做法是给每个工具设置权限等级高风险工具需要额外确认。比如写文件、发请求这类工具我会加一个确认步骤让模型先输出计划再执行。另外工具的参数要做校验防止模型生成非法参数。我用 pydantic 做参数校验非法参数直接返回错误给模型让它重新生成。6.4 成本优化哪些环节可以省成本优化我一般从三个地方入手提示词精简、历史裁剪、模型分级。提示词精简是最直接的去掉所有不必要的说明。历史裁剪用滑动窗口加摘要。模型分级是把简单任务交给小模型复杂任务才用大模型。我试过把工具选择交给小模型执行交给大模型成本降了大概 40%效果基本没差。这个思路值得一试。6.5 后续可以扩展的方向如果基础版本跑通了可以考虑几个扩展方向多 Agent 协作把不同职责拆给不同 Agent工具动态发现让 Agent 自己注册新工具长期记忆优化引入更精细的检索和重排序。不过我的建议是先把单 Agent 跑稳再考虑多 Agent。多 Agent 的协调成本很高单 Agent 没跑好就上多 Agent很容易失控。最后分享一个我在实际项目里总结的小技巧每次修改 Agent 逻辑后先用固定任务集跑一遍回归测试。Agent 的行为很容易被一个小改动影响回归测试能帮你快速发现意外变化。这个习惯帮我省了很多调试时间。 
长河君 · 2026/10/8 11:06:26 · 阅读 1.2k Agent工程实战：七要素拆解与七个决策点，从零搭建可运行Agent
1. 从“七要素”到“七个决策点”为什么 Agent 工程需要一套拆解框架AI Agent 这个词在过去一年多里被反复提及但真正落到工程实现层面很多人还是会卡在同一个地方知道它大概是什么却不知道从哪下手把它搭出来。我自己在带团队做 Agent 项目的时候最常听到的问题不是“LLM 怎么调”而是“循环怎么写才不会跑飞”“工具调用失败了怎么办”“记忆到底存什么”。这些问题背后其实指向同一件事——Agent 不是一个模型而是一套工程系统。把 Agent 拆成“七要素”是为了让你看清它由哪些零件组成把工程实现拆成“七个决策点”是为了让你知道每个零件在落地时要做哪些取舍。这两件事合起来才构成一个可复现的 Agent 工程路径。这篇文章面向的是已经了解 LLM 基本调用、想真正把 Agent 跑起来的开发者也适合正在做 Agent 架构选型的技术负责人。我会尽量把每个决策点背后的“为什么”讲清楚而不是只给一个结论。先说清楚一个前提Agent 和单纯的 LLM 调用最大的区别在于自主性。普通 LLM 调用是“输入一次、输出一次”而 Agent 是“给一个目标它自己决定走几步、用什么工具、什么时候停”。这个差异决定了 Agent 工程的核心难点不在模型本身而在循环机制、工具调用、状态管理这三件事的协同。热搜词里频繁出现的“agent架构”“agent框架与编排”“agent记忆”本质上都是在解决这个协同问题。我见过不少团队一开始就想上复杂框架结果被框架的抽象层拖慢调试速度。我的建议是先用最小可运行循环把七要素串起来再根据实际瓶颈决定要不要引入编排框架。这也是我后面讲七个决策点时反复强调的一个原则——先跑通再优化。2. Agent 七要素拆解每个零件到底在系统里干什么2.1 目标与指令Agent 的“任务定义层”目标与指令是 Agent 的起点但它比很多人想的要复杂。一个模糊的目标会让 Agent 在循环里反复试探浪费 token 还容易跑偏。我在实际项目里会把目标拆成三层最终目标、当前子目标、约束条件。最终目标是用户给的比如“帮我整理这份竞品分析”当前子目标是 Agent 自己拆的比如“先抓取三家竞品官网的产品页”约束条件是硬性的比如“不要访问需要登录的页面”。这三层分开写的好处是Agent 在每一轮循环里只需要关注当前子目标不会因为最终目标太远而迷失。约束条件则直接写进系统提示词作为不可逾越的边界。我试过把约束条件放在用户消息里结果模型经常在长对话中“忘记”后来改成系统提示词里的固定段落稳定性明显提升。注意目标描述里尽量避免“尽量”“最好”这类模糊词Agent 对这类词的处理方式很不稳定有时会过度追求有时会直接忽略。2.2 记忆短期上下文与长期知识的分离记忆是 Agent 工程里最容易做过头的地方。很多人一上来就想做“永久记忆”结果发现检索出来的内容要么不相关要么把上下文撑爆。我的做法是把记忆分成两层短期记忆就是当前会话的上下文窗口长期记忆是外部存储的向量库或结构化数据库。短期记忆的管理核心是裁剪策略。我一般用“滑动窗口 摘要”的组合保留最近 N 轮完整对话更早的内容压缩成一段摘要。N 的取值取决于任务复杂度简单任务 5 到 8 轮够用复杂任务可以到 15 轮。摘要的生成时机是在窗口滑动时触发用一次额外的 LLM 调用把被裁掉的内容压缩。长期记忆的写入要克制。我见过把每一轮对话都写进向量库的做法结果检索噪声极大。更合理的做法是只写入经过验证的事实、用户偏好、任务结论这三类内容。写入前加一个判断步骤让模型自己决定“这条信息值不值得长期保存”能过滤掉大量垃圾。2.3 工具调用Agent 与外部世界的手工具调用是 Agent 从“会说”变成“会做”的关键。热搜词里“工具调用”出现频率很高但真正落地时难点不在调用本身而在工具描述的设计。模型选择哪个工具几乎完全取决于工具描述写得好不好。我写工具描述时会遵循三个原则动词开头、说明输入输出、给出使用场景。比如不要写“天气查询工具”而要写“查询指定城市当前天气输入城市名返回温度和天气状况适用于需要实时天气信息的场景”。这样模型在决策时能更快匹配。工具调用的失败处理也是重点。我的经验是给每个工具设置超时和重试上限超时后返回一个结构化的错误信息给模型让它自己决定是换工具还是放弃。不要直接抛异常中断循环那样 Agent 就“死”了。2.4 规划把大目标拆成可执行步骤规划能力决定了 Agent 能不能处理多步任务。我一般把规划分成两种模式前置规划和边做边规划。前置规划是在任务开始时让模型输出一个步骤列表适合步骤明确的任务边做边规划是每一轮根据当前状态决定下一步适合探索性任务。实际项目里我更多用混合模式先做一次粗粒度的前置规划得到 3 到 5 个大步骤然后在每个大步骤内部用边做边规划。这样既有全局方向又保留了灵活性。规划的输出格式我建议用结构化 JSON方便后续解析和校验。2.5 执行循环机制的核心执行就是 Agent 的主循环。一个典型的循环是观察当前状态 → 决定下一步动作 → 执行动作 → 更新状态 → 判断是否结束。这个循环看起来简单但每个环节都有坑。循环的终止条件必须明确。我一般设置三个终止条件达到最终目标、达到最大轮数、连续 N 轮无有效进展。最大轮数是硬性保护防止无限循环无进展检测是软性保护防止 Agent 在原地打转。这两个条件缺一不可。2.6 反思让 Agent 自己发现错误反思是 Agent 从错误中恢复的机制。我的做法是在每轮执行后加一个轻量的自检步骤让模型判断“上一步的结果是否推进了当前子目标”。如果判断为否就触发一次反思分析原因并调整策略。反思不要做得太重否则每轮都调用一次大模型成本会失控。我的经验是只在检测到异常时触发反思比如工具返回错误、结果为空、或者连续两轮动作相似。这样既控制了成本又保留了纠错能力。2.7 输出结果的整理与交付输出是 Agent 的最后一环但很多人会忽略它。Agent 跑完一堆步骤后如果直接把中间结果丢给用户体验会很差。我一般会加一个结果整理步骤把执行过程中的关键信息汇总成用户能直接用的格式。整理步骤的提示词要明确告诉模型“面向最终用户”去掉中间过程的噪声只保留结论和必要的依据。如果任务有多个交付物还要按优先级排序。3. 七个决策点Agent 工程实现中的关键取舍3.1 决策点一循环用固定轮数还是动态判断这是 Agent 工程的第一个岔路口。固定轮数实现简单但要么浪费要么不够动态判断灵活但需要额外的判断逻辑。我的选择是动态判断为主、固定轮数为辅。具体做法是主循环用动态判断每轮结束后让模型输出一个continue或stop的标志同时设置一个最大轮数作为硬性上限比如 20 轮。动态判断的提示词要写清楚“如果当前子目标已完成或无法继续输出 stop”。实测下来这种组合在大多数任务上都能在 5 到 10 轮内收敛。提示动态判断的标志位不要和工具调用混在一起输出分开两次调用更稳定虽然多花一点 token但解析逻辑简单很多。3.2 决策点二工具是预定义还是动态发现预定义工具就是提前写好工具列表Agent 从里面选动态发现是让 Agent 自己去找可用工具。前者可控后者灵活。我的建议是生产环境用预定义探索场景可以试动态发现。预定义工具的关键是控制数量。我试过给 Agent 挂 30 多个工具结果模型选择准确率明显下降。后来精简到 8 到 12 个核心工具准确率回升。如果工具确实多可以分组让 Agent 先选组再选工具。3.3 决策点三记忆存向量库还是结构化存储向量库适合语义检索结构化存储适合精确查询。我的经验是两者结合事实类、偏好类信息存结构化数据库文档类、对话类信息存向量库。检索时先查结构化没有再查向量库。向量库的坑主要在分块策略。块太大检索不精准块太小丢失上下文。我一般按语义段落分块每块 200 到 500 字块之间保留 20% 重叠。嵌入模型的选择上中文场景我倾向用专门优化过中文的模型通用模型在中文短文本上表现不稳定。3.4 决策点四规划用一次性还是增量式一次性规划适合步骤明确的任务比如“生成一份报告”增量式规划适合探索性任务比如“调研某个市场”。我的做法是默认增量式任务明确时切一次性。增量式规划的实现要点是每轮都要重新评估当前状态而不是机械执行初始计划。我见过不少 Agent 一开始规划得很好但执行中环境变了还在按老计划走结果越走越偏。每轮重新评估能避免这个问题。3.5 决策点五错误处理用重试还是降级工具调用失败时重试和降级是两种思路。重试适合临时性错误降级适合持续性错误。我的策略是先重试一次再降级。重试要设置退避时间不要立即重试否则可能连续失败。降级则是换一个更简单的方案比如搜索工具失败就改用缓存结果。降级方案要提前准备好不要等出错了才想。3.6 决策点六状态管理用内存还是外部存储内存状态实现简单但 Agent 重启就丢外部存储持久但增加复杂度。我的选择是开发阶段用内存生产环境用外部存储。外部存储我一般用 Redis 存短期状态用数据库存长期状态。状态的结构要设计好我通常分成task_state、step_history、tool_results三部分方便调试时定位问题。3.7 决策点七输出用原始结果还是二次加工原始结果直接返回实现简单但体验差二次加工体验好但多一次调用。我的做法是默认二次加工简单任务可跳过。二次加工的提示词要明确“面向用户”去掉中间过程。如果任务有格式要求还要在提示词里写清楚格式规范。我一般会让模型输出 Markdown 格式方便直接展示。4. 从零搭建一个最小可运行 Agent完整实操流程4.1 环境准备与依赖选择我用的技术栈是 Python OpenAI 兼容接口 Redis。Python 生态成熟调试方便OpenAI 兼容接口意味着可以换任何兼容的模型服务Redis 用来存状态和缓存。依赖清单如下pip install openai redis pydantic如果你用的是其他模型服务把openai换成对应的 SDK 即可。我建议用pydantic定义工具和状态的结构类型检查能帮你提前发现很多问题。4.2 定义工具与工具注册表工具定义我用一个字典来管理每个工具包含名称、描述、参数 schema 和执行函数。下面是一个搜索工具的示例from pydantic import BaseModel class SearchArgs(BaseModel): query: str top_k: int 5 def search_tool(query: str, top_k: int 5): # 实际搜索逻辑 return results TOOLS { search: { description: 搜索指定关键词返回相关文档列表适用于需要外部信息的场景, args_model: SearchArgs, func: search_tool } }工具描述我反复强调过要写清楚“做什么、输入什么、输出什么、什么时候用”。这四要素齐了模型选择准确率会高很多。4.3 实现主循环主循环是整个 Agent 的心脏。我的实现分成四步构造提示词、调用模型、解析动作、执行动作。def agent_loop(task, max_turns20): state init_state(task) for turn in range(max_turns): prompt build_prompt(state) response call_llm(prompt) action parse_action(response) if action.type stop: break result execute_action(action) state update_state(state, action, result) if no_progress(state): break return finalize(state)build_prompt负责把当前状态、工具列表、历史步骤拼成提示词。parse_action负责从模型输出里提取动作我一般要求模型输出 JSON解析失败时重试一次。no_progress检测连续两轮动作是否相似相似就中断。4.4 状态更新与记忆写入状态更新要区分短期和长期。短期状态每轮都更新长期记忆只在特定条件下写入。def update_state(state, action, result): state[step_history].append({ action: action, result: result }) if should_write_long_term(action, result): write_to_long_term(state[task_id], action, result) return stateshould_write_long_term的判断逻辑我一般让模型来做给它一个简单的提示词“这条信息是否值得长期保存只回答是或否”。这样能过滤掉大部分临时信息。4.5 终止条件与结果整理终止条件我设置三个模型输出 stop、达到最大轮数、连续无进展。结果整理用一个单独的 LLM 调用提示词里明确“面向用户去掉中间过程输出 Markdown”。def finalize(state): prompt f根据以下执行记录整理成面向用户的最终结果{state[step_history]} return call_llm(prompt)整理步骤的提示词里我还会加上“如果任务未完成说明原因和已完成部分”这样即使 Agent 中途停止用户也能知道发生了什么。5. 常见问题与排查技巧实录5.1 Agent 陷入无限循环怎么办无限循环是最常见的问题。排查思路是看step_history如果连续几轮动作相似基本可以确定是循环。解决方法有三个加无进展检测、加最大轮数、在提示词里明确“不要重复已执行的动作”。我遇到过一次循环是因为工具返回的结果格式和模型预期不一致模型反复尝试同一个工具。后来在工具描述里加了返回格式示例问题就解决了。5.2 工具调用总是选错工具怎么办工具选错通常是描述问题。排查方法是把工具描述单独拿出来让模型做一次“给定任务选择工具”的测试。如果准确率低就优化描述。我一般会做两件事一是把相似工具合并或明确区分二是给每个工具加“不适用场景”的说明。比如搜索工具加一句“不适用于查询本地文件”能减少误选。5.3 记忆检索不相关怎么优化检索不相关的原因通常是分块策略或嵌入模型的问题。排查方法是手动测试几个查询看返回的块是否相关。如果不相关先调分块大小再考虑换嵌入模型。我的经验是中文场景下分块按语义段落切比按固定长度切效果好很多。另外检索时可以加一个重排序步骤用一个小模型对候选块重新打分能明显提升相关性。5.4 Token 消耗过快怎么控制Token 消耗主要来自三块提示词、历史上下文、工具返回结果。控制方法分别是精简提示词、裁剪历史、截断工具返回。我一般会把工具返回结果截断到 500 字以内超出部分只保留摘要。历史上下文用滑动窗口加摘要能省不少 token。提示词方面去掉所有不必要的示例和说明只保留核心指令。5.5 常见问题速查表问题可能原因排查方法解决方向无限循环无进展检测缺失查看 step_history加检测和最大轮数工具选错描述不清晰单独测试工具选择优化描述加不适用场景检索不相关分块或嵌入问题手动测试查询调分块加重排序Token 过快上下文过长统计各部分 token裁剪历史截断返回结果质量差整理步骤缺失检查 finalize加整理提示词5.6 几个我踩过的坑第一个坑是工具描述里用了太多技术术语。模型对术语的理解不如自然语言稳定后来我改成用大白话描述准确率反而提升了。第二个坑是状态更新时覆盖了历史。早期我用字典直接赋值结果历史丢了。后来改成列表追加问题解决。第三个坑是反思步骤触发太频繁。一开始我每轮都反思成本翻倍。后来改成只在异常时触发成本降了一半效果没差。6. 工程化扩展从能跑到好用还差什么6.1 可观测性日志与追踪Agent 跑起来之后最需要的是能看清它每一步在干什么。我一般会记录三类日志提示词日志、动作日志、结果日志。提示词日志用于调试模型行为动作日志用于追踪决策路径结果日志用于评估效果。如果条件允许可以接入追踪系统把每一步的耗时、token 消耗、工具调用结果都记录下来。这样出问题时能快速定位是模型问题还是工具问题。6.2 评估怎么判断 Agent 好不好用评估 Agent 比评估普通模型复杂因为它有多步交互。我的做法是定义一组任务集每个任务有明确的成功标准然后跑一遍看成功率。成功标准可以是“最终结果包含关键信息”或“在 N 轮内完成”。除了成功率我还会看平均轮数和平均 token 消耗。这两个指标能反映效率。如果成功率高但轮数多说明规划能力有优化空间。6.3 安全工具调用的边界控制工具调用是 Agent 与外部交互的通道必须设边界。我的做法是给每个工具设置权限等级高风险工具需要额外确认。比如写文件、发请求这类工具我会加一个确认步骤让模型先输出计划再执行。另外工具的参数要做校验防止模型生成非法参数。我用 pydantic 做参数校验非法参数直接返回错误给模型让它重新生成。6.4 成本优化哪些环节可以省成本优化我一般从三个地方入手提示词精简、历史裁剪、模型分级。提示词精简是最直接的去掉所有不必要的说明。历史裁剪用滑动窗口加摘要。模型分级是把简单任务交给小模型复杂任务才用大模型。我试过把工具选择交给小模型执行交给大模型成本降了大概 40%效果基本没差。这个思路值得一试。6.5 后续可以扩展的方向如果基础版本跑通了可以考虑几个扩展方向多 Agent 协作把不同职责拆给不同 Agent工具动态发现让 Agent 自己注册新工具长期记忆优化引入更精细的检索和重排序。不过我的建议是先把单 Agent 跑稳再考虑多 Agent。多 Agent 的协调成本很高单 Agent 没跑好就上多 Agent很容易失控。最后分享一个我在实际项目里总结的小技巧每次修改 Agent 逻辑后先用固定任务集跑一遍回归测试。Agent 的行为很容易被一个小改动影响回归测试能帮你快速发现意外变化。这个习惯帮我省了很多调试时间。