Skip to content

About

Build Azure documentation assistant with Microsoft Agent Framework, Agent Skills and MCP

Resources

Stars

3 stars

Watchers

0 watching

Forks

Repository files navigation

Azure Doc Agent - Skills & MCP

一个基于 Microsoft Agent Framework 的智能文档助手,集成了 Agent Skills 和 MCP(Model Context Protocol)。

🌟 核心特性

🎯 渐进式披露架构

关键设计1:所有MCP工具在初始化时注册,SKILL.md指导Agent何时使用它们

  • 所有MCP Server的工具在Agent初始化时一次性注册
  • SKILL.md通过文字说明告诉Agent在什么情况下使用哪些工具
  • 不同Skill可以指导使用不同MCP Server的工具
  • 完美支持多MCP Server扩展,易于添加新的Skills和MCP集成

关键设计2:LLM智能Skill匹配(无需硬编码关键词)

  • 使用LLM理解用户意图,智能匹配最相关的Skill
  • 支持任何语言(中文、英文、混合等)、任何表达方式
  • 无需为每个Skill维护关键词列表
  • 关键词匹配作为fallback确保稳定性

📖 详细架构说明: docs/ARCHITECTURE.md
📝 技术细节请参考: 中文技术博客

其他特性

  • 🎨 Modern Web UI: React + TypeScript + Vite 前端界面
  • 🤖 Agent Skills 集成: 基于 agentskills.io 标准的技能发现和动态注入
  • 🔌 MCP 客户端: 连接 Microsoft Learn MCP Server,访问官方文档
  • 💬 多轮对话: 支持线程管理和对话上下文维护
  • 🧠 短期记忆: In-memory 对话历史保留
  • ⚡ 异步架构: 使用 asyncio 实现高性能并发
  • 📡 REST API: FastAPI 后端服务
  • 💭 Thinking显示: 实时展示Agent的思考过程(Skill匹配、激活、工具选择)

📁 项目结构

AzureDoc_Skills_MCP/
├── src/                          # 源代码目录
│   ├── azure_doc_agent.py       # 主 Agent 类(渐进式披露逻辑)
│   ├── api_server.py            # FastAPI 后端服务器
│   ├── registry.py              # 技能注册表
│   ├── injector.py              # 技能注入器(按需加载完整SKILL.md)
│   ├── llm_matcher.py           # LLM 智能技能匹配(91.3% 准确率)
│   ├── mcp_client.py            # MCP 客户端(多MCP Server支持)
│   └── system_prompts.py        # 系统提示管理
├── frontend/                     # React 前端
│   ├── src/
│   │   ├── components/          # React 组件
│   │   ├── services/            # API 服务
│   │   ├── styles/              # 样式文件
│   │   ├── types/               # TypeScript 类型定义
│   │   ├── App.tsx              # 主应用组件
│   │   └── main.tsx             # 入口文件
│   ├── package.json
│   └── vite.config.ts
├── skills/                       # 技能定义目录
│   ├── microsoft-docs/          # 文档搜索技能
│   │   └── SKILL.md            # 指导使用 microsoft_docs_search/fetch
│   └── microsoft-code-reference/ # 代码参考技能
│       └── SKILL.md            # 指导使用 microsoft_code_sample_search
├── docs/                         # 文档目录
│   ├── ARCHITECTURE.md          # 完整架构说明
│   ├── BLOG_POST.md             # 英文技术博客
│   ├── BLOG_POST_CN.md          # 中文技术博客
│   ├── DIAGRAMS.md              # Mermaid 架构图表
│   ├── TROUBLESHOOTING.md       # 故障排查指南
│   ├── PROJECT_CLEANUP_SUMMARY.md # 项目清理总结
│   └── images/                  # 文档图片
│       ├── 问题1.jpg
│       └── 问题2.jpg
├── main.py                       # CLI 程序入口
├── start.sh                      # 总启动脚本(前端+后端)
├── start_backend.sh              # 后端启动脚本
├── start_frontend.sh             # 前端启动脚本
├── setup.sh                      # 安装脚本
├── setup-frontend.sh             # 前端安装脚本
├── requirements.txt              # Python 依赖
├── .env.example                  # 环境变量示例
├── Dockerfile                    # Docker 镜像配置
├── docker-compose.yml            # Docker Compose 配置
├── INDEX.md                      # 文档导航索引
├── QUICKSTART.md                 # 快速开始指南
├── PROJECT_STRUCTURE.md          # 项目结构详解
├── DEPLOYMENT.md                 # 部署指南
└── README.md                     # 项目文档

实机演示

实际问题1

实际问题2

🏗️ 架构亮点

渐进式披露的三个层面

  1. Skill层面: metadata常驻内存,完整内容匹配后按需加载
  2. 工具层面: 所有MCP工具预先注册,SKILL.md指导何时使用
  3. 扩展层面: 多MCP Server共存,不同Skill指导不同工具

查询处理流程

用户查询 → Skill匹配 (min_score=50)
         ↓
         匹配成功? → 加载完整SKILL.md → 注入Agent Context
         ↓                                ↓
         匹配失败  →  通用对话            Agent根据SKILL.md指导选择工具

示例:

  • "Azure Functions文档" → 匹配microsoft-docs → Agent使用microsoft_docs_search
  • "Python代码示例" → 匹配microsoft-code-reference → Agent使用microsoft_code_sample_search
  • "hello world" → 无匹配 → 通用对话(不使用MCP工具)

🚀 快速开始

方式 1: Web UI(推荐)

# 1. 安装 Python 依赖
pip install -r requirements.txt

# 2. 安装前端依赖
./setup-frontend.sh

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env 填写 Azure OpenAI 配置

# 4. 启动服务器(后端 + 前端)
./start.sh

访问:

方式 2: CLI 模式

# 1. 安装依赖
pip install -r requirements.txt

# 2. 配置环境
cp .env.example .env

# 3. 运行 CLI
python main.py

💡 使用示例

基本对话

from src.azure_doc_agent import AzureDocAgent
import asyncio

async def main():
    # 初始化 Agent
    agent = AzureDocAgent(
        azure_openai_endpoint="https://your-resource.openai.azure.com/",
        azure_openai_key="your-key",
        azure_openai_deployment="gpt-4o"
    )
    
    await agent.initialize()
    
    # 创建对话线程
    thread_id = agent.create_thread()
    
    # 发送消息
    response = await agent.chat(
        "我需要了解 Azure Functions 的端到端教程"
    )
    
    print(response)
    
    await agent.close()

asyncio.run(main())

多线程对话

# 创建多个对话线程
thread1 = agent.create_thread("azure-functions")
thread2 = agent.create_thread("cosmos-db")

# 在不同线程中对话
await agent.chat("Azure Functions 概述", thread_id=thread1)
await agent.chat("Cosmos DB 分区策略", thread_id=thread2)

# 切换线程
agent.switch_thread(thread1)
await agent.chat("如何部署 Azure Functions?")

🎯 核心组件

1. Skill Registry(技能注册表)

自动发现和索引 skills/ 目录下的所有技能:

registry = SkillRegistry("skills")
skill_count = registry.discover_skills()
skills = registry.list_skills()

2. Skill Injector(技能注入器)

动态激活技能并注入到对话上下文:

injector = SkillInjector(registry)
content = injector.activate_skill("microsoft-docs")

3. MCP Client(MCP 客户端)

连接 Microsoft Learn MCP Server:

mcp_client = MCPClient("https://learn.microsoft.com/api/mcp")
await mcp_client.initialize()

# 搜索文档
results = await mcp_client.search_docs("Azure Functions", max_results=5)

# 获取完整文档
content = await mcp_client.fetch_doc("https://learn.microsoft.com/...")

4. System Prompts Manager(系统提示管理器)

动态生成系统提示:

prompts_manager = SystemPromptsManager(registry, injector)
system_prompt = prompts_manager.build_full_system_prompt()

🔧 技能系统

技能定义格式

每个技能包含一个 SKILL.md 文件,使用 YAML front matter 定义元数据:

---
name: microsoft-docs
description: Query official Microsoft documentation
context: fork
compatibility: Requires Microsoft Learn MCP Server
tags: ["documentation", "microsoft", "azure"]
---

# Microsoft Docs

## Tools
...

添加新技能

  1. 在 skills/ 下创建新目录
  2. 添加 SKILL.md 文件
  3. Agent 启动时自动发现

📊 工作流程

用户查询
    ↓
Skill Registry 搜索相关技能
    ↓
Skill Injector 激活技能
    ↓
动态更新系统提示
    ↓
LLM 决定使用的工具
    ↓
调用 MCP 或激活更多技能
    ↓
返回结果给用户

🛠️ 开发

运行测试

pytest tests/

代码格式化

black src/
flake8 src/
mypy src/

📝 配置说明

环境变量

变量 说明 默认值
AZURE_OPENAI_ENDPOINT Azure OpenAI / AI Foundry 端点 -
AZURE_OPENAI_KEY API 密钥 -
AZURE_OPENAI_DEPLOYMENT 模型部署名称 gpt-4o
MCP_SERVERS MCP 服务器列表(逗号分隔) ms-learn
SKILLS_DIRECTORY 技能目录 skills
LOG_LEVEL 日志级别 INFO
MAX_HISTORY_LENGTH 最大历史消息数 20

💡 AI Foundry 用户: 使用 AI Foundry 中的模型时,AZURE_OPENAI_ENDPOINT 填写您的 AI Foundry 项目端点,格式相同。

🔗 相关链接

📞 支持

如有问题,请提交 Issue 或联系维护者。

About

Build Azure documentation assistant with Microsoft Agent Framework, Agent Skills and MCP

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages