基于MS代理框架的多代理系统（MCP协议集成）
这个项目 Microsoft代理框架 （Azure AI Agent服务）和\*\*使用模型上下文协议（MCP）\*\*实现的多代理系统示例。 通过HR入门方案 身份、IT、培训 专业代理合作 计划（Plan）→批准（Approve）→执行（Execute） 显示执行工作流的过程。
关键更改和功能
- 添加模型上下文协议（MCP）支持:
- 4种MCP服务器集成：与提供HR（人事）、Sales（销售额）、Supply Chain（库存）和Weather（天气）专业工具的MCP服务器相结合。 - 注册动态工具：在创建代理时，所选MCP协议中的工具将自动注册为Azure AI Agent的Function Calling工具。 - 扩展的UI：在前端创建代理时，您可以选择所需的MCP服务作为复选框，相关示例问题将自动添加到提示中。
- 基于Azure AI Agent的入站:
- 代替传统的模拟代理 实际Azure AI Agent使用执行Identity、IT和Training操作。 - 通过异步任务处理和状态管理提供可靠的工作流。
- 工作流（Plan→Approve→Execute）:
1. 计划：分析用户输入（名称、角色），制定代理所需的资源计划。 1. 批准：用户审阅并批准AI提出的计划。 1. 执行：根据批准的计划，每个代理并行运行任务。
- 代理内存持续性（Agent Memory）:
- 通过保留与每个代理（Identity、IT、Training）的聊天线程（Thread），用户可以随时继续之前的对话。
- UI/UX改进和本地化:
- 改进了直观的时间轴UI和Markdown渲染。 - 所有代理响应和系统消息 韩语 支援。
🏗️ 体系结构和技术堆栈（Architecture&Tech Stack）
1.MCP（模型上下文协议）란?
\*\*MCP（Model Context Protocol）\*\*是一种开放协议，用于标准化AI模型与外部系统（数据、工具、资源）之间的通信。该项目通过MCP动态地向代理提供不同域的工具。
为什么是MCP？ (Why MCP?) 开发AI代理的最大瓶颈是“集成”。
- 传统方式：必须针对天气API、HR DB和CRM系统分别编写单独的联动代码和函数定义。
- MCP方式：所有服务均符合MCP标准（例如：
tools/list,resources/read），只需一个客户端实现即可实现无限的可扩展性。如果需要新工具，只需打开新的MCP服务器，而不是修改代码。
2.项目体系结构（Architecture）
这个样品 MCP主机哇 MCP服务器 作为结构运行。
- MCP主机（后端API）:
- src/backend/mcp_manager.py充当MCP客户端。 - 创建代理时，连接到选定的MCP服务器，查看可用工具列表。 - 将这些工具自动转换为Azure AI Agent可以理解的OpenAI Function Calling格式并进行注册。
- MCP服务器（Python实现）:
每台服务器以独立的进程运行，并通过Server-Sent Events（SSE）进行通信。
服务器名称端口主要功能数据源 | :--- | :--- | :--- | :--- | | 人力资源政策 | 8003 | get_hiring_policy（招聘政策）， check_employee_leave（假期剩余日）| policy.md, employees.json | | 销售CRM | 8001 | get_customer_profile（客户信息） get_sales_leads（机会）| customers.json | | 供应链 | 8002 | check_inventory（库存确认）， track_shipment（发货跟踪）| inventory.json | | 天气 | 8004 | get_current_weather（查询天气）， get_forecast（查询预报）Mock Data
3.技术堆栈（Tech Stack）
后端
- 语言：Python 3.10+
- 框架：FastAPI（异步支持）
- AI SDK：Azure AI项目客户端（代理框架）
- 协议：模型上下文协议（MCP）客户端实现
- 建筑：模块化路由器和基于服务的设计
前端
- 框架：React 18，TypeScript
- 构建工具：快
- 样式：顺风CSS
- 组件：自定义UI组件，Lucide图标
- 整合：用于后端通信的REST API客户端
4.执行流（Execution Flow）
用户问\*\*“请告诉我金哲秀职员的剩余休假天数”\*\*时的处理过程。
- 意图：Azure AI Agent分析问题
check_employee_leave(name="김철수")我们认为需要调用工具。 - 请求：代理请求后端（Host）执行函数（Requires Action）。
- 路由：后端标识此请求是“HR Policy”MCP服务器的工具。
- 呼叫：后端（MCP客户端）
localhost:8003（HR Server）tools/call发送请求。 - 响应：HR服务器在JSON文件中查找金哲秀的信息
{ "leave_balance": 15 }返回。 - 回答：代理根据这些数据回答说：“金哲秀剩下的假期是15天。”
📁 项目结构（已更新）
src/
backend/ # FastAPI 백엔드 (Port: 8000)
routers/
agents.py # 에이전트 관리 (Azure AI Agent 연동)
workflows.py # HR 온보딩 워크플로우 로직
...
mcp_manager.py # MCP 서버 연결 및 도구 변환 로직
client.py # Azure AI Project Client 설정
main.py # 앱 진입점
frontend/ # React + Vite 프론트엔드 (Port: 5173)
src/
App.tsx # 메인 대시보드 (Chat & Workflow UI)
api/ # 백엔드 연동 API 모듈
...
mcp/ # MCP (Model Context Protocol) 서버 그룹
mcp-hr-policy/ # HR 정책 및 직원 휴가 데이터 (Port: 8003)
mcp-sales-crm/ # 판매 데이터 및 CRM (Port: 8001)
mcp-supply-chain/ # 재고 및 공급망 데이터 (Port: 8002)
mcp-weather/ # 실시간 날씨 정보 (Port: 8004)
start_all.ps1 # 전체 시스템 원클릭 시작 스크립트
stop_all.ps1 # 시스템 종료 및 프로세스 정리 스크립트
tests/ # 백엔드 테스트 코드史前要求（Prerequisites）
- Python3.9或更高版本
- Node.js 18+和npm
安装和设置（Installation&Setup）
1.库安装（Library Installation）
后端（Python）
# 가상환경 생성 및 활성화
python -m venv .venv
.\.venv\Scripts\Activate.ps1
# 의존성 설치
pip install -r requirements.txt前端（Node.js）
cd src/frontend
npm install2.环境配置（Environment Configuration）
这个项目 Azure人工智能项目 及 Azure OpenAI 使用服务。运行前需要设置环境变量。
src/backend/.env 创建文件并输入信息：
# Azure AI Project 연결 문자열 (Azure AI Studio -> Project Settings에서 확인 가능)
AZURE_AI_PROJECT_CONNECTION_STRING=""
# Azure AI Project 이름
AZURE_AI_PROJECT_NAME=""
# Azure AI Services 리소스 이름
AZURE_AI_SERVICE_NAME=""
# Azure 환경 이름 (예: dev, prod)
AZURE_ENV_NAME=""
# Azure Key Vault 엔드포인트 URL
AZURE_KEY_VAULT_ENDPOINT=""
# Azure 리전 위치 (예: eastus, koreacentral)
AZURE_LOCATION=""
# Azure OpenAI 모델 배포 이름 (예: gpt-4o)
AZURE_MODEL_DEPLOYMENT_NAME=""
# Azure 리소스 그룹 이름
AZURE_RESOURCE_GROUP=""
# Azure 구독 ID
AZURE_SUBSCRIPTION_ID=""
# Azure 테넌트 ID
AZURE_TENANT_ID=""参考：Connection String可在Azure AI Foundry门户的项目设置中查看。
▶执行服务器（Server Execution）
安装和设置完成后，运行每台服务器。
1.后台运行（Backend）
# 가상환경 활성화 (필요시)
# .\.venv\Scripts\Activate.ps1
uvicorn src.backend.main:app --reload如果服务器正常运行：
INFO: Uvicorn running on http://127.0.0.1:8000
...
Agent Framework API 서버를 시작합니다...
API 문서 (Swagger UI): http://localhost:8000/docs2.前端执行（Frontend）
cd src/frontend
npm run dev
# or
npm run dev --prefix src/frontend3.运行MCP服务器（MCP服务器）
代理必须运行相应的MCP服务器才能使用该工具。（在单独的终端上运行或 start_all.ps1 使用）
# 환경 변수 설정 (PowerShell)
$env:PYTHONPATH='.'
# 1. HR Policy Server (Port: 8003)
python src/mcp/mcp-hr-policy/hr_server.py --sse
# 2. Sales CRM Server (Port: 8001)
python src/mcp/mcp-sales-crm/sales_server.py --sse
# 3. Supply Chain Server (Port: 8002)
python src/mcp/mcp-supply-chain/supply_server.py --sse
# 4. Weather Server (Port: 8004)
python src/mcp/mcp-weather/weather_server.py --sse🚀 快速启动（Quick Start）
安装和首选参数完成所需的软件包后，可以使用PowerShell脚本轻松控制整个系统。
1.启动整个服务
.\start_all.ps1- 4种MCP服务器 （销售、供应、人力资源、天气）
- 后端API服务器 （端口8000）
- 前端开发服务器 （端口5173）
- 上述服务分别在单独的终端窗口中运行。
2.全部服务结束
.\stop_all.ps1- 安全地退出所有运行的Python和Node.js进程，并关闭终端窗口。
📖 API规范和开发指南（API&Development）
服务器运行后，您可以在Web浏览器中通过以下地址查看API文档：
- Swagger用户界面: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
主要API端点
| 组件 | 路径（Prefix） | 说明 |
|---|---|---|
| 系统 | /api/v1 | 服务器状态，健康检查（/health），公制（/telemetry/metrics) |
| 文件 | /api/v1/files | 上传/列表/删除文件 |
| 代理 | /api/v1/agents | 创建/查看/修改/删除AI代理 |
| 线程 | /api/v1/threads | 创建/查询/删除聊天室（主题），管理消息 |
| 跑 | /api/v1/threads/{thread_id}/runs | 运行代理并查看状态 |
| 工作流 | /api/v1/workflows | 工作流列表/运行/状态 |
元件关系和概念
- Agents（大脑和工具）： 定义“谁将工作？”包含模型、系统说明和要使用的工具设置。
- Threads（记忆与对话）： 定义“在哪里谈论？”存储对话记录的状态空间。
- Runs（运行和处理）： 命令“执行任务”。触发任务处理和响应创建。
- Files（知识和数据）： 代理要分析或参考的文档。
- Workflows（编排）： 定义复杂的业务流程或多个代理的协作。
UI开发的API调用顺序（Flow for UI Dev）
在Web前端 AI聊天应用程序实施时的详细API调用流。
示例场景：“分析销售报告的AI助手”
Files API路sales_data.csv上传Agents API使用创建“数据分析师”代理Threads API通过创建新主题，添加问题消息Runs API通过执行请求（Agent+Thread）Runs API确认状态为，Threads API通过查看回复消息
摘要流程图（Sequence Diagram）
sequenceDiagram
participant User as 사용자 (Web UI)
participant API as 백엔드 API (Backend)
User->>API: 1. 에이전트 목록 조회 (GET /agents)
User->>User: 에이전트 선택
User->>API: 2. 스레드 생성 (POST /threads)
API-->>User: thread_id 반환
loop 대화 반복
User->>API: 3. 메시지 전송 (POST /threads/{id}/messages)
User->>API: 4. 실행(Run) 요청 (POST /runs)
API-->>User: run_id 반환
loop 완료될 때까지 (Polling)
User->>API: 5. 상태 확인 (GET /runs/{run_id})
API-->>User: status: "in_progress" -> "completed"
end
User->>API: 6. 답변 조회 (GET /threads/{id}/messages)
API-->>User: 에이전트 답변 반환
User->>User: 화면 업데이트
end🖥️ 前端关键功能
- 选择和创建代理（动态选择MCP工具）
- 创建聊天室（线程）并发送消息
- 附加和上载文件
- 实时查看AI响应
- 支持Markdown渲染
🧪 测试（Testing）
如何运行后端测试
测试 pytest使用运行，在Windows环境中必须指定PYTHONPATH。
激活虚拟环境并运行测试（PowerShell）
cd src/backend
.\.venv\Scripts\Activate.ps1
$env:PYTHONPATH='.'; pytest tests测试结果
如果所有测试都通过，则会输出成功消息。
注意：请注意罚款和资源限制，因为测试可以创建和删除实际的Azure资源。
📚 参考和联系（References&Contact）
- API_规范.md：完整的API规范
/src/frontend/README.md：前端开发指南