从一次诡异的 Planner 死循环说起上个月帮一个做工业质检的团队调 Semantic Kernel他们的 Agent 在调用一个“检测结果汇总”的 Plugin 时Planner 突然开始疯狂重试同一个步骤。日志里反复出现“Plan execution failed, retrying with adjusted context”但每次重试的 Plan 一模一样连参数都没变。我盯着日志看了半小时最后发现是 Memory 里存了一条过期的工作流缓存Planner 每次读取 Memory 时都拿到了同一个“最优解”而这个最优解里调用的 Plugin 接口已经废弃了。这个坑让我意识到Semantic Kernel 的三大组件——Planner、Plugin、Memory——表面上是独立模块实际运行时是深度耦合的。任何一个环节的配置失误都会让整个 Agent 陷入诡异的“假死”状态。今天这篇笔记我就从这三个组件的底层逻辑和实战踩坑点展开不讲官方文档里那些漂亮的架构图只讲你写代码时真正会撞上的墙。Plugin别把 Function 当 API 封装很多人第一次接触 Semantic Kernel 的 Plugin会下意识把它当成“给 LLM 调用的 API 封装”。这个理解没错但太浅了。Plugin 的核心价值不在于“把函数暴露给 AI”而在于“让 AI 理解这个函数什么时候该用、怎么用、用了会有什么副作用”。我见过最典型的错误写法是这样的[KernelFunction][Description(获取当前时间)]publicstringGetCurrentTime(){returnDateTime.Now.ToString(yyyy-MM-dd HH:mm:ss);}这段代码能跑但实际效果很差。因为 LLM 在 Planner 里做决策时它不光要知道“这个函数能获取时间”还需要知道“这个时间是什么时区的”“精度到秒还是毫秒”“是否适合用于日志记录”。你给的信息越模糊Planner 就越容易在错误的场景下调用这个 Plugin。正确的做法是给足“语义上下文”[KernelFunction][Description(获取系统当前本地时间适用于日志记录和任务调度)][return:Description(格式为 yyyy-MM-dd HH:mm:ss 的本地时间字符串时区为系统默认时区)]publicstringGetCurrentTime(){// 这里踩过坑之前直接返回 UTC 时间导致 Planner 在计算任务截止时间时算错了 8 小时returnDateTime.Now.ToString(yyyy-MM-dd HH:mm:ss);}别小看这些 Description 和 return 的注释。Semantic Kernel 在序列化 Plugin 元数据时会把这些信息原封不动地塞进给 LLM 的 Prompt 里。你写得越详细LLM 的决策就越精准。还有一个容易被忽略的点Plugin 的参数类型。尽量用 string、int、bool 这些基础类型别用复杂对象。因为 LLM 在生成 JSON 参数时对嵌套对象的理解能力远不如对扁平结构的理解。如果你非要用自定义类记得在类上加[Description]和[JsonPropertyDescription]否则 LLM 可能会把字段名理解错。Planner它不是万能的调度器Planner 是 Semantic Kernel 里最容易被神化的组件。很多人以为 Planner 能像人类一样“理解任务、拆解步骤、自动编排”实际上它只是一个“基于 LLM 的步骤生成器 执行引擎”。它的核心逻辑很简单给你一个目标你生成一个步骤列表然后按顺序执行失败了就重试或回滚。但就是这个“简单逻辑”在实际项目中坑最多。第一个坑Planner 的上下文窗口限制。默认的 SequentialPlanner 会把所有 Plugin 的元数据、历史对话、Memory 内容全部塞进一个 Prompt 里。如果你的 Plugin 数量超过 20 个或者 Memory 里存了大量长文本LLM 的上下文窗口很容易被撑爆。这时候 Planner 会开始“失忆”——它可能只看到了前 10 个 Plugin然后生成一个残缺的 Plan。解决方案是手动控制 Plugin 的可见范围varplannernewSequentialPlanner(kernel,newPlannerOptions{// 别这样写var planner new SequentialPlanner(kernel); 默认会加载所有 PluginAvailableFunctionskernel.Plugins.GetFunctionsMetadata().Where(ff.PluginNameDataProcessing||f.PluginNameLogging).ToList()});第二个坑Planner 的“过度自信”。当 LLM 遇到一个它不确定的任务时它倾向于“编造”一个步骤而不是承认自己不会。比如你让 Planner 执行一个“计算圆周率到第 1000 位”的任务它可能会生成一个“调用 CalculatePi 函数”的步骤但实际上你的 Plugin 里根本没有这个函数。执行时就会报错然后 Planner 重试再报错陷入死循环。我现在的做法是在 Plugin 里加一个“兜底函数”专门处理 Planner 无法匹配的任务[KernelFunction][Description(当其他所有函数都无法满足用户需求时调用此函数返回错误信息)]publicstringFallbackHandler([Description(用户原始请求)]stringuserRequest){// 这里踩过坑之前直接返回无法处理导致 Planner 反复重试return$无法处理请求{userRequest}。请检查 Plugin 配置或提供更具体的指令。;}然后在 Planner 的配置里把这个 FallbackHandler 的优先级设到最低确保它只在其他所有选项都失败时才被调用。Memory别把它当数据库用Semantic Kernel 的 Memory 模块官方文档里吹得天花乱坠——什么“长期记忆”“语义搜索”“自动摘要”。但实际用起来它就是一个“带向量索引的键值存储”只不过索引是基于语义相似度而不是精确匹配。我见过最离谱的用法是有人把整个项目的配置文件、数据库 Schema、甚至用户隐私数据都塞进 Memory 里然后指望 Planner 能“智能地”从中提取需要的信息。结果就是 Memory 的向量索引被大量无关数据污染Planner 每次查询都返回一堆噪音最终生成的 Plan 完全跑偏。Memory 的正确用法是“只存 Agent 需要记住的上下文”而不是“存所有可能用到的数据”。比如用户在当前对话中提到的偏好“我喜欢用 JSON 格式输出”之前任务执行的结果摘要“上次处理了 100 条记录耗时 2.3 秒”需要跨对话保持的状态“用户已授权访问数据库”这些信息的特点是体积小、语义明确、对后续决策有直接影响。还有一个容易被忽略的点Memory 的过期策略。默认的 SemanticTextMemory 没有自动过期机制你存进去的数据会永远留在那里。如果用户今天说“我喜欢红色”明天说“我喜欢蓝色”Memory 里就会同时存在两条矛盾的信息。Planner 在查询时如果两条信息的相似度都很高它可能会随机选择一条导致行为不一致。我现在的做法是每次写入 Memory 时先删除同类型的旧记录// 别这样写await memory.SaveInformationAsync(UserPreferences, color, blue);// 这样会保留旧记录导致冲突// 正确的做法先删除再写入awaitmemory.RemoveAsync(UserPreferences,color);awaitmemory.SaveInformationAsync(UserPreferences,color,blue);三者的协作一个真实的调试案例回到文章开头那个死循环问题。当时我排查的步骤是这样的先看 Planner 生成的 Plan 日志发现每次重试的 Plan 完全一样说明问题不在 Planner 的生成逻辑而在“它为什么认为这个 Plan 是正确的”。检查 Plugin 的元数据发现那个废弃接口的 Description 里写着“推荐使用新接口 V2”但 Planner 在读取 Memory 时拿到了一条旧的工作流缓存里面明确写着“处理检测结果时调用旧接口”。问题出在 Memory 的写入逻辑之前的工作流缓存没有设置过期时间也没有在接口更新时自动失效。Planner 每次查询 Memory都优先返回了这条“高相似度”的旧缓存。修复方案在 Memory 的写入逻辑里给每条缓存加一个“版本号”字段并在查询时过滤掉过期版本。同时在 Plugin 的元数据里明确标注“此接口已废弃请勿使用”这样即使 Planner 误调用了也能在第一步就报错退出而不是陷入死循环。这个案例说明Planner、Plugin、Memory 三者不是独立的它们通过“语义”这个纽带紧密耦合。任何一个环节的语义信息不准确都会导致整个系统行为异常。个人经验性建议Plugin 的 Description 要写“场景”而不是“功能”。比如“获取当前时间”不如“获取当前本地时间用于日志记录和任务调度”。LLM 理解场景比理解功能更容易。Planner 的失败重试次数不要超过 3 次。超过 3 次还失败说明 Plan 本身有问题重试只会浪费 Token。不如直接返回错误让上层逻辑处理。Memory 的向量维度不要超过 1536。OpenAI 的 text-embedding-ada-002 默认就是 1536 维你用更高的维度不仅不会提升精度反而会增加计算开销。永远给 Planner 一个“我不知道”的选项。在 Plugin 里加一个 FallbackHandler或者在 Planner 的 Prompt 里明确告诉 LLM“如果你不确定如何完成任务请直接说不知道不要编造步骤。”日志里记录每一步的“决策依据”。不要只记录“调用了哪个函数”还要记录“为什么调用这个函数”。这样当 Agent 行为异常时你能快速定位是 Planner 的决策问题还是 Plugin 的执行问题。别迷信“全自动”。Semantic Kernel 的 Planner 再智能也只是个“半自动”工具。对于关键业务逻辑我建议手动编写 Plan 模板让 Planner 只在模板内做参数填充而不是完全自由发挥。最后说一句Semantic Kernel 是个好框架但它不是银弹。它的设计哲学是“给 LLM 足够的自由度”但自由度越大不可控因素就越多。你在用它的同时必须时刻想着“如果 LLM 在这里犯错了我的系统会怎样”。只有把容错机制做扎实了Agent 才能真正落地到生产环境。