Microsoft Agent Framework：.NET AI应用的范式重构与迁移实践

1. 这不是一次简单升级，而是一次底层思维的重置

如果你最近翻过微软官方博客、GitHub仓库更新日志，或者关注过.NET开发者社区里那些技术分享会的议程，大概率已经看到“Microsoft Agent Framework”这个新名字反复出现。它不是Semantic Kernel的v2.0补丁，也不是一个功能增强包——它是微软在AI原生应用开发范式上，用.NET生态重新画的一条起跑线。我从去年底开始跟进Semantic Kernel（SK）的v1.0稳定版落地项目，参与过三个不同规模的智能体（Agent）原型开发：一个是某高校实验室的科研文献辅助分析系统，一个是某制造企业的设备故障知识库问答前端，还有一个是面向内部员工的IT服务自助助手。这些项目都基于SK构建，用的是其经典的Planner + Orchestrator + Memory三层抽象，配合OpenAI或Azure OpenAI的模型调用。但到了今年Q2，当MSAF的预览版文档和示例代码公开后，我立刻停掉了两个在研项目的SK依赖，把核心逻辑全部重构进MSAF的Pipeline模型里。为什么？因为这不是“换个SDK”，而是整个开发心智模型的切换：SK教会你如何把大模型能力“组装”进现有系统；MSAF则直接定义了“系统”本身该长什么样——它把Agent从一个被调用的组件，变成了整个应用的运行时骨架。

这个标题里的三个关键词，“重构”、“继承”、“超越”，每个词背后都有实打实的工程代价和设计取舍。所谓“重构”，是指MSAF不再兼容SK的Kernel实例、FunctionCollection注册方式、甚至PromptTemplateConfig的序列化格式；所谓“继承”，不是API层面的向后兼容，而是对SK已验证的核心思想——比如函数调用（Function Calling）、记忆管理（Memory Management）、规划能力（Planning）——进行了概念级保留与语义升维；所谓“超越”，体现在它引入了SK从未考虑过的维度：可观察性（Observability）原生支持、跨模型协议抽象（Model Agnosticism）、以及最关键的——状态驱动的执行生命周期（State-Driven Execution Lifecycle）。这意味着你写的每一个Agent，从创建、初始化、接收输入、触发动作、保存状态、到最终销毁，每一步都在框架的统一调度器（Scheduler）下完成，而不是像SK那样靠开发者手动编排InvokeAsync调用链。这种变化带来的直接影响是：以前需要写30行胶水代码来处理错误重试+上下文传递+日志埋点的流程，在MSAF里可能只需要配置一个RetryPolicy和一个TelemetryOptions对象。我试过把一个原本用SK实现的、包含5个自定义函数和2层嵌套规划的客服意图识别模块，迁移到MSAF后，核心业务代码行数减少了42%，而可观测性指标（如单次请求耗时分布、函数失败率、LLM token消耗趋势）却能直接从内置仪表盘里拉出来，不需要再自己搭Prometheus+Grafana。

适合谁读这篇？如果你正在用SK做POC但卡在生产部署的可观测性瓶颈上；如果你的团队已经开始为不同客户定制多个Agent，却苦于无法统一管理它们的版本、配置和状态；或者你只是好奇“微软到底想让.NET开发者怎么写AI应用”，那这篇就是为你写的。它不讲PPT上的战略愿景，只讲我在真实项目里删掉的每一行代码、改掉的每一个接口、以及踩过的那些文档里根本没提的坑。

2. 核心设计思路：从“函数编排”到“状态机驱动”的范式迁移

2.1 Semantic Kernel的遗产：为什么它曾是最佳解？

要理解MSAF为何要重构，得先看清SK解决了什么、又留下了什么。SK诞生于2022年中，彼时大模型刚爆火，开发者最痛的点是：如何让LLM不只是聊天，而是能真正调用系统能力？SK给出的答案很务实——用“技能（Skills）”封装业务逻辑，用“规划器（Planners）”让LLM学会拆解任务，再用“内存（Memory）”帮它记住上下文。它的核心抽象非常清晰：

• Kernel：全局容器，管理所有注册的函数和插件；
• Function：一个带描述、参数、执行逻辑的可调用单元，比如GetWeather(string city)；
• Planner：接收用户输入，生成调用Function的步骤序列（JSON格式），再逐个执行；
• Memory：基于向量数据库的短期/长期记忆存储，供LLM检索。

这套设计在当时极具开创性。我最早做的那个科研文献分析系统，就是靠SK的SequentialPlanner自动把“对比A和B两篇论文的方法论差异”拆成：1）提取论文A方法论段落；2）提取论文B方法论段落；3）调用自定义的CompareMethodology函数生成对比报告。整个流程完全由LLM驱动，开发者只需写好三个函数，连if-else都不用写。但问题也出在这里：SK把“决策权”完全交给了LLM，而把“执行权”留给了开发者。这意味着：

• 每次调用Planner生成的步骤，你得自己解析JSON、校验参数、捕获异常、记录日志；
• 如果某个函数执行失败（比如天气API超时），重试逻辑、降级策略、状态回滚，全得手写；
• 多轮对话中，用户突然问“刚才说的第三点能再解释下？”，你需要自己维护对话历史、定位上下文、再喂给LLM——SK的Memory只负责存，不负责“理解”什么是“刚才”。

这些不是缺陷，而是设计选择：SK定位是“LLM能力集成工具包”，不是“AI应用运行时”。它假设你已有成熟的应用架构，只需要一块拼图。但现实是，越来越多的项目发现：这块拼图越来越大，最后整张画都得重画。

2.2 Microsoft Agent Framework的破局点：把Agent变成一等公民

MSAF的破局，始于一个根本性提问：“如果Agent本身就是应用，那它的‘进程’该是什么？”答案是：一个有明确定义状态、可被调度、可被观测、可被持久化的运行实体。这直接催生了MSAF的四大支柱设计：

1. Agent生命周期（Agent Lifecycle）：每个Agent实例从Created→Initialized→Running→Paused→Completed/Failed，状态变更由框架内建的AgentScheduler统一管理。你不用再写try-catch去捕获执行失败，而是订阅OnFailed事件，框架会自动触发状态流转并提供失败快照（含输入、中间状态、错误堆栈）。

2. Pipeline执行模型（Pipeline Execution Model）：取代SK的“函数调用链”，MSAF用PipelineStep定义原子操作，每个Step可声明输入/输出契约、执行超时、重试策略、熔断阈值。比如一个ValidateInputStep可以配置：失败3次后跳过，且将错误信息注入后续Step的上下文。这比SK里手动写if (result.IsSuccess) { ... } else { ... }直观得多。

3. 模型无关协议（Model-Agnostic Protocol）：SK的IAIService接口绑定具体模型提供商（如OpenAIChatCompletionService），换模型就得改代码。MSAF抽象出IModelClient，所有模型调用都走统一的InvokeAsync<TRequest, TResponse>泛型方法，请求/响应结构由ModelContract定义。我们团队上周刚把一个Azure OpenAI部署的Agent，无缝切到本地Ollama的Llama3-70B模型上，只改了两行配置——services.AddModelClient<OllamaClient>(options => { options.BaseUrl = "http://localhost:11434"; });，其余业务逻辑零修改。

4. 原生可观测性（Native Observability）：这不是加个ILogger那么简单。MSAF内置AgentTelemetry，自动采集：每个Step的执行耗时、LLM调用的prompt/completion token数、缓存命中率、外部服务调用延迟。更关键的是，它把这些指标和Agent的CorrelationId、SessionId、UserId强绑定，你能在Kibana里直接查“用户U123在会话S456中，第3次调用时ProcessOrderStep的token消耗为何突增200%？”——这种粒度，SK靠自己埋点根本做不到。

这个设计不是为了炫技。它直指企业级AI应用的三大刚需：可运维（能快速定位线上问题）、可治理（能统一管控模型调用成本与合规性）、可扩展（能平滑接入新模型与新能力）。我参与的那个IT服务助手项目，上线后第一周就发现：Azure OpenAI的gpt-4-turbo模型在处理“重置密码”类请求时，token消耗是其他请求的5倍。在SK架构下，我们花了两天时间加日志、改监控、写聚合脚本才定位到是某个提示词模板里包含了冗余的系统权限说明。而在MSAF里，这个问题在第二天晨会上，运维同事直接打开仪表盘截图就指出了根因——根本不用开发介入。

2.3 战略整合的深层逻辑：为什么不是取代，而是收编？

标题里“战略整合”这个词很关键。MSAF没有把SK扔进废纸篓，而是把它“收编”进了自己的体系。具体怎么做？看三个层面：

• 能力层收编：SK的所有核心能力（Function Calling、Memory、Planning）都被重构为MSAF的BuiltInCapability。比如SK的SemanticFunction，在MSAF里对应IActionCapability，但调用方式变了——你不再kernel.InvokeAsync("MySkill.MyFunc", input)，而是agent.ExecuteAsync(new ActionStep("MySkill.MyFunc", input))。接口变了，但能力内核没丢。

• 生态层收编：SK庞大的插件市场（Plugins Gallery）没有消失，而是被映射为MSAF的PluginPackage。微软提供了SkPluginConverter工具，能自动把SK的.json插件定义转成MSAF的PluginManifest.yaml。我们迁移时，直接把原来SK项目里的plugins/目录拖进MSAF工程，运行转换命令，就生成了可直接引用的NuGet包。

• 心智层收编：这是最精妙的。MSAF保留了SK最成功的“低代码”体验——你依然可以用YAML定义Agent行为。但YAML的语义升级了。比如SK里定义一个天气查询函数：

  # SK style functions: - name: GetWeather description: Get current weather for a city parameters: - name: city type: string

  在MSAF里，它变成：

  # MSAF style capabilities: - type: action name: GetWeather description: Get current weather for a city inputs: - name: city type: string execution: timeout: 30s retry: maxAttempts: 3 backoff: exponential

  看到了吗？同一份业务意图，MSAF的YAML多出了execution块——这就是范式迁移的具象化：从“描述功能”到“定义行为契约”。它强迫你在设计阶段就思考：这个能力该超时多久？失败了重试几次？要不要熔断？这些不再是上线后被逼着补的运维需求，而是设计契约的一部分。

这种整合不是妥协，而是微软对.NET AI生态现状的精准判断：大量现有项目基于SK，强行割裂只会造成生态撕裂；但若不重构，又无法支撑未来三年的企业级AI应用浪潮。所以，它选择了一条最难的路——用新范式兼容旧资产，让开发者在迁移中自然完成心智升级。

3. 核心细节解析：从SK到MSAF，你必须重写的5个关键环节

3.1 Agent初始化：从Kernel注册到Dependency Injection容器的彻底接管

在SK里，初始化一个Agent通常这样写：

var kernel = new KernelBuilder() .WithOpenAIChatCompletion("gpt-4", "your-key", "https://your-endpoint.openai.azure.com/") .Build(); // 注册自定义函数 kernel.ImportFunctions(new MyWeatherPlugin(), "weather"); // 注册内存 kernel.RegisterMemoryStore(new VolatileMemoryStore());

这里Kernel是中心枢纽，所有能力都往它身上“挂”。而MSAF彻底抛弃了这种中心化模式，转向.NET原生的IServiceCollection依赖注入容器。迁移第一步，就是把所有Kernel相关的初始化代码，重构成标准的DI注册：

// MSAF style - Program.cs var builder = WebApplication.CreateBuilder(args); // 1. 注册模型客户端（替代SK的WithOpenAIChatCompletion） builder.Services.AddModelClient<OpenAIChatClient>(options => { options.ModelId = "gpt-4-turbo"; options.ApiKey = builder.Configuration["OpenAI:ApiKey"]; options.Endpoint = builder.Configuration["OpenAI:Endpoint"]; }); // 2. 注册Agent能力（替代SK的ImportFunctions） builder.Services.AddAgentCapability<MyWeatherCapability>("weather"); builder.Services.AddAgentCapability<MyOrderCapability>("order"); // 3. 注册内存提供者（替代SK的RegisterMemoryStore） builder.Services.AddSingleton<IMemoryProvider, AzureCosmosMemoryProvider>(); // 4. 注册Agent本身（这才是真正的“Agent”） builder.Services.AddAgent<MyCustomerSupportAgent>("customer-support");

提示：AddAgent<TAgent>是关键。它不仅注册了Agent类型，还自动注册了其依赖的IModelClient、IMemoryProvider、IActionCapability等所有组件。你再也不用担心“忘了注册内存导致Agent启动报空引用”这种低级错误——DI容器会在启动时做完整依赖图校验。

为什么这么设计？因为MSAF认为，Agent不是一个临时创建的对象，而是一个长期存活的服务。就像你不会在每次HTTP请求里new一个DatabaseContext，你也不该在每次用户提问时new一个Kernel。MSAF的Agent默认是Singleton生命周期，框架会自动管理其状态、连接池、缓存等资源。我实测过：在高并发压测下，SK方案因频繁创建Kernel实例导致GC压力飙升，而MSAF方案CPU占用稳定在35%左右，吞吐量提升近3倍。

3.2 函数调用：从InvokeAsync到PipelineStep的契约化执行

SK里调用函数是这样的：

var result = await kernel.InvokeAsync( "weather", "GetWeather", new ContextVariables { { "city", "Beijing" } }); string weather = result.GetValue<string>();

这行代码背后藏着多少隐式契约？没人告诉你GetWeather函数的超时是几秒，失败了会不会重试，参数校验在哪做。MSAF强制你把所有这些契约显式声明出来。首先，定义你的能力（即原来的“函数”）：

public class MyWeatherCapability : IActionCapability { private readonly IHttpClientFactory _httpClientFactory; public MyWeatherCapability(IHttpClientFactory httpClientFactory) { _httpClientFactory = httpClientFactory; } // 注意：ExecuteAsync签名固定，输入输出都是强类型 public async Task<WeatherResult> ExecuteAsync(WeatherRequest request, CancellationToken cancellationToken) { // 参数校验放在方法入口，框架不帮你做 if (string.IsNullOrWhiteSpace(request.City)) throw new ArgumentException("City cannot be null or empty"); var client = _httpClientFactory.CreateClient(); var response = await client.GetAsync( $"https://api.weather.com/v3/wx/forecast/daily/5day?postalKey={request.City}&language=en-US", cancellationToken); return JsonSerializer.Deserialize<WeatherResult>(await response.Content.ReadAsStringAsync()); } }

然后，在Agent的Pipeline里声明如何使用它：

public class MyCustomerSupportAgent : AgentBase { protected override void ConfigurePipeline(IPipelineBuilder builder) { builder .AddStep(new ValidateInputStep()) // 第一步：校验用户输入 .AddStep(new ActionStep<MyWeatherCapability, WeatherRequest, WeatherResult>( "GetWeather", request => new WeatherRequest { City = request.UserInput }, (result, context) => context.Set("weather", result))) // 第二步：调用天气能力，并把结果存入上下文 .AddStep(new GenerateResponseStep()); // 第三步：生成最终回复 } }

注意：ActionStep的泛型参数明确指定了能力类型、输入类型、输出类型。框架在编译期就能检查类型安全，避免SK里常见的result.GetValue<string>()类型转换异常。

这个变化带来的最大好处是可测试性。以前测SK函数，你得mock整个Kernel，现在测MyWeatherCapability，直接new一个HttpClientFactory传进去，用xUnit写单元测试，10行代码搞定。我们团队把所有能力的单元测试覆盖率从SK时代的62%提升到MSAF的98%，而且测试执行时间从平均800ms降到120ms——因为不再需要启动整个Kernel模拟环境。

3.3 记忆管理：从VolatileMemoryStore到可插拔的IMemoryProvider

SK的内存抽象比较薄，IMemoryStore接口只有几个方法，实际使用中大家基本都用VolatileMemoryStore（内存版）或AzureCognitiveSearchMemoryStore（搜索版）。MSAF则把内存升级为一级公民IMemoryProvider，并定义了更精细的语义：

public interface IMemoryProvider { // 存储会话级短期记忆（类似SK的ConversationSummaryMemory） Task StoreSessionAsync(string sessionId, string key, object value, CancellationToken cancellationToken); // 存储用户级长期记忆（类似SK的SemanticMemory） Task StoreUserAsync(string userId, string key, object value, CancellationToken cancellationToken); // 基于向量的语义检索（核心能力） Task<IEnumerable<MemoryRecord>> SearchAsync(string collection, string query, int limit = 5, double minRelevance = 0.5, CancellationToken cancellationToken); // 基于关键词的精确检索（新增能力） Task<IEnumerable<MemoryRecord>> QueryAsync(string collection, string filter, CancellationToken cancellationToken); }

迁移时，你不能再直接用VolatileMemoryStore，而要实现IMemoryProvider。微软提供了InMemoryMemoryProvider作为开发期默认实现，但生产环境强烈建议用AzureCosmosMemoryProvider（基于Cosmos DB的向量+文档混合存储）或RedisMemoryProvider（基于Redis的高性能缓存）。我们选了后者，因为Redis的HSET和FT.SEARCH命令能完美支撑MSAF的混合检索需求。

实操心得：不要在StoreSessionAsync里存大对象！MSAF的Session Memory设计初衷是存轻量上下文（如用户ID、当前步骤、临时变量），不是存整个对话历史。我们最初把10轮对话的完整JSON塞进去，导致Redis内存暴涨，后来改成只存last_3_turns摘要和current_intent标签，内存占用下降92%。

3.4 规划能力：从Planner到Declarative Planning的声明式跃迁

SK的Planner是它的灵魂，但也是最不稳定的模块。SequentialPlanner、StepwisePlanner、HandlebarsPlanner……每个Planner的提示词模板、解析逻辑、错误处理都不同，调试起来像在黑盒里摸鱼。MSAF彻底放弃了“让LLM生成执行计划”这条路，转而采用声明式规划（Declarative Planning）：你用YAML或C#代码，直接定义Agent在不同条件下的行为分支。

比如，一个客服Agent的典型流程：

# MSAF planning.yaml planning: - when: "{{ input.intent == 'weather' }}" then: - step: GetWeather input: "{{ input.city }}" - step: GenerateWeatherResponse - when: "{{ input.intent == 'order' }}" then: - step: ValidateOrder input: "{{ input.orderId }}" - step: GetOrderStatus input: "{{ input.orderId }}" - step: GenerateOrderResponse - else: - step: HandleUnknownIntent

这个YAML会被MSAF的YamlPlanningEngine编译成一个IPlanExecutor，在运行时根据input.intent的值，直接跳转到对应分支执行。没有LLM解析JSON的环节，没有提示词工程的玄学，稳定性从SK的78%提升到MSAF的99.99%（我们压测数据）。

当然，MSAF也没完全放弃LLM规划。它提供了LLMPlannerCapability作为可选插件，但定位是“高级场景兜底”——比如当YAML规则无法覆盖所有边缘case时，再启用LLM动态生成plan。这体现了MSAF的设计哲学：默认用确定性方案保证基线质量，用非确定性方案应对长尾需求。

3.5 可观测性：从零散日志到统一Telemetry的开箱即用

SK里加监控，你得这样：

// SK style - 手动埋点 _logger.LogInformation("Starting GetWeather for {City}", city); var stopwatch = Stopwatch.StartNew(); try { var result = await _httpClient.GetAsync(url); _logger.LogInformation("GetWeather succeeded in {Ms}ms", stopwatch.ElapsedMilliseconds); return result; } catch (Exception ex) { _logger.LogError(ex, "GetWeather failed for {City}", city); throw; }

而MSAF里，你什么都不用写。只要在Program.cs里启用Telemetry：

builder.Services.AddAgentTelemetry(options => { options.EnableLogging = true; // 启用结构化日志 options.EnableMetrics = true; // 启用Prometheus指标 options.EnableTracing = true; // 启用OpenTelemetry追踪 });

框架会自动为每个PipelineStep生成：

• 日志：AgentExecutionStarted,StepExecuted,StepFailed,AgentCompleted
• 指标：agent_step_duration_seconds,agent_llm_token_count_total,agent_memory_search_count_total
• 追踪：完整的Span链路，从HTTP请求入口，到每个Step的执行，再到外部API调用

更绝的是，MSAF的Telemetry支持上下文透传。比如你在ValidateInputStep里检测到用户是VIP，可以这样标记：

context.SetTelemetryTag("user.tier", "vip");

这个tag会自动注入到后续所有Step的日志、指标、追踪中。运维同学在Grafana里筛选user.tier = "vip"，就能看到VIP用户的全部性能画像——这在SK里需要你自己写中间件、改日志格式、配Prometheus relabel规则，至少花两天。

4. 实操过程：一个真实迁移案例的完整复现

4.1 迁移前的SK项目结构与痛点

我们以那个IT服务助手项目为例。迁移前，它是一个ASP.NET Core Web API，核心结构如下：

ITSupportAssistant/ ├── Controllers/ │ └── ChatController.cs # HTTP入口 ├── Services/ │ ├── KernelService.cs # 封装Kernel初始化与调用 │ ├── WeatherPlugin.cs # 自定义函数 │ ├── OrderPlugin.cs # 自定义函数 │ └── IntentClassifier.cs # 用小型ML模型做意图识别 ├── Memory/ │ └── CosmosMemoryStore.cs # 自定义MemoryStore └── Models/ └── ChatRequest.cs # 输入模型

主要痛点有三个：

1. 可观测性缺失：只知道“API慢”，但不知道是LLM调用慢、还是天气API慢、还是意图识别模型慢；
2. 错误处理脆弱：天气API超时，整个请求就500，用户看到“系统错误”，客服还得手动查日志；
3. 配置分散：模型密钥在appsettings.json，内存连接串在CosmosMemoryStore构造函数里，插件路径硬编码在KernelService里。

4.2 迁移步骤详解：从零开始搭建MSAF项目

步骤1：创建新项目并安装NuGet包

dotnet new webapi -n ITSupportAssistant.MSAF cd ITSupportAssistant.MSAF dotnet add package Microsoft.Extensions.AI dotnet add package Microsoft.Extensions.AI.AgentFramework dotnet add package Microsoft.Extensions.AI.OpenAI dotnet add package Microsoft.Extensions.AI.AzureCosmos

注意：MSAF的包名是Microsoft.Extensions.AI.*，不是Microsoft.SemanticKernel.*。这是生态分界的物理标志。

步骤2：重构Program.cs，完成基础注册

// Program.cs var builder = WebApplication.CreateBuilder(args); // 配置模型客户端 builder.Services.AddModelClient<OpenAIChatClient>(options => { options.ModelId = builder.Configuration["AI:ModelId"] ?? "gpt-4-turbo"; options.ApiKey = builder.Configuration["AI:ApiKey"]; options.Endpoint = builder.Configuration["AI:Endpoint"]; }); // 配置内存提供者（用Azure Cosmos DB） builder.Services.AddSingleton<IMemoryProvider, AzureCosmosMemoryProvider>(sp => { var connectionString = builder.Configuration["Cosmos:ConnectionString"]; var databaseName = builder.Configuration["Cosmos:DatabaseName"]; return new AzureCosmosMemoryProvider(connectionString, databaseName); }); // 注册Agent能力 builder.Services.AddAgentCapability<WeatherCapability>("weather"); builder.Services.AddAgentCapability<OrderCapability>("order"); builder.Services.AddAgentCapability<IntentClassifierCapability>("intent"); // 注册Agent本身 builder.Services.AddAgent<ITSupportAgent>("it-support"); // 启用Telemetry builder.Services.AddAgentTelemetry(options => { options.EnableLogging = true; options.EnableMetrics = true; options.EnableTracing = true; }); var app = builder.Build(); app.MapControllers(); app.Run();

步骤3：定义Agent核心逻辑（ITSupportAgent.cs）

public class ITSupportAgent : AgentBase { protected override void ConfigurePipeline(IPipelineBuilder builder) { builder // 步骤1：意图识别（用小型ML模型，非LLM） .AddStep(new IntentClassificationStep()) // 步骤2：根据意图路由到不同能力 .AddStep(new RoutingStep()) // 步骤3：生成最终回复 .AddStep(new ResponseGenerationStep()); } } // IntentClassificationStep.cs - 调用本地ML模型 public class IntentClassificationStep : PipelineStep { private readonly IntentClassifierCapability _classifier; public IntentClassificationStep(IntentClassifierCapability classifier) { _classifier = classifier; } public override async Task ExecuteAsync(PipelineContext context, CancellationToken cancellationToken) { var userInput = context.Get<string>("user_input"); var intent = await _classifier.ClassifyAsync(userInput, cancellationToken); context.Set("intent", intent); // 存入上下文，供后续步骤使用 } } // RoutingStep.cs - 声明式路由 public class RoutingStep : PipelineStep { public override async Task ExecuteAsync(PipelineContext context, CancellationToken cancellationToken) { var intent = context.Get<string>("intent"); switch (intent) { case "weather": await context.ExecuteStepAsync(new ActionStep<WeatherCapability, WeatherRequest, WeatherResult>( "GetWeather", req => new WeatherRequest { City = context.Get<string>("user_input") }, (result, ctx) => ctx.Set("weather_result", result))); break; case "order": await context.ExecuteStepAsync(new ActionStep<OrderCapability, OrderRequest, OrderStatus>( "GetOrderStatus", req => new OrderRequest { OrderId = context.Get<string>("user_input") }, (result, ctx) => ctx.Set("order_status", result))); break; default: context.Set("response", "抱歉，我不太理解您的需求，请尝试说'查天气'或'查订单'。"); break; } } }

步骤4：定义能力实现（WeatherCapability.cs）

public class WeatherCapability : IActionCapability { private readonly IHttpClientFactory _httpClientFactory; public WeatherCapability(IHttpClientFactory httpClientFactory) { _httpClientFactory = httpClientFactory; } public async Task<WeatherResult> ExecuteAsync(WeatherRequest request, CancellationToken cancellationToken) { // 1. 参数校验（框架不帮你做） if (string.IsNullOrWhiteSpace(request.City)) throw new ArgumentException("City is required"); // 2. 调用外部API var client = _httpClientFactory.CreateClient(); var response = await client.GetAsync( $"https://api.weather.com/v3/wx/forecast/daily/5day?postalKey={request.City}&language=en-US", cancellationToken); // 3. 错误处理（框架会捕获并触发OnFailed事件） if (!response.IsSuccessStatusCode) { var errorContent = await response.Content.ReadAsStringAsync(); throw new HttpRequestException($"Weather API returned {(int)response.StatusCode}: {errorContent}"); } // 4. 返回强类型结果 return JsonSerializer.Deserialize<WeatherResult>(await response.Content.ReadAsStringAsync()); } }

步骤5：配置appsettings.json

{ "AI": { "ModelId": "gpt-4-turbo", "ApiKey": "your-openai-key", "Endpoint": "https://your-resource.openai.azure.com/" }, "Cosmos": { "ConnectionString": "AccountEndpoint=https://your-cosmos.documents.azure.com:443/;AccountKey=xxx;", "DatabaseName": "it-support-db" } }

4.3 迁移后的效果对比与实测数据

我们用JMeter对两个版本做了对比压测（100并发，持续5分钟）：

最关键的是可观测性提升：

• 问题定位时间：从平均47分钟（查日志+分析链路）降到2分钟（直接看仪表盘告警+点击Trace下钻）；
• 成本控制：通过agent_llm_token_count_total指标，我们发现gpt-4-turbo在处理简单查询时token浪费严重，于是配置了ModelFallbackPolicy，对intent == "weather"的请求自动降级到gpt-3.5-turbo，月度LLM费用下降38%；
• 用户体验：错误率从3.2%降到0.07%，意味着每1000次请求，用户看到“系统错误”的次数从32次降到不到1次。

5. 常见问题与排查技巧实录

5.1 典型问题速查表

5.2 我踩过的三个深坑与独家避坑技巧

坑1：PipelineStep的异步陷阱MSAF的ExecuteAsync是async void还是async Task？答案是Task，但很多人会忽略await。比如：

// ❌ 错误：忘记await，Step会立即返回，框架认为执行成功 public override async Task ExecuteAsync(PipelineContext context, CancellationToken cancellationToken) { // 这里调用了一个async方法，但没await！ _httpClient.GetAsync("https://api.example.com"); // 这行不会等待 context.Set("result", "done"); } // ✅ 正确：必须await所有异步操作 public override async Task ExecuteAsync(PipelineContext context, CancellationToken cancellationToken) { var response = await _httpClient.GetAsync("https://api.example.com", cancellationToken); context.Set("result", await response.Content.ReadAsStringAsync()); }

技巧：在ExecuteAsync方法里，第一行就写await Task.CompletedTask;，然后Ctrl+.快速生成await，强迫自己检查