.NET C# SubAgent 多智能体架构独立 Kernel 设计与编排系列.NET C# Semantic Kernel 集成深度解析 ⑥/6完结篇难度⭐⭐⭐进阶源码需.NET基础源码仓库github.com/zongge0812/zonggeAgent适用环境.NET 9.0 WPF一、引言多智能体Multi-Agent架构是 AI 应用从单兵作战走向团队协奏的关键一步。zonggeAgent 的 SubAgent 设计遵循一个核心理念主 Agent 负责协调和决策SubAgent 负责执行具体任务——每个 SubAgent 拥有独立的 Kernel 和工具调用上下文。┌─────────────────────────────────────────────────────────────┐ │ 场景示例 │ │ │ │ 用户帮我分析这个项目的架构生成一份报告 │ │ │ │ 主Agent 接到任务 → 拆解为 3 个子任务 │ │ ├─ SubAgent①扫描项目目录结构FileToolRead │ │ ├─ SubAgent②分析代码架构ArchitectureRecognition │ │ └─ SubAgent③生成报告文档DocumentGeneration │ │ │ │ 主Agent 汇总 3 个 SubAgent 的结果 → 返回给用户 │ └─────────────────────────────────────────────────────────────┘二、SubAgentService 整体架构SubAgent 服务通过ISubAgentService接口暴露由SubAgentService类实现。2.1 接口设计// ISubAgentService.cspublicinterfaceISubAgentService{TaskSubAgentResponseExecuteAsync(SubAgentRequestrequest,CancellationTokencancellationTokendefault);voidUpdateWorkspaceSnapshot(string?workspacePath);string?GetCurrentWorkspacePath();}接口非常精简——只暴露了执行对话和工作区管理两个核心能力。2.2 类结构SubAgentService │ ├── 状态 │ ├── _subAgentKernel ← 独立 Kernel缓存模式切换时重置 │ ├── _currentWorkspaceSnapshot ← 继承主 Agent 的工作区 │ ├── _currentChatMode ← 当前模式Chat / Development │ └── _settingsService ← 配置服务 │ └── _providerFactory ← Provider 工厂 │ ├── 核心方法 │ ├── ExecuteAsync() ← 入口执行 SubAgent 对话 │ ├── CreateSubAgentKernelAsync()← 创建独立 Kernel │ ├── LoadSubAgentTools() ← 加载子 Agent 专用工具 │ └── ExecuteConversationWithToolsAsync() ← 带工具调用的对话执行 │ ├── 辅助方法 │ ├── BuildEnhancedSystemPrompt() ← 构建系统提示含模式说明 │ ├── BuildUserPrompt() ← 构建用户提示 │ ├── CreateSubAgentExecutionSettings() ← 工具调用配置 │ ├── ExecuteFallbackConversationAsync() ← 工具失败回退 │ ├── IsContentComplete() ← 是否完成检测 │ ├── IsNonRetryableError() ← 不可重试错误检测 │ └── EstimateTokens() ← Token 估算 │ └── 公共方法 ├── UpdateWorkspaceSnapshot() ← 更新工作区快照 ├── UpdateChatMode() ← 更新模式重置 Kernel 缓存 └── GetCurrentWorkspacePath() ← 获取当前工作区三、独立 Kernel 设计SubAgent 拥有完全独立的 Kernel不共享主 Agent 的 Kernel。3.1 Kernel 创建privateasyncTaskKernelCreateSubAgentKernelAsync(AIProviderConfigproviderConfig,IAIProviderServiceproviderService,CancellationTokencancellationTokendefault){// 缓存如果 Kernel 已存在直接返回if(_subAgentKernel!null){return_subAgentKernel;}// 创建新的 Kernel_subAgentKernelnewKernel();// 加载子 Agent 专用工具LoadSubAgentTools(_subAgentKernel);return_subAgentKernel;}3.2 Kernel 缓存与重置事件Kernel 状态行为首次调用未创建创建新 Kernel后续调用已缓存直接返回避免重复创建模式切换重置为 null_subAgentKernel null下次调用重新创建publicvoidUpdateChatMode(ChatModemode){_currentChatModemode;// 模式切换时重置 Kernel 缓存下次调用时重新创建并加载对应工具集_subAgentKernelnull;}为什么要重置 Kernel因为不同模式下需要加载不同的工具集聊天模式移除写插件。不重置的话切换到聊天模式后写插件仍然存在。3.3 工具加载privatevoidLoadSubAgentTools(Kernelkernel){// ① 热加载所有插件PluginLoader 负责扫描和注册PluginLoader.RegisterPlugin(kernel);// ② 在 Kernel 中注入模式信息供后续使用kernel.Data.Add(ChatMode,_currentChatModeChatMode.Chat?Chat:Development);}与主 Agent 的工具加载对比对比项主 AgentSubAgent工具来源PluginLoader 热加载✅ 同左Kernel 生命周期每次对话重建✅ 缓存重用模式过滤ApplyChatModeFilter❌ SubAgent 自行控制Tools 接口通过 ITools 标记✅ 同左四、对话执行完整流程4.1 ExecuteAsync 入口publicasyncTaskSubAgentResponseExecuteAsync(SubAgentRequestrequest,CancellationTokencancellationTokendefault){varstopwatchStopwatch.StartNew();try{// ① 获取配置的 Providervar(providerConfig,providerService)GetConfiguredProvider();if(providerConfignull||providerServicenull){returnSubAgentResponse.Error(AI提供商未正确配置);}// ② 确定工作区路径继承主 Agent 的vareffectiveWorkspacerequest.WorkspacePath??_currentWorkspaceSnapshot??WorkspaceBridge.CurrentWorkspacePath;// ③ 执行对话带工具调用varresultawaitExecuteConversationWithToolsAsync(request,providerConfig,providerService,effectiveWorkspace,cancellationToken);result.ExecutionTimeMsstopwatch.ElapsedMilliseconds;result.ProviderTypeproviderConfig.ProviderType;returnresult;}catch(Exceptionex){varerrorResponseSubAgentResponse.Error($Sub Agent执行失败:{ex.Message});errorResponse.ExecutionTimeMsstopwatch.ElapsedMilliseconds;returnerrorResponse;}}4.2 执行链路全景用户触发 SubAgent ↓ ExecuteAsync() ├─ GetConfiguredProvider() → 获取当前 AI Provider ├─ 确定工作区路径 → 主 Agent → 快照 → WorkspaceBridge └─ ExecuteConversationWithToolsAsync() │ ├─ CreateSubAgentKernelAsync() → 创建/获取缓存 Kernel │ └─ LoadSubAgentTools() → PluginLoader 加载工具 │ ├─ 重试循环maxRetries 次 │ ├─ BuildEnhancedSystemPrompt() → 构建系统提示 │ ├─ BuildUserPrompt() → 构建用户提示 │ ├─ 上下文体积检查 → EstimateTokens() │ ├─ 创建 SubAgent 执行设置 → CreateSubAgentExecutionSettings() │ ├─ providerService.SendMessageAsync() → 调用 AI │ ├─ 检查是否完成 → IsContentComplete() │ └─ 如果工具调用失败 → ExecuteFallbackConversationAsync() │ └─ 返回 SubAgentResponse4.3 重试机制对话执行采用重试循环不是一次调用就结束while(currentRetrymaxRetries){// 连续失败检测if(consecutiveFailuresmaxConsecutiveFailures){returnSubAgentResponse.Error($连续失败{consecutiveFailures}次);}// 执行对话...varresponseawaitproviderService.SendMessageAsync(...);if(!string.IsNullOrEmpty(response.Content)){collectedContent.Append(response.Content);consecutiveFailures0;// 重置连续失败计数// 检查是否完成if(IsContentComplete(response.Content,collectedContent.ToString())){returnSubAgentResponse.Success(collectedContent.ToString(),true);}}else{consecutiveFailures;}}重试策略参数值说明maxRetries从 SubAgentRequest 传入最大重试次数maxConsecutiveFailures3连续失败 3 次立即终止IsContentComplete()智能检测判断是否已收集到完整内容4.4 不可重试错误检测if(IsNonRetryableError(ex)){// 永不重试的错误类型returnSubAgentResponse.Error($检测到不可重试错误:{ex.Message});}// 可重试等待下次循环尝试4.5 工具调用失败的自动回退try{varresponseawaitproviderService.SendMessageAsync(userPrompt,chatHistory,providerConfig,executionSettings);// ...}catch(Exceptionex){// 工具调用失败 → 自动回退到纯文本对话varfallbackResponseawaitExecuteFallbackConversationAsync(request,providerConfig,providerService,workspacePath);if(!string.IsNullOrEmpty(fallbackResponse.Content)){collectedContent.Append(fallbackResponse.Content);consecutiveFailures0;}}五、SubAgent 的执行设置SubAgent 拥有独立的ExecutionSettings配置根据模式自动选择不同的工具调用行为privatePromptExecutionSettingsCreateSubAgentExecutionSettings(AIProviderConfigconfig){// 聊天模式让 AI 看到工具但需要明确请求才调用// 开发模式自动调用工具正常读写vartoolBehavior_currentChatModeChatMode.Chat?ToolCallBehavior.EnableKernelFunctions:ToolCallBehavior.AutoInvokeKernelFunctions;returnnewOpenAIPromptExecutionSettings{MaxTokensconfig.MaxTokens,Temperature(float)config.Temperature,ToolCallBehaviortoolBehavior};}重要差异模式主 Agent 的 ToolCallBehaviorSubAgent 的 ToolCallBehavior 聊天AutoInvokeKernelFunctions插件被 Kernel 移除写工具EnableKernelFunctionsAI 看到工具但不自动调用 开发AutoInvokeKernelFunctions全自动AutoInvokeKernelFunctions全自动为什么聊天模式下 SubAgent 使用EnableKernelFunctions而非主 Agent 的AutoInvokeKernelFunctions主 Agent 通过ApplyChatModeFilter物理移除了写插件SubAgent 通过EnableKernelFunctions让 AI 可以看见工具但不会自动调用双重保险即使写插件存在也不会被自动调用六、提示词构造SubAgent 的提示词构造非常完整包含 3 个核心部分6.1 系统提示BuildEnhancedSystemPromptprivatestringBuildEnhancedSystemPrompt(SubAgentRequestrequest,string?workspacePath){varbasePromptrequest.CustomSystemPrompt;// ① 模式说明最优先展示if(_currentChatModeChatMode.Chat){basePrompt当前模式聊天模式只读模式只看不写...;}else{basePrompt当前模式开发模式读写全开...;}// ② 工作区信息继承主 Agentif(!string.IsNullOrEmpty(workspacePath)){basePrompt$\n**当前工作区**{workspacePath};}// ③ 工具使用指南basePrompt工具使用指南节能高效...;returnbasePrompt;}6.2 上下文体积保护varestimatedTokensEstimateTokens(chatHistory.ToString()userPrompt);constintmaxTokens900000;// 留 10% 安全余量if(estimatedTokensmaxTokens){returnSubAgentResponse.Error($上下文Token数过大{estimatedTokens}超过{maxTokens}限制);}设置 900,000 Token 的安全上限超过则立即报错而不是悄悄截断。七、SubAgentRequest 与 SubAgentResponse7.1 请求模型字段类型说明AgentNamestringSubAgent 名称日志标识UserMessagestring用户消息Contextstring?上下文信息WorkspacePathstring?工作区路径不传则继承主 AgentMaxRetriesint最大重试次数CustomSystemPromptstring?自定义系统提示7.2 响应模型字段类型说明Contentstring响应内容IsSuccessbool是否成功IsCompletebool是否完成AgentNamestringAgent 名称ExecutionTimeMslong执行耗时 msProviderTypeAIProviderType使用的 Provider八、安全性设计SubAgent 的安全设计体现在3 层防护层级防护措施说明第 1 层独立 KernelSubAgent 不共享主 Agent 的 Kernel互不干扰第 2 层模式感知的 ToolCallBehavior聊天模式使用EnableKernelFunctions不自动调用工具第 3 层连续失败检测连续 3 次失败立即终止防止级联故障九、UnifiedChatService 中的 SubAgent 调用在UnifiedChatService中SubAgent 通过统一的IAIProviderService接口调用与主 Agent 共享 Provider 配置UnifiedChatService.SendMessageAsync() │ ├─ 判断是否需要 SubAgent │ ├─ 否 → 直接使用当前 Provider 对话 │ └─ 是 → SubAgentService.ExecuteAsync() │ ├─ 继承 Provider 配置GetConfiguredProvider │ ├─ 继承工作区路径 │ ├─ 创建独立 Kernel │ └─ 执行对话 工具调用 │ └─ 返回最终结果十、系列总结第2系列全篇回顾期次标题核心源码关键知识点①SK 核心概念与架构设计BaseAIProviderService, UnifiedAIServiceSK 三件套、6层架构、模板方法②多 AI Provider 统一接入方案AIProviderFactory, 6个Provider工厂模式、模板方法、连接器差异③插件热加载机制PluginLoaderDLL扫描、反射加载、AddFromObject④工具调用与 Function CallingBaseAIProviderService 中 ToolCall 部分ToolCallBehavior、自动调用链路⑤流式响应与性能优化BaseAIProviderService 流式部分, StreamingOptimizationServiceIAsyncEnumerable、Token追踪、智能分块⑥SubAgent 多智能体架构SubAgentService独立Kernel、重试机制、回退对话本系列核心源码文件索引文件路径行数核心职责IAIProviderService.csServices/Interfaces/52统一接口契约BaseAIProviderService.csServices/Abstract/539模板方法基类流式/非流式/Token追踪AIProviderFactory.csServices/Implementations/51工厂模式创建ProviderDeepSeekAIProviderService.csServices/Implementations/59DeepSeek Provider 实现ClaudeAIProviderService.csServices/Implementations/57Claude Anthropic 连接器OllamaAIProviderService.csServices/Implementations/55Ollama 本地模型PluginLoader.csTools/Implementations/258插件热加载核心StreamingOptimizationService.csServices/Implementations/365流式优化 智能分块PerformanceMonitorService.csServices/Implementations/-性能监控SubAgentService.csServices/Implementations/648多Agent架构UnifiedAIService.csServices/-统一入口UnifiedChatService.csServices/-统一对话服务源码仓库github.com/zongge0812/zonggeAgent首发CSDN · zonggeAgent 技术专栏