XIAOSUO 记录个人学习的足迹

摘要：一、自定义工作流事件 1. 为什么需要自定义事件？ 场景 内置事件 自定义事件 粒度 Executor 级别 业务逻辑级别 语义 系统通用 (调用、完成) 业务特定 (审核通过、风险预警) 数据 执行元数据 业务数据 (敏感词、风险分数) 监控 技术监控 业务监控 + 审计 前端 通用进度条 具体业务状态展示 2. 自定义事件类定义 基本定义模式：自定义事件本质上就是继承 WorkflowEvent 的普通 C# 类。让我们从最简单的开始： /// summary /// 表示检测到敏感词的事件 /// /summary public class SensitiveWordDetectedEvent : WorkflowEvent { public SensitiveWordDetectedEvent(string word, int position) : base(data: null) // 可以传递简单数据到 base { Word = word; Position = position; } public string Word { get; } public int Position { get; } } 设计原则 DO (推荐做法)： 类名以 Event 结尾，语义清晰 使用只读属性 ({ get; })，确保事件不可变 添加 XML 注释说明事件的业务含义 属性类型尽量简单（string, int, DateTime 等可序列化类型） DON'T (避免做法)： 不要在事件类中包含方法逻辑 不要引用不可序列化的对象（如 DbContext, HttpClient） 不要使用可变属性（{ get; set; }） 不要在构造函数中执行耗时操作 3. 携带复杂数据的事件 当需要传递更复杂的业务数据时，有两种设计模式： 模式 1: 使用属性传递结构化数据 /// summary /// 风险评估完成事件 /// /summary public class RiskAssessmentCompletedEvent : WorkflowEvent { public RiskAssessmentCom…… 阅读全文

摘要：一、工作流基础 1. 什么是 Workflow Orchestration 在企业级 AI 应用开发中，我们经常面临以下挑战： 单个 Agent 难以处理复杂任务：一个 Agent 无法同时擅长需求分析、代码生成、测试等多个领域 业务逻辑与 AI 调用耦合：复杂的条件判断、循环、并发控制分散在代码各处 流程难以可视化和维护：多步骤的 AI 处理流程缺乏清晰的结构 缺乏统一的状态管理：多个步骤之间的数据传递和状态共享容易出错 Workflow Orchestration (工作流编排) 正是为了解决这些问题而生： 模块化设计：将复杂任务拆分为独立的 Executor 和 Agent 清晰的流程定义：使用 Builder API 构建可读、可维护的流程图 灵活的流程控制：支持条件分支、循环迭代、并发执行等复杂模式 统一的状态管理：内置 WorkflowContext 管理跨步骤的状态和数据 实时流式反馈：通过事件机制实时监控工作流的执行进度 MAF Workflow 位于应用层和 Agent 层之间，负责： 编排多个 Agent：决定 Agent 的执行顺序、条件和并发策略 管理数据流：在 Agent 和 Executor 之间传递数据 监控执行状态：实时报告工作流的执行进度和结果 错误处理：统一处理执行过程中的异常和重试逻辑 2. Workflow 的核心构建块 Workflow 由以下三个核心概念组成： Executor (执行器) - 处理单元：Executor 是工作流的基本处理单元，负责执行具体的业务逻辑。 特点： 强类型输入：TInput 定义接收的数据类型 强类型输出：TOutput 定义返回的数据类型 纯逻辑处理：可以是数据转换、验证、格式化等任何操作 Agent 也是 Executor：AIAgent 可以直接作为 Executor 使用 示例用途： 文本转换 (大写、反转、清理) 数据验证 (格式检查、安全过滤) 结果聚合 (合并多个输出) AI 调用 (通过 Agent) public abstract class ExecutorTInput, TOutput : Executor { public abstract ValueTaskTOutput HandleAsync( TInput i…… 阅读全文

摘要：一、自定义 Agent 的实现 1. 场景分析 在大多数场景下，使用 chatClient.CreateAIAgent() 创建的标准 Agent 已经足够强大。但在某些特殊场景下，自定义 Agent 实现能带来更大的价值： 场景 1：规则引擎替代 AI（成本优化） 问题：客服系统每天处理数万次重复性问题(营业时间？，退货流程？)，每次调用 AI 模型都会产生成本。 解决方案：自定义 Agent 使用 FAQ 知识库进行关键词匹配，只在无法匹配时才调用 AI。 收益： 成本降低 70-90%（高频简单问题零成本） 响应速度提升 10 倍（无需等待 AI 推理） 答案一致性更高（预定义标准答案） 场景 2：遗留系统集成（ERP/CRM/工作流引擎） 问题：企业内部有成熟的审批工作流引擎，需要将其包装为 Agent 供统一调度。 解决方案：自定义 Agent 作为适配器，将工作流引擎的 API 转换为 Agent 接口。 收益： 无缝集成现有系统（无需重构） 复用企业级规则引擎（审批、权限、流程） 数据安全可控（不发送敏感数据到外部 AI） 场景 3：测试模拟（Mock Agent） 问题：开发和测试环境中，不希望调用真实 AI 模型（成本、稳定性、可预测性）。 解决方案：自定义 Agent 返回固定或可配置的测试数据。 收益： 单元测试更可靠（确定性输出） 开发环境零成本 CI/CD 管道更快（无需等待 AI 响应） 场景 4：混合模式（规则 + AI） 问题：希望结合规则引擎的确定性和 AI 的灵活性。 解决方案：自定义 Agent 先尝试规则匹配，失败后转发给 AI Agent。 收益： 平衡成本与效果 灵活的分流策略（按优先级、置信度） 逐步优化规则库（分析 AI 处理的高频问题） 对比: 标准 Agent vs 自定义 Agent 特性 ChatClientAgent(标准) 自定义 Agent 说明 创建方式 chatClient.CreateAIAgent() 继承 AIAgent 抽象类 标准方式更简单 开发复杂度 低 高 自定义需实现所有核心方法 灵活性 受限于 IChatClient 能力 完全可控 自定义可实现任意逻辑 成本 按 Token 计费…… 阅读全文

摘要：一、自定义文件消息存储 1. ChatMessageStore 架构概览 classDiagram class ChatMessageStore { abstract>> #IChatReducer? ChatReducer +AddMessagesAsync(messages) +GetMessagesAsync() +ClearAsync() +Serialize() +Deserialize(state) } class InMemoryChatMessageStore { -List~ChatMessage~ _messages +AddMessagesAsync() +GetMessagesAsync() +ClearAsync() } class FileChatMessageStore { -string _filePath -SemaphoreSlim _lock +AddMessagesAsync() +GetMessagesAsync() +ClearAsync() } class RedisChatMessageStore { -IConnectionMultiplexer _redis +AddMessagesAsync() +GetMessagesAsync() +ClearAsync() } ChatMessageStore |-- InMemoryChatMessageStore ChatMessageStore |-- FileChatMessageStore ChatMessageStore |-- RedisChatMessageStore ChatMessageStore 抽象类核心方法职责 方法 职责 使用场景 AddMessagesAsync 添加新消…… 阅读全文

摘要：一、第一个智能体 1. 什么是 MAF Microsoft Agent Framework (MAF) 是微软推出的企业级 AI Agent 开发框架，构建在 Microsoft.Extensions.AI (MEAI) 之上，提供了构建生产级 AI Agent 所需的完整能力。 Agent vs ChatClient - 什么时候用 Agent? 特性 IChatClient AIAgent 定位 底层 AI 调用抽象 高级智能体封装 状态管理 无状态，每次调用独立 内置对话线程 (AgentThread) 身份定义 需要手动在每次调用中传入 System Message 固定的 Instructions 和 Name 工具管理 需要手动配置 ChatOptions.Tools Agent 级别统一管理工具 使用场景 构建自定义 AI 功能，单次对话场景 企业级对话系统，多轮交互场景 简单来说: ChatClient 就像一个纯函数：给定输入，返回输出，不保留状态 Agent 就像一个有记忆的助手： 有固定身份、能记住上下文、能使用工具 2. MAF 的核心概念 MAF 围绕以下核心概念构建: AIAgent - 智能代理：Agent 是具有特定身份和能力的智能实体，包含： Name (名称)：Agent 的唯一标识 Instructions (指令)：Agent 的系统提示词，定义其行为和角色 Tools (工具)：Agent 可以调用的函数工具集合 AgentThread - 对话线程：每个 Agent 可以有多个对话线程，每个线程维护独立的对话历史： 自动管理消息历史 支持序列化/反序列化 (持久化) 线程隔离，互不干扰 AgentRun - 执行实例：每次调用 Agent 都会创建一个 Run： 同步调用：RunAsync() → 返回完整响应 流式调用：RunStreamingAsync() → 返回增量更新流 3. 快速开始 让我们通过创建一个口语教练 Agent 来快速入门 MAF。 // 步骤 1: 获取底层获取 ChatClient var chatClient = ChatClientFactory.GetQwenClient(); // 步骤 2: 创建口语教…… 阅读全文