A2 A Microservice Sample

Agent Framework Aspire - 多智能体微服务系统

  

基于 .NET Aspire、Microsoft Agent Framework、A2A 和 MCP 协议构建的多智能体微服务系统。

📖 目录

• 项目背景
• 项目目标
• 架构设计
• 技术栈
• 项目结构
• 服务说明
• 快速开始
• 配置说明
• 开发指南
• License

🌟 项目背景

在现代企业环境中，项目管理涉及多个专业领域的协作，包括技术评估、人力资源配置、财务预算控制、质量风险管理和项目进度规划等。传统的单体智能体系统存在以下问题：

传统方案的痛点

1. 通用性 vs 专业性的矛盾

- 单一 AI 助手难以同时具备多领域的深度专业知识 - 通用模型缺乏对企业特定领域的深度理解

1. 维护和更新困难

- 任何部门知识更新都需要重新训练整个模型 - 权限控制和数据隔离难以实现

1. 不符合组织结构

- 违背企业实际的分工协作模式 - 责任不清晰，出错难以追溯

我们的方案

基于康威定律在 AI 时代的应用，本项目提出了多智能体微服务架构：

"设计系统的架构应该映射组织的沟通结构。"

每个专业团队维护自己的智能体服务，实现：

• ✅ 专业化分工：每个智能体专注一个领域
• ✅ 标准化通信：使用 MCP 和 A2A 协议实现跨服务协作
• ✅ 独立演进：各团队可以独立迭代自己的服务
• ✅ 责任清晰：问题可追溯到具体领域

🎯 项目目标

1. 降低集成成本：基于标准协议（MCP + A2A），减少各团队系统集成的复杂度
2. 提高专业化程度：各团队专注于自己的领域，提供更专业的服务
3. 增强系统弹性：微服务架构提供更好的容错性和扩展性
4. 促进团队协作：通过标准化接口促进跨团队协作
5. 提供参考实现：为企业构建类似系统提供完整的示例代码

🏗️ 架构设计

整体架构

graph TB
    subgraph "用户交互层"
        User[👤 用户/客户端
Blazor Web UI]
    end
    
    subgraph "智能编排层"
        PM[🎯 项目经理智能体
ProjectManagerAgent
━━━━━━━━━━━
统一协调与决策
3阶段工作流编排]
    end
    
    subgraph "专业服务层 - 并行分析"
        Tech[💻 技术团队服务
Tech Agent
━━━━━━━━━━━
MCP工具 + A2A端点]
        HR[👥 HR团队服务
HR Agent
━━━━━━━━━━━
MCP工具 + A2A端点]
        Finance[💰 财务团队服务
Finance Agent
━━━━━━━━━━━
MCP工具 + A2A端点]
        QA[🔍 QA团队服务
QA Agent
━━━━━━━━━━━
MCP工具 + A2A端点
内部4阶段工作流]
    end
    
    subgraph "专业服务层 - 规划整合"
        PMO[📅 PMO团队服务
PMO Agent
━━━━━━━━━━━
MCP工具 + A2A端点
内部4阶段工作流]
    end
    
    subgraph "基础设施层"
        Aspire[.NET Aspire
服务编排 & 配置管理]
        MCP[MCP 协议层
工具与资源访问]
        A2A[A2A 协议层
智能体间通信]
        AF[Agent Framework
工作流编排引擎]
    end
    
    User --> PM
    PM -->|Stage 1: 并行分析| Tech
    PM -->|Stage 1: 并行分析| HR
    PM -->|Stage 1: 并行分析| Finance
    PM -->|Stage 1: 并行分析| QA
    PM -->|Stage 2: 规划整合| PMO
    PM -.->|Stage 3: 最终决策| PM
    
    Tech --> MCP
    HR --> MCP
    Finance --> MCP
    QA --> MCP
    PMO --> MCP
    
    PM --> A2A
    Tech --> A2A
    HR --> A2A
    Finance --> A2A
    QA --> A2A
    PMO --> A2A
    
    QA --> AF
    PMO --> AF
    PM --> AF
    
    Aspire -.->|编排| PM
    Aspire -.->|编排| Tech
    Aspire -.->|编排| HR
    Aspire -.->|编排| Finance
    Aspire -.->|编排| QA
    Aspire -.->|编排| PMO
    
    style User fill:#e1f5ff,stroke:#333,stroke-width:2px
    style PM fill:#fff3cd,stroke:#333,stroke-width:3px
    style Tech fill:#d4edda,stroke:#333,stroke-width:2px
    style HR fill:#d4edda,stroke:#333,stroke-width:2px
    style Finance fill:#d4edda,stroke:#333,stroke-width:2px
    style QA fill:#d4edda,stroke:#333,stroke-width:2px
    style PMO fill:#cce5ff,stroke:#333,stroke-width:2px
    style Aspire fill:#f8d7da,stroke:#333,stroke-width:2px
    style MCP fill:#e2e3e5,stroke:#333,stroke-width:1px
    style A2A fill:#e2e3e5,stroke:#333,stroke-width:1px
    style AF fill:#e2e3e5,stroke:#333,stroke-width:1px

工作流设计

项目经理智能体使用 3 阶段工作流编排：

sequenceDiagram
    participant User as 用户
    participant PM as 项目经理智能体
    participant Tech as 技术团队
    participant HR as HR团队
    participant Finance as 财务团队
    participant QA as QA团队
    participant PMO as PMO团队
    
    User->>PM: 提交项目需求
    
    Note over PM: Stage 1: 并行分析阶段
    par 并行调用
        PM->>Tech: A2A调用：技术需求分析
        Tech-->>PM: 技术评估报告
    and
        PM->>HR: A2A调用：人力资源评估
        HR-->>PM: 资源分析报告
    and
        PM->>Finance: A2A调用：预算分析
        Finance-->>PM: 财务评估报告
    and
        PM->>QA: A2A调用：风险分析
        QA-->>PM: 风险评估报告
    end
    
    Note over PM: Stage 2: 详细规划阶段
    PM->>PMO: A2A调用：基于前期分析进行规划
    Note over PMO: 内部工作流:
任务分解→依赖分析
→资源匹配→时间优化
    PMO-->>PM: 详细项目计划
    
    Note over PM: Stage 3: 整合决策阶段
    PM->>PM: 综合所有分析结果
生成最终决策
    PM-->>User: 完整项目计划与建议

智能体分层架构

系统采用四层智能体架构设计：

graph TD
    subgraph "第四层：编排智能体层"
        L4[项目经理智能体
━━━━━━━━━━━
跨团队协调
复杂工作流编排
最终决策]
    end
    
    subgraph "第三层：专家智能体层"
        L3A[QA 风险管理专家
━━━━━━━━━━━
内部工作流:
识别→评估→缓解→监控]
        L3B[PMO 进度规划专家
━━━━━━━━━━━
内部工作流:
分解→依赖→匹配→优化]
    end
    
    subgraph "第二层：简单智能体层"
        L2A[Tech 需求分析
━━━━━━━━━━━
单一职责
直接调用工具]
        L2B[HR 资源评估
━━━━━━━━━━━
单一职责
直接调用工具]
        L2C[Finance 预算分析
━━━━━━━━━━━
单一职责
直接调用工具]
    end
    
    subgraph "第一层：MCP 工具层"
        L1A[EstimateTechnicalComplexity
ValidateTechStack
GetArchitectureTemplate]
        L1B[GetTeamCapabilities
CheckTeamAvailability
EstimateResourceCost]
        L1C[ValidateBudget
GetHistoricalCosts
CalculateROI]
        L1D[AnalyzeRiskPatterns
GetComplianceRequirements
ValidateDeliverables]
        L1E[GetProjectTemplate
ValidateSchedule
CalculateCriticalPath]
    end
    
    L4 --> L3A
    L4 --> L3B
    L4 --> L2A
    L4 --> L2B
    L4 --> L2C
    
    L3A --> L1D
    L3B --> L1E
    L2A --> L1A
    L2B --> L1B
    L2C --> L1C
    
    style L4 fill:#ff6b6b,stroke:#333,stroke-width:3px,color:#fff
    style L3A fill:#feca57,stroke:#333,stroke-width:2px
    style L3B fill:#feca57,stroke:#333,stroke-width:2px
    style L2A fill:#48dbfb,stroke:#333,stroke-width:2px
    style L2B fill:#48dbfb,stroke:#333,stroke-width:2px
    style L2C fill:#48dbfb,stroke:#333,stroke-width:2px
    style L1A fill:#dfe6e9,stroke:#333,stroke-width:1px
    style L1B fill:#dfe6e9,stroke:#333,stroke-width:1px
    style L1C fill:#dfe6e9,stroke:#333,stroke-width:1px
    style L1D fill:#dfe6e9,stroke:#333,stroke-width:1px
    style L1E fill:#dfe6e9,stroke:#333,stroke-width:1px

层次说明：

1. 第一层 - MCP 工具层：无状态的纯函数工具，提供基础计算和数据访问能力
2. 第二层 - 简单智能体层：单一职责的智能体，使用 ChatClient 直接调用 MCP 工具
3. 第三层 - 专家智能体层：复杂的工作流编排，使用 Agent Framework 实现多阶段分析
4. 第四层 - 编排智能体层：跨领域协调，统一用户接口，最终决策

🛠️ 技术栈

项目结构

AgentFrameworkAspire/
├── AgentFrameworkAspire.AppHost/        # Aspire 编排主机
├── AgentFrameworkAspire.Web/            # Web 前端
├── AgentFrameworkAspire.ServiceDefaults/ # 共享服务配置
├── Finance/                              # 财务服务 (MCP + A2A Agent)
├── Tech/                                 # 技术架构服务 (MCP + A2A Agent)
├── HumanResource/                        # 人力资源服务 (MCP + A2A Agent)
├── QA/                                   # QA服务 (MCP + Workflow Agent)
└── PMO/                                  # PMO服务 (MCP + Workflow Agent)

服务说明

1. Finance (财务服务)

• MCP工具: 预算验证、历史成本查询、ROI计算
• A2A Agent: 财务分析智能体，提供预算分析和成本控制建议
• 端点:

- MCP: /finance/mcp - A2A: /finance/budget-analyzer

2. Tech (技术架构服务)

• MCP工具: 技术复杂度评估、技术栈验证、架构模板获取
• A2A Agent: 技术需求分析智能体，提供架构设计建议
• 端点:

- MCP: /tech/mcp - A2A: /tech/requirement-analyst

3. HumanResource (人力资源服务)

• MCP工具: 团队能力查询、可用性检查、资源成本估算
• A2A Agent: HR资源评估智能体，提供团队容量规划
• 端点:

- MCP: /hr/mcp - A2A: /hr/resource-estimator

4. QA (质量保证服务)

• MCP工具: 风险模式分析、合规要求获取、交付物验证
• A2A Workflow Agent: 风险管理专家，使用多阶段工作流进行风险分析

- 工作流: 风险识别 → 影响评估 → 缓解策略 → 监控计划

• 端点:

- MCP: /qa/mcp - A2A: /qa/risk-expert

5. PMO (项目管理办公室服务)

• MCP工具: 项目模板获取、进度验证、关键路径计算
• A2A Workflow Agent: 进度规划专家，使用多阶段工作流进行项目规划

- 工作流: 任务分解 → 依赖分析 → 资源匹配 → 时间优化

• 端点:

- MCP: /pmo/mcp - A2A: /pmo/schedule-expert

🚀 快速开始

前置要求

• ✅ .NET 9.0 SDK (下载)
• ✅ Docker Desktop (下载)
• ✅ OpenAI API Key 或兼容的 API 服务

第一步：克隆项目

git clone https://github.com/MadLongTom/A2AMicroserviceSample.git
cd A2AMicroserviceSample

第二步：配置 OpenAI API

编辑 AgentFrameworkAspire.AppHost/appsettings.json 文件，配置 OpenAI 参数：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Aspire.Hosting.Dcp": "Warning"
    }
  },
  "Parameters": {
    "openai-endpoint": "",  
    "openai-apikey": "your-api-key-here",
    "openai-deployment": "gpt-4o-mini"
  }
}

配置说明：

• 留空：使用 OpenAI 官方 API
• 填写：使用第三方兼容 API | ""

"https://api.openai.com/v1" "https://your-proxy.com/v1" | | openai-apikey | API 密钥（必填） 从 OpenAI 或第三方服务获取 | "sk-..." | | openai-deployment | 模型名称（必填） 选择要使用的模型 | "gpt-4o-mini" "gpt-4" "gpt-3.5-turbo" |

💡 提示：如果你使用的是 Azure OpenAI，endpoint 应该类似 https://your-resource.openai.azure.com/，deployment 是你在 Azure 中部署的模型名称。

第三步：恢复依赖

dotnet restore

第四步：启动项目

cd AgentFrameworkAspire.AppHost
dotnet run

Aspire Dashboard 会自动在浏览器中打开（默认 http://localhost:15000），显示所有服务的状态和日志。

第五步：访问 Web 界面

在 Aspire Dashboard 中找到 webfrontend 服务，点击其 URL（通常是 http://localhost:5xxx）即可访问项目经理智能体的聊天界面。

测试示例

尝试输入以下问题：

我们要开发一个在线教育平台，预算200万，需要多久能完成？

系统会自动调用所有专业智能体进行分析，并给出综合建议。

⚙️ 配置说明

Aspire 配置文件位置

主要配置文件位于 AgentFrameworkAspire.AppHost/appsettings.json，这是推荐的配置方式。

开发环境配置（可选）

如果需要针对开发环境的特殊配置，可以创建 AgentFrameworkAspire.AppHost/appsettings.Development.json：

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    }
  },
  "Parameters": {
    "openai-endpoint": "https://your-dev-api.com/v1",
    "openai-apikey": "your-dev-key",
    "openai-deployment": "gpt-4"
  }
}

注意：appsettings.Development.json 会覆盖 appsettings.json 中的配置。

环境变量配置（高级）

你也可以通过环境变量覆盖配置（优先级最高）：

# Windows PowerShell
$env:Parameters__openai-endpoint = "https://api.openai.com/v1"
$env:Parameters__openai-apikey = "your-api-key"
$env:Parameters__openai-deployment = "gpt-4"

# 然后启动
dotnet run

服务端点

启动后，各服务的端点如下（端口由 Aspire 动态分配，可在 Dashboard 中查看）：

架构特点

1. 微服务架构：每个业务领域独立部署，职责清晰
2. 标准化协议：使用 A2A 和 MCP 实现服务间标准化通信
3. 智能体分层：

- 简单 Agent（第二层）：Finance, Tech, HumanResource - 专家 Agent（第三层）：QA, PMO（内部使用 Workflow） - 编排 Agent（第四层）：ProjectManager（跨服务编排）

1. 统一配置：通过 Aspire AppHost 统一管理所有服务配置
2. 可观测性：集成 OpenTelemetry 追踪和监控

开发指南

项目代码组织

了解项目的关键文件和代码结构：

添加新的 MCP 工具

在任何微服务的 Program.cs 中添加新工具：

[McpServerToolType]
public class YourCustomTools
{
    [McpServerTool(Description = "工具描述")]
    public Task YourMethod(
        [ToolParameter(Required = true)] string param1,
        [ToolParameter(Required = false)] int? param2)
    {
        // 实现你的业务逻辑
        var result = new { 
            status = "success",
            data = "your data" 
        };
        
        return Task.FromResult(new CallToolResult
        {
            Content = [new TextContentBlock { 
                Text = JsonSerializer.Serialize(result) 
            }]
        });
    }
}

// 注册到 MCP Server
mcpServer.AddToolType();

添加新的 MCP 资源

[McpServerResourceType]
public class YourCustomResources
{
    [McpServerResource(
        UriTemplate = "your://resource/{id}", 
        Name = "Resource Name",
        Description = "Resource Description")]
    public Task GetResource(string id)
    {
        var data = FetchYourData(id);
        
        return Task.FromResult(new ReadResourceResult
        {
            Contents = [new TextResourceContents
            {
                Uri = $"your://resource/{id}",
                MimeType = "application/json",
                Text = JsonSerializer.Serialize(data)
            }]
        });
    }
}

// 注册到 MCP Server
mcpServer.AddResourceType();

创建简单智能体（第二层）

简单智能体使用 ChatClient 直接集成 MCP 工具：

public class YourSimpleAgent
{
    private readonly IChatClient _chatClient;
    private readonly McpClient _toolsClient;
    
    public YourSimpleAgent(IChatClient chatClient, McpClient toolsClient)
    {
        _chatClient = chatClient;
        _toolsClient = toolsClient;
    }
    
    public void Attach(ITaskManager taskManager)
    {
        taskManager.OnMessageReceived = ProcessMessageAsync;
    }
    
    private async Task ProcessMessageAsync(
        MessageSendParams messageSendParams,
        CancellationToken cancellationToken)
    {
        var userMessage = messageSendParams.Message.Content.FirstOrDefault()?.Text ?? "";
        
        // 构建聊天上下文
        var messages = new List
        {
            new ChatMessage(ChatRole.System, "你是一个专业的XX助手..."),
            new ChatMessage(ChatRole.User, userMessage)
        };
        
        // 调用 AI（自动使用 MCP 工具）
        var response = await _chatClient.CompleteAsync(
            messages, 
            cancellationToken: cancellationToken);
        
        return new A2AResponse
        {
            Message = new Message
            {
                Role = "assistant",
                Content = [new TextContent { Text = response.Message.Text }]
            }
        };
    }
}

创建专家智能体（第三层）

专家智能体使用 Agent Framework 的 Workflow 实现多阶段分析：

public class YourExpertAgent
{
    private readonly Workflow _analysisWorkflow;
    
    public YourExpertAgent(IChatClient chatClient, McpClient toolsClient)
    {
        // 定义多个子智能体
        var stage1Agent = new ChatClientAgent(
            chatClient, 
            "第一阶段专家指令...");
        
        var stage2Agent = new ChatClientAgent(
            chatClient, 
            "第二阶段专家指令...");
        
        var stage3Agent = new ChatClientAgent(
            chatClient, 
            "第三阶段专家指令...");
        
        // 构建工作流：stage1 → stage2 → stage3
        _analysisWorkflow = new WorkflowBuilder(stage1Agent)
            .AddEdge(stage1Agent, stage2Agent)
            .AddEdge(stage2Agent, stage3Agent)
            .Build();
    }
    
    public void Attach(ITaskManager taskManager)
    {
        taskManager.OnMessageReceived = ProcessMessageAsync;
    }
    
    private async Task ProcessMessageAsync(
        MessageSendParams messageSendParams,
        CancellationToken cancellationToken)
    {
        var userMessage = messageSendParams.Message.Content.FirstOrDefault()?.Text ?? "";
        
        // 执行工作流
        var result = await _analysisWorkflow.ExecuteAsync(
            userMessage, 
            cancellationToken);
        
        return new A2AResponse
        {
            Message = new Message
            {
                Role = "assistant",
                Content = [new TextContent { Text = result }]
            }
        };
    }
}

添加新的微服务

1. 创建新项目：

dotnet new webapi -n YourNewService
cd YourNewService
dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.AI.Agents
dotnet add package ModelContextProtocol
dotnet add package A2A.Protocol

1. 在 AppHost 中注册（AgentFrameworkAspire.AppHost/Program.cs）：

var yourService = builder.AddProject
("yournewservice")
    .WithEnvironment("OpenAI__Endpoint", openAiEndpoint)
    .WithEnvironment("OpenAI__ApiKey", openAiApiKey)
    .WithEnvironment("OpenAI__DeploymentName", openAiDeploymentName);

// 在 webfrontend 中引用
builder.AddProject
("webfrontend")
    // ... 其他配置
    .WithReference(yourService)
    .WaitFor(yourService);

1. 实现服务逻辑（参考现有服务的 Program.cs）

调试技巧

1. 查看服务日志：在 Aspire Dashboard 中点击对应服务查看实时日志
2. 追踪请求链路：使用 Dashboard 的 Traces 视图查看跨服务调用
3. 单独调试服务：在 VS Code 中设置断点，然后单独启动某个服务
4. 查看 MCP 工具列表：访问 `http://localhost:

//mcp` 查看可用工具

测试建议

# 测试单个微服务
cd Finance
dotnet test

# 测试整个解决方案
dotnet test

# 运行特定测试
dotnet test --filter "FullyQualifiedName~FinanceTests"

代码规范

• ✅ 使用 async/await 处理异步操作
• ✅ 为 MCP 工具添加详细的 Description 和参数说明
• ✅ 智能体的系统提示词（System Prompt）要清晰明确
• ✅ 处理好异常和错误场景
• ✅ 使用结构化日志（Serilog）
• ✅ 遵循 SOLID 原则

📚 更多资源

• 详细文档：查看 /docs 目录下的系列文档

- 入门手册-Multi-Agent-Microservices快速上手.md：适合初学者 - 进阶手册-Multi-Agent-Microservices深度实战.md：适合进阶开发 - 博客1-从业务痛点出发.md：理解项目背景 - 博客2-三大协议深度解析.md：理解 MCP、A2A、Agent Framework - 博客3-Aspire实战演练.md：Aspire 编排实战 - 博客4-从Demo到生产.md：生产环境部署

• 参考文档：

- .NET Aspire 官方文档 - Microsoft Agent Framework - Model Context Protocol (MCP) - Anthropic - A2A Protocol - Google Cloud - A2A .NET SDK (社区实现)

• 源码参考：/component_source_code_reference 目录包含第三方库的源码，方便学习

🤝 贡献

欢迎贡献代码、文档或提出问题！

1. Fork 本仓库（https://github.com/MadLongTom/A2AMicroserviceSample）
2. 创建你的特性分支（git checkout -b feature/AmazingFeature）
3. 提交你的更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 开启一个 Pull Request

📄 License

本项目采用 WTFPL License - 详见 LICENSE 文件。

简单来说：你可以对这个项目做任何你想做的事情。

⭐ Star History

如果这个项目对你有帮助，请给个 Star ⭐ 支持一下！

Made with ❤️ by MadLongTom

项目地址：https://github.com/MadLongTom/A2AMicroserviceSample

注意事项

1. API密钥安全: 不要将 API 密钥提交到版本控制系统
2. Mock数据: 当前工具实现使用 Mock 数据，生产环境需要连接真实系统
3. 并发限制: 注意 OpenAI API 的速率限制
4. 错误处理: 生产环境需要添加完善的错误处理和重试机制

故障排查

服务无法启动

• 检查 .NET 9.0 SDK 是否安装
• 检查 Docker Desktop 是否运行
• 检查端口是否被占用

OpenAI API 错误

• 验证 API Key 是否正确
• 检查网络连接
• 确认 API 配额是否充足

Workflow Agent 无响应

• 检查 ChatClient 配置是否正确
• 查看服务日志了解详细错误信息

参考文档

• .NET Aspire
• Microsoft Agent Framework
• A2A Protocol - Google Cloud
• A2A .NET SDK (社区实现)
• Model Context Protocol - Anthropic
• MCP .NET SDK

许可证

本项目遵循 MIT 许可证。