# Microsoft Agent Framework playground

**Repository Path**: XiongMingcai/microsoft-agent-framework-playground

## Basic Information

- **Project Name**: Microsoft Agent Framework playground
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-16
- **Last Updated**: 2026-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

以下是专为**Microsoft Agent Framework 1.0**开发的**命令行（Console）练习项目**量身打造的 **README.md** 内容。你可以直接复制到项目根目录的 `README.md` 文件中。

```markdown
# Microsoft Agent Framework 1.0 - 命令行练习项目

一个基于 **Microsoft Agent Framework 1.0** 的 .NET 命令行练习项目，适合快速上手 Agent 开发、练习 Tools、Multi-turn 对话、Memory、Agent Skills 等核心概念。

项目采用 **Console** 应用形式，便于在终端中交互测试，支持热重载（`dotnet watch`）和 Docker 容器化开发。

## 项目目标

- 快速掌握 Microsoft Agent Framework 1.0 的核心抽象（Agent + Tools + Workflow + Skills）
- 通过命令行交互练习多轮对话、工具调用、状态管理
- 结合 **七牛云 DeepSeek-V3.2**（或 Azure OpenAI / OpenAI）进行实际开发
- 为后续扩展到 Web API、多 Agent Workflow、Agent Skills 打好基础

## 技术栈

- **.NET 10.0**（推荐）
- **Microsoft Agent Framework 1.0**（`Microsoft.Agents.AI`）
- **OpenAI 兼容客户端**（支持七牛云、Azure OpenAI、OpenAI 等）
- **Docker + Docker Compose**（开发环境推荐）
- **WSL2 / Windows / macOS** 均支持

## 快速开始

### 1. 前置条件

- .NET 10.0 SDK（`dotnet --version` 确认）
- 七牛云 API Key（或 OpenAI / Azure OpenAI Key）

### 2. 克隆 / 初始化项目

```bash
cd  ~/Projects/MyAgentApp 
dotnet new console -o . -f net10.0
```

### 3. 安装依赖包

```bash
dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.OpenAI
dotnet add package OpenAI
```

### 4. 配置环境变量

在项目根目录创建 `.env` 文件（推荐）或直接设置系统环境变量：

```env
AI_API_KEY=sk-6919ff07991c65c**********
AI_BASE_URI=https://api.qnaigc.com/v1
AI_MODEL=deepseek-v3-tool

```

### 5. 运行项目

```bash
# 普通运行
dotnet run

# 推荐：使用热重载开发
dotnet watch run
```

启动后在终端输入问题即可与 Agent 交互，输入 `exit` 或 `quit` 退出。

## 项目结构

```
MyAgentConsolePractice/
├── global.json                 # 锁定 .NET SDK 版本
├── Program.cs                  # 主程序（Agent 初始化 + 交互循环）
├── appsettings.json            # 配置（可选）
├── Dockerfile.dev              # 开发用 Docker
├── docker-compose.yml          # Docker Compose（双向绑定）
├── .env                        # 环境变量（不提交 Git）
└── README.md
```

## 核心功能演示

### 1. 基础 Agent（已实现）
- 使用七牛云 DeepSeek-V3.2 模型
- 自定义 System Prompt（专业 .NET AI Agent 助手）

### 2. 练习任务（逐步扩展）

1. **添加 Tools**  
   注册 C# 函数工具（如计算器、天气查询、代码执行等），让 Agent 自主调用。

2. **Multi-turn 对话**  
   使用 `AgentSession` 维护会话状态，实现有记忆的多轮对话。

3. **Memory & Persistence**  
   集成 Redis / 文件存储，实现长期记忆。

4. **Agent Skills**  
   创建可复用的 `SKILL.md` 技能包（领域知识、参考资料、脚本），练习 Progressive Disclosure。

5. **Workflow**  
   引入图式 Workflow，实现顺序执行、并发、Handoff、Group Chat 等模式。

6. **Human-in-the-Loop**  
   添加人工介入机制。

## Docker 开发环境（推荐）

项目已支持 Docker + 双向 volume 绑定，适合 WSL2 / macOS / Windows。

```bash
docker compose up --build
```

## 学习路径推荐

1. 官方文档（强烈推荐按顺序学习）：
   - [Get Started with Agent Framework](https://learn.microsoft.com/en-us/agent-framework/get-started/)
   - Step 1: Your First Agent → Step 2: Add Tools → Step 3: Multi-Turn ...

2. GitHub Samples：
   - https://github.com/microsoft/agent-framework （.NET samples 目录）

3. 本项目练习顺序建议：
   - 先跑通基础 Agent
   - 添加一个简单 Tool（例如计算器）
   - 实现带记忆的多轮对话
   - 尝试创建第一个 Agent Skill

## 常见命令

```bash
dotnet restore
dotnet build
dotnet run
dotnet watch run
docker compose up --build
docker compose down
```

## 注意事项

- API Key 请勿硬编码到代码中
- 开发时优先使用 `gpt-4o-mini` 或 DeepSeek-V3.2 等性价比高的模型
- 生产环境建议增加日志、遥测（OpenTelemetry）和错误处理
- 项目代码放在 Linux 文件系统（WSL2 的 `~/Projects`）可获得最佳热重载性能

## 参考资源

- 官方文档：https://learn.microsoft.com/en-us/agent-framework/
- GitHub 主仓库：https://github.com/microsoft/agent-framework
- 1.0 发布博客：https://devblogs.microsoft.com/agent-framework/microsoft-agent-framework-version-1-0/

---

**练习建议**：每完成一个功能点，就在代码中添加详细注释，并尝试修改 Prompt / Tools 来观察 Agent 行为变化。

祝你学习愉快！如果遇到问题，欢迎在 Issues 中讨论。

**作者**：你的 .NET AI Agent 架构师  
**版本**：2026 年 4 月（基于 Agent Framework 1.0）
```

---

这个 README.md 内容**结构清晰、实用、循序渐进**，适合作为命令行练习项目的入口文档。你可以根据实际代码再微调“练习任务”部分。

需要我帮你：
- 补充具体某个练习任务的代码示例（例如“添加计算器 Tool”）
- 增加 Docker 部分更详细说明
- 或者生成带 Tools 的完整 `Program.cs` 示例？

直接告诉我你的需求即可！