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

[![License: WTFPL](https://img.shields.io/badge/License-WTFPL-brightgreen.svg)](http://www.wtfpl.net/about/)
[![.NET](https://img.shields.io/badge/.NET-9.0-blue.svg)](https://dotnet.microsoft.com/)
[![Aspire](https://img.shields.io/badge/Aspire-Latest-purple.svg)](https://learn.microsoft.com/dotnet/aspire/)

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

## 📖 目录

- [项目背景](#项目背景)
- [项目目标](#项目目标)
- [架构设计](#架构设计)
- [技术栈](#技术栈)
- [项目结构](#项目结构)
- [服务说明](#服务说明)
- [快速开始](#快速开始)
- [配置说明](#配置说明)
- [开发指南](#开发指南)
- [License](#license)

## 🌟 项目背景

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

### 传统方案的痛点

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

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

3. **不符合组织结构**
   - 违背企业实际的分工协作模式
   - 责任不清晰，出错难以追溯

### 我们的方案

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

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

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

## 🎯 项目目标

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

## 🏗️ 架构设计

### 整体架构

```mermaid
graph TB
    subgraph "用户交互层"
        User[👤 用户/客户端<br/>Blazor Web UI]
    end
    
    subgraph "智能编排层"
        PM[🎯 项目经理智能体<br/>ProjectManagerAgent<br/>━━━━━━━━━━━<br/>统一协调与决策<br/>3阶段工作流编排]
    end
    
    subgraph "专业服务层 - 并行分析"
        Tech[💻 技术团队服务<br/>Tech Agent<br/>━━━━━━━━━━━<br/>MCP工具 + A2A端点]
        HR[👥 HR团队服务<br/>HR Agent<br/>━━━━━━━━━━━<br/>MCP工具 + A2A端点]
        Finance[💰 财务团队服务<br/>Finance Agent<br/>━━━━━━━━━━━<br/>MCP工具 + A2A端点]
        QA[🔍 QA团队服务<br/>QA Agent<br/>━━━━━━━━━━━<br/>MCP工具 + A2A端点<br/>内部4阶段工作流]
    end
    
    subgraph "专业服务层 - 规划整合"
        PMO[📅 PMO团队服务<br/>PMO Agent<br/>━━━━━━━━━━━<br/>MCP工具 + A2A端点<br/>内部4阶段工作流]
    end
    
    subgraph "基础设施层"
        Aspire[.NET Aspire<br/>服务编排 & 配置管理]
        MCP[MCP 协议层<br/>工具与资源访问]
        A2A[A2A 协议层<br/>智能体间通信]
        AF[Agent Framework<br/>工作流编排引擎]
    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 阶段工作流编排：

```mermaid
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: 内部工作流:<br/>任务分解→依赖分析<br/>→资源匹配→时间优化
    PMO-->>PM: 详细项目计划
    
    Note over PM: Stage 3: 整合决策阶段
    PM->>PM: 综合所有分析结果<br/>生成最终决策
    PM-->>User: 完整项目计划与建议
```

### 智能体分层架构

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

```mermaid
graph TD
    subgraph "第四层：编排智能体层"
        L4[项目经理智能体<br/>━━━━━━━━━━━<br/>跨团队协调<br/>复杂工作流编排<br/>最终决策]
    end
    
    subgraph "第三层：专家智能体层"
        L3A[QA 风险管理专家<br/>━━━━━━━━━━━<br/>内部工作流:<br/>识别→评估→缓解→监控]
        L3B[PMO 进度规划专家<br/>━━━━━━━━━━━<br/>内部工作流:<br/>分解→依赖→匹配→优化]
    end
    
    subgraph "第二层：简单智能体层"
        L2A[Tech 需求分析<br/>━━━━━━━━━━━<br/>单一职责<br/>直接调用工具]
        L2B[HR 资源评估<br/>━━━━━━━━━━━<br/>单一职责<br/>直接调用工具]
        L2C[Finance 预算分析<br/>━━━━━━━━━━━<br/>单一职责<br/>直接调用工具]
    end
    
    subgraph "第一层：MCP 工具层"
        L1A[EstimateTechnicalComplexity<br/>ValidateTechStack<br/>GetArchitectureTemplate]
        L1B[GetTeamCapabilities<br/>CheckTeamAvailability<br/>EstimateResourceCost]
        L1C[ValidateBudget<br/>GetHistoricalCosts<br/>CalculateROI]
        L1D[AnalyzeRiskPatterns<br/>GetComplianceRequirements<br/>ValidateDeliverables]
        L1E[GetProjectTemplate<br/>ValidateSchedule<br/>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. **第四层 - 编排智能体层**：跨领域协调，统一用户接口，最终决策

## 🛠️ 技术栈

| 类别 | 技术 | 版本 | 说明 |
|------|------|------|------|
| **框架** | .NET | 9.0 | 最新的 .NET 平台 |
| **Web** | ASP.NET Core | 9.0 | 微服务框架 |
| **前端** | Blazor Server | 9.0 | 服务端渲染 UI |
| **编排** | .NET Aspire | Latest | 云原生应用编排 |
| **AI 框架** | Microsoft Agent Framework | Preview | 智能体工作流引擎 |
| **协议** | A2A (Agent-to-Agent) | Latest | 智能体间通信协议 (Google Cloud) |
| **协议** | MCP (Model Context Protocol) | Preview | 模型上下文协议 (Anthropic) |
| **AI 服务** | OpenAI API | GPT-4 | 大语言模型 |
| **监控** | OpenTelemetry | Latest | 可观测性 |

## 项目结构

```
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 ([下载](https://dotnet.microsoft.com/download/dotnet/9.0))
- ✅ Docker Desktop ([下载](https://www.docker.com/products/docker-desktop))
- ✅ OpenAI API Key 或兼容的 API 服务

### 第一步：克隆项目

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

### 第二步：配置 OpenAI API

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

```json
{
  "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-endpoint` | API 端点（可选）<br/>- 留空：使用 OpenAI 官方 API<br/>- 填写：使用第三方兼容 API | `""`<br/>`"https://api.openai.com/v1"`<br/>`"https://your-proxy.com/v1"` |
| `openai-apikey` | API 密钥（必填）<br/>从 OpenAI 或第三方服务获取 | `"sk-..."` |
| `openai-deployment` | 模型名称（必填）<br/>选择要使用的模型 | `"gpt-4o-mini"`<br/>`"gpt-4"`<br/>`"gpt-3.5-turbo"` |

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

### 第三步：恢复依赖

```powershell
dotnet restore
```

### 第四步：启动项目

```powershell
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`：

```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` 中的配置。

### 环境变量配置（高级）

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

```powershell
# 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 中查看）：

| 服务 | MCP 端点 | A2A 端点 | 说明 |
|------|---------|---------|------|
| **Finance** | `/finance/mcp` | `/finance/budget-analyzer` | 财务分析智能体 |
| **Tech** | `/tech/mcp` | `/tech/requirement-analyst` | 技术需求分析智能体 |
| **HumanResource** | `/hr/mcp` | `/hr/resource-estimator` | 人力资源评估智能体 |
| **QA** | `/qa/mcp` | `/qa/risk-expert` | 风险管理专家智能体 |
| **PMO** | `/pmo/mcp` | `/pmo/schedule-expert` | 进度规划专家智能体 |
| **Web Frontend** | - | - | 项目经理智能体 UI |

## 架构特点

1. **微服务架构**：每个业务领域独立部署，职责清晰
2. **标准化协议**：使用 A2A 和 MCP 实现服务间标准化通信
3. **智能体分层**：
   - **简单 Agent**（第二层）：Finance, Tech, HumanResource
   - **专家 Agent**（第三层）：QA, PMO（内部使用 Workflow）
   - **编排 Agent**（第四层）：ProjectManager（跨服务编排）
4. **统一配置**：通过 Aspire AppHost 统一管理所有服务配置
5. **可观测性**：集成 OpenTelemetry 追踪和监控

## 开发指南

### 项目代码组织

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

| 路径 | 说明 | 重要性 |
|------|------|--------|
| `AgentFrameworkAspire.AppHost/Program.cs` | Aspire 编排配置，参数注入 | ⭐⭐⭐ |
| `AgentFrameworkAspire.Web/Services/ProjectManagerAgent.cs` | 项目经理智能体核心逻辑 | ⭐⭐⭐ |
| `AgentFrameworkAspire.ServiceDefaults/AgentHelpers.cs` | ChatClient 和 MCP 工厂方法 | ⭐⭐⭐ |
| `Finance/Program.cs` | 财务服务：MCP 工具 + A2A 端点 | ⭐⭐ |
| `Tech/Program.cs` | 技术服务：MCP 工具 + A2A 端点 | ⭐⭐ |
| `HumanResource/Program.cs` | HR 服务：MCP 工具 + A2A 端点 | ⭐⭐ |
| `QA/Program.cs` | QA 服务：4 阶段工作流 | ⭐⭐ |
| `PMO/Program.cs` | PMO 服务：4 阶段工作流 | ⭐⭐ |

### 添加新的 MCP 工具

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

```csharp
[McpServerToolType]
public class YourCustomTools
{
    [McpServerTool(Description = "工具描述")]
    public Task<CallToolResult> 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<YourCustomTools>();
```

### 添加新的 MCP 资源

```csharp
[McpServerResourceType]
public class YourCustomResources
{
    [McpServerResource(
        UriTemplate = "your://resource/{id}", 
        Name = "Resource Name",
        Description = "Resource Description")]
    public Task<ReadResourceResult> 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<YourCustomResources>();
```

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

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

```csharp
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<A2AResponse> ProcessMessageAsync(
        MessageSendParams messageSendParams,
        CancellationToken cancellationToken)
    {
        var userMessage = messageSendParams.Message.Content.FirstOrDefault()?.Text ?? "";
        
        // 构建聊天上下文
        var messages = new List<ChatMessage>
        {
            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 实现多阶段分析：

```csharp
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<A2AResponse> 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. **创建新项目**：

```powershell
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
```

2. **在 AppHost 中注册**（`AgentFrameworkAspire.AppHost/Program.cs`）：

```csharp
var yourService = builder.AddProject<Projects.YourNewService>("yournewservice")
    .WithEnvironment("OpenAI__Endpoint", openAiEndpoint)
    .WithEnvironment("OpenAI__ApiKey", openAiApiKey)
    .WithEnvironment("OpenAI__DeploymentName", openAiDeploymentName);

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

3. **实现服务逻辑**（参考现有服务的 `Program.cs`）

### 调试技巧

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

### 测试建议

```powershell
# 测试单个微服务
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 官方文档](https://learn.microsoft.com/dotnet/aspire/)
  - [Microsoft Agent Framework](https://github.com/microsoft/semantic-kernel)
  - [Model Context Protocol (MCP) - Anthropic](https://modelcontextprotocol.io/)
  - [A2A Protocol - Google Cloud](https://cloud.google.com/agentspace/docs/agent-to-agent)
  - [A2A .NET SDK (社区实现)](https://github.com/microsoft/a2a-dotnet)

- **源码参考**：`/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](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](https://learn.microsoft.com/dotnet/aspire/)
- [Microsoft Agent Framework](https://github.com/microsoft/agent-framework)
- [A2A Protocol - Google Cloud](https://cloud.google.com/agentspace/docs/agent-to-agent)
- [A2A .NET SDK (社区实现)](https://github.com/microsoft/a2a-dotnet)
- [Model Context Protocol - Anthropic](https://modelcontextprotocol.io/)
- [MCP .NET SDK](https://github.com/microsoft/mcp-dotnet)

## 许可证

本项目遵循 MIT 许可证。