目录一句话简介 核心要点 为什么 Agent 必须结构化输出 实现方式两种提取路径 流式与复杂对象 国产模型适配DeepSeek / Qwen⚖️ MAF vs MEAI如何选️ 最佳实践速查 总结上一篇一句话简介MAF 依托 Microsoft.Extensions.AI 的结构化输出能力让 Agent 直接返回强类型业务对象既保证类型安全又能与企业系统快速对接。 核心要点✅ Agent 天然需要结构化输出来驱动流程、审批、入库等后续动作✅RunAsyncT()是默认首选自动生成 Schema 并返回强类型结果✅ 流式、嵌套对象、国产模型都能通过少量配置完成适配✅ 与 MEAI 的分工清晰MAF 管状态与复用MEAI 负责轻量调用 为什么 Agent 必须结构化输出企业级 Agent 不是止于回答问题而是要触发下游流程。结构化输出能直接映射业务对象避免脆弱的字符串解析。场景需求结构化收益客服工单分类、定级、行动项TicketAnalysis对象可直接入库审批助手抽取审批结论与风险ApprovalDecision触发工作流数据分析汇总指标、异常AnalysisResult连接 BI 管道 实现方式两种提取路径非泛型方式兼容所有返回类型创建 Agent 时配置ChatOptions.ResponseFormat调用RunAsync()再用response.DeserializeT()泛型方式推荐无需预先配置直接await agent.RunAsyncPersonInfo(...)自动生成 JSON Schema、设置 ResponseFormat、反序列化到Resultvar agent chatClient.CreateAIAgent(new ChatClientAgentOptions { Name PersonInfoExtractor, Instructions 提取姓名、年龄、职业、地点 }); var thread agent.GetNewThread(); var result await agent.RunAsyncPersonInfo( 张伟35岁软件工程师在北京, thread); result.Result.Display(); 流式与复杂对象流式获取RunStreamingAsync()-ToAgentRunResponseAsync()-DeserializeT()完成后再解析即可。嵌套模型枚举使用JsonStringEnumConverter列表和对象用[JsonPropertyName]保持字段名一致。最佳实践把TicketAnalysis这类复杂对象一次定义完整避免后续修改 Schema 导致模型漂移。 国产模型适配DeepSeek / Qwen模型不支持 JSON Schema 时调用RunAsyncT()需设置useJsonSchemaResponseFormat: falseInstructions 内必须明确 JSON 模板并强调“只返回 JSON”var deepseekResponse await deepseekAgent.RunAsyncPersonInfo( 刘洋42岁数据科学家在深圳, thread, useJsonSchemaResponseFormat: false);模型ResponseFormat泛型参数提示词要求OpenAI / Azure OpenAI自动 Schema默认即可简要描述即可DeepSeek / QwenChatResponseFormat.JsonuseJsonSchemaResponseFormat: false必须提供完整 JSON 示例⚖️ MAF vs MEAI如何选维度MEAI (IChatClient)MAF (AIAgent)配置方式每次请求传ChatOptionsAgent 创建时配置一次泛型调用GetResponseAsyncT()RunAsyncT()状态管理手动维护messagesAgentThread自动记录适用场景一次性、无状态调用长期运行、需要上下文的 Agent️ 最佳实践速查配置策略泛型方法优先非泛型需搭配ChatResponseFormat.ForJsonSchemaT()流式场景完成流后再DeserializeT()切勿边流边反序列化数据模型使用可空类型、JSON 特性、XML 注释保证可维护性国产模型useJsonSchemaResponseFormat: false 详细 JSON 提示Instructions列出字段约束、示例必要时给出校验规则 总结✅ MAF 的结构化输出让 Agent 与业务系统直接对接避免文本解析✅RunAsyncT()AgentThread组合提供最省心的强类型体验✅ 深入掌握流式、嵌套、国产模型等场景企业落地不再踩坑✅ MAF 与 MEAI 分工明确前者管状态后者管轻量调用引入地址