Skip to content

Conversation

Copy link

Copilot AI commented Dec 6, 2025

Establishes layered governance architecture where BotSharp acts as control plane (intent routing, session management) and Microsoft Agent Framework serves as execution plane (deterministic business workflows). Enables enterprise-grade separation of conversational AI from critical business logic.

Architecture

Control Plane (BotSharp)

  • Intent recognition and routing
  • User authentication and session lifecycle
  • Channel integration (Slack, Teams, WebChat)

Execution Plane (MAF)

  • Deterministic workflow execution
  • Multi-step transaction processing
  • Enterprise system integration (ERP/CRM)

Integration Layer

  • Plugin wrapping pattern via IFunctionCallback
  • Context passing: conversation history → MAF → structured results
  • State serialization for long-running workflows requiring approval

Implementation

// MAF workflow wrapped as BotSharp function
public class MafOrderWorkflowFunction : IFunctionCallback
{
    public async Task<bool> Execute(RoleDialogModel message)
    {
        var orderDetails = JsonSerializer.Deserialize<OrderRequest>(message.FunctionArgs);
        
        // Execute deterministic workflow: validate → calculate → lock → process → notify
        var result = await ExecuteMafWorkflow(orderDetails, message);
        
        message.Content = result.Output;
        message.Payload = result.SerializedState; // For workflow resumption
        return result.Success;
    }
}

Plugin Components

  • MafOrderWorkflowFunction: Order processing/refunds/cancellations with sequential steps
  • MafWorkflowExecutorFunction: Generic executor for IT/HR/Customer Service workflows
  • Models: OrderRequest, WorkflowExecutionRequest, WorkflowResult
  • Settings: OpenAI config, timeouts, state serialization toggles

Example Agent Configuration

{
  "id": "order-management-agent",
  "name": "Order Management Agent",
  "functions": [{
    "name": "execute_order_workflow",
    "description": "Execute order workflow via MAF",
    "parameters": {
      "order_id": "string",
      "action": "enum[process,refund,cancel]"
    }
  }]
}

Workflow Patterns

  • Order refund: Validate → Calculate → Lock inventory → Initiate refund → Notify
  • IT support: Diagnose → Configure → Document → Follow-up
  • HR service: Review → Approve → Process → Notify

Documentation

  • README.md: Architecture diagrams, installation, benefits
  • INTEGRATION_GUIDE.md: Configuration, custom workflows, enterprise integration
  • Example agent configs for Order Management, IT Support, HR Service

Tests

13 unit tests covering workflow execution, error handling, timeout management, JSON validation. All passing.

Future Enhancement

Template-ready for official Microsoft.Agents.AI SDK:

// Replace simulation with actual MAF SDK
var chatClient = new OpenAIChatClient(apiKey, model);
var validatorAgent = new ChatClientAgent(chatClient, "Validator");
var workflow = new WorkflowBuilder(validatorAgent)
    .AddEdge(validatorAgent, processorAgent)
    .Build();
Original prompt

BotSharp 与 Microsoft Agent Framework 不应被视为竞争对手,而应视为互补的技术栈。一个理想的企业级 AI 架构应当结合 BotSharp 的高层意图管理能力与 MAF 的底层执行稳健性

6.1 架构蓝图:控制平面与执行平面的分离

我们建议采用一种分层治理架构,将系统划分为控制平面(Control Plane)和执行平面(Execution Plane)。

6.1.1 控制平面:BotSharp 的角色

BotSharp 应被部署为系统的统一接入网关

  • 职责:负责用户认证、会话生命周期管理、初步的意图识别(Router)、以及与即时通讯渠道(Slack, Teams, WebChat)的连接。
  • 配置:业务分析师在 BotSharp UI 中定义高层级的 Agent,如 "IT Support", "HR Service", "Order Management"。
  • 价值:利用 BotSharp 的 Router 处理模糊的自然语言输入,将用户千奇百怪的表达收敛为明确的业务领域意图。

6.1.2 执行平面:Microsoft Agent Framework 的角色

MAF 应被封装为具体的业务执行单元

  • 职责:负责具体业务流程的执行、多步骤事务处理、与企业 ERP/CRM 系统的深度集成。
  • 实现:当 BotSharp 将请求路由给 "Order Management" Agent 时,该 Agent 的底层实现并非直接调用 LLM 生成回复,而是触发一个预定义的 MAF Workflow
  • 价值:利用 MAF 的强类型工作流确保业务逻辑的严密性。例如,在处理退款时,使用 MAF 的 Sequential Workflow 严格按照“验证订单 -> 计算金额 -> 锁定库存 -> 发起退款 -> 发送通知”的顺序执行,任何一步失败都能通过代码逻辑进行精确的错误处理,而不是依赖 LLM 的“运气”。

6.2 代码级集成模式:插件封装(Plugin Wrapping)

实现这一架构的关键在于如何打通两者。由于 BotSharp 具有极强的插件扩展性,我们可以通过实现 IBotSharpPlugin 接口将 MAF 嵌入其中。

集成方案设计:

  1. 定义 MAF 包装器:创建一个.NET 类库,引用 Microsoft.Agents.AI 和 BotSharp.Core。
  2. 实现 IFunctionCallback:将 MAF 的工作流启动逻辑封装在 BotSharp 的工具回调中。

C#

// 示例:将 MAF 工作流封装为 BotSharp 的一个 Function 工具
public class MafOrderWorkflowFunction : IFunctionCallback
{
public string Name => "execute_order_workflow";
public string Indication => "正在启动订单处理工作流...";

public async Task\<string\> Execute(string jsonInput)  
{  
    // 1\. 解析输入参数  
    var orderDetails \= JsonSerializer.Deserialize\<OrderRequest\>(jsonInput);

    // 2\. 初始化 MAF Agents  
    var validatorAgent \= new ChatClientAgent(new OpenAIChatClient(...), "Validator");  
    var processorAgent \= new ChatClientAgent(new OpenAIChatClient(...), "Processor");

    // 3\. 构建 MAF 工作流 (利用代码定义的确定性)  
    var workflow \= new WorkflowBuilder(validatorAgent)  
       .AddEdge(validatorAgent, processorAgent)  
       .Build();

    // 4\. 执行 MAF 工作流  
    var result \= await workflow.RunAsync(orderDetails.ToString());

    // 5\. 返回最终结果给 BotSharp Router  
    return result.FinalOutput;  
}  

}

  1. 注册插件:在 BotSharp 的 Startup.cs 或配置中启用该插件。
  2. 配置 Agent:在 BotSharp UI 中,为 "Order Agent" 添加 execute_order_workflow 工具。当 Router 激活 Order Agent 时,Order Agent 会调用此工具,从而无缝启动 MAF 的执行引擎。

6.3 数据流与上下文传递

在集成过程中,上下文(Context)的传递是核心挑战。

  • 入参:BotSharp 需要将当前的 Conversation History 摘要或关键参数(Slot Filling 提取的参数)传递给 MAF。建议使用 JSON 序列化作为标准载体。
  • 状态保持:如果 MAF 的工作流需要挂起(等待人工审批),可以利用 AgentThread.SerializeAsync 将状态序列化为字符串,返回给 BotSharp 存储。当用户稍后回复确认时,BotSharp 再将此状态字符串传回 MAF 进行恢复 23。
  • 出参:MAF 执行完毕后,应返回结构化的结果(而非纯文本),由 BotSharp 的 Template Engine(模板引擎)负责将其渲染为最终用户友好的自然语言 6。

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Copilot AI and others added 3 commits December 6, 2025 01:40
Co-authored-by: geffzhang <439390+geffzhang@users.noreply.github.com>
Co-authored-by: geffzhang <439390+geffzhang@users.noreply.github.com>
Co-authored-by: geffzhang <439390+geffzhang@users.noreply.github.com>
Copilot AI changed the title [WIP] Update architecture blueprint for AI framework Implement Microsoft Agent Framework integration for control-execution plane separation Dec 6, 2025
Copilot AI requested a review from geffzhang December 6, 2025 01:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants