Microsoft Agent Framework 实战：打造智能 Git 周报生成工具
从手动写周报到 AI 自动生成，用 Python + Microsoft Agent Framework RC6 构建你的第一个 Agent 应用
一、前言：程序员周报的痛点
每周五下班前，你是不是都在对着 Git 提交记录发愁？
git log --since="1 week ago" --oneline看着一堆 fix bug、add feature、update config 这样的提交记录，手动整理成一份"专业"的周报。这个过程既枯燥又容易遗漏重要内容。
如果能有一个智能助手，自动把原始提交记录转化成结构清晰、语言专业的周报，岂不是美滋滋？
今天我们就用 Microsoft Agent Framework RC6 来构建这样一个 Git 周报生成工具，体验 Agent 开发的完整流程。
二、Microsoft Agent Framework 简介
Microsoft Agent Framework 是微软推出的轻量级 AI Agent 开发框架，核心特点：
| 特点 | 说明 |
|---|---|
| 轻量级 | 仅需少量代码即可构建 Agent |
| 工具集成 | 支持将 Python 函数自动注册为 Agent 工具 |
| 流式输出 | 支持 streaming 模式，实时展示生成过程 |
| 兼容性好 | 支持 OpenAI API 及各类兼容模型（本地模型、Azure 等） |
相比 LangChain、AutoGen 等框架，Microsoft Agent Framework 更专注于"工具调用 + 任务执行"的简洁范式，非常适合快速构建实用性 Agent。
安装依赖
bash
pip install agent-framework python-dotenv三、核心设计思路
3.1 整体架构
用户输入（仓库路径、天数范围）
↓
Agent 调用工具获取 Git 数据
↓
├── get_git_commit_logs() → 提交记录
├── get_git_stats() → 统计数据
↓
LLM 将原始数据转化为专业周报
↓
输出 Markdown 格式周报并保存3.2 工具函数设计
Agent 需要两个核心工具：
工具一：获取提交记录
python
def get_git_commit_logs(
repo_path: Annotated[str, Field(description="Git 仓库路径")] = ".",
days: Annotated[int, Field(description="获取过去 N 天的提交记录")] = 7,
) -> str:
"""获取指定路径下过去 N 天的 Git 提交记录"""
since_date = (datetime.now() - timedelta(days=days)).strftime("%Y-%m-%d")
cmd = [
"git", "-C", repo_path, "log",
f"--since={since_date}",
"--oneline",
"--pretty=format:%s (%ad)",
"--date=short",
]
result = subprocess.run(cmd, capture_output=True, text=True, encoding="utf-8")
return f"过去 {days} 天的提交记录：\n{result.stdout}"工具二：获取统计数据
python
def get_git_stats(repo_path: str = ".", days: int = 7) -> str:
"""获取提交次数、新增/删除行数、变更文件数等统计"""
# 统计提交数量
# 统计代码行变化
# 统计变更文件数
return f"提交次数: {count}\n新增行数: {added}\n删除行数: {deleted}"3.3 使用 Pydantic 进行工具定义
Microsoft Agent Framework 使用 Pydantic 的 Annotated + Field 进行参数定义，这样可以：
- 自动生成工具的 JSON Schema
- 提供参数说明（description）
- 支持类型验证和默认值
python
from typing import Annotated
from pydantic import Field
def get_git_commit_logs(
repo_path: Annotated[str, Field(description="Git 仓库路径，默认当前目录")] = ".",
days: Annotated[int, Field(description="获取过去 N 天的提交记录")] = 7,
) -> str:LLM 会根据这些描述自动决定何时调用工具、如何传参。
四、完整实现代码
4.1 创建 Agent 系统
python
class GitWeeklyReportSystem:
"""基于 Microsoft Agent Framework RC6 的 Git 周报生成系统"""
def __init__(self):
self._setup_chat_client()
def _setup_chat_client(self):
"""设置 OpenAI 兼容的 Chat Client"""
from agent_framework.openai import OpenAIChatCompletionClient
model = os.getenv("OPENAI_CHAT_MODEL") or os.getenv("OPENAI_MODEL", "gpt-4o-mini")
base_url = os.getenv("OPENAI_BASE_URL")
api_key = os.getenv("OPENAI_API_KEY", "sk-placeholder")
if base_url:
# 支持本地模型（如 Ollama、vLLM 等）
self.chat_client = OpenAIChatCompletionClient(
model=model, base_url=base_url, api_key=api_key
)
else:
# 使用 OpenAI 官方 API
self.chat_client = OpenAIChatCompletionClient(model=model, api_key=api_key)关键点说明：
- 使用
OpenAIChatCompletionClient（Chat Completions API）而非OpenAIChatClient（Responses API） - 这样可以兼容本地模型（Ollama、vLLM、LocalAI 等）
- 通过环境变量灵活配置模型端点
4.2 创建 Agent 实例
python
async def generate_report(self, repo_path: str = ".", days: int = 7) -> str:
from agent_framework import Agent
# 创建周报专家 Agent，配备工具
report_agent = Agent(
name="Report_Specialist",
client=self.chat_client,
instructions="""你是一个擅长写周报的职场专家。
你的任务是将原始的代码提交记录转化为一份结构清晰、语言专业的周报。
要求：
1. 将提交记录分类为：【新功能开发】、【问题修复与优化】、【常规维护】三大类
2. 将口语化的提交记录转化为专业描述
3. 突出工作价值和成果，使用主动语态
4. 使用 Markdown 格式输出""",
tools=[get_git_commit_logs, get_git_stats],
)
# 构建任务提示
task_prompt = f"""请帮我生成一份专业的周报：
1. 获取仓库 '{repo_path}' 过去 {days} 天的提交记录
2. 获取统计数据
请调用工具获取数据后，合成 Markdown 格式周报。"""
result = await self._run_agent(report_agent, task_prompt)
return resultAgent 创建要点：
name: Agent 名称，用于识别client: LLM 客户端实例instructions: Agent 的角色定义和行为准则tools: 可调用的工具函数列表
4.3 流式输出实现
python
async def _run_agent(self, agent, prompt: str) -> str:
"""运行 Agent 并流式打印输出"""
chunks: list[str] = []
async for update in agent.run(prompt, stream=True):
if hasattr(update, "text") and update.text:
chunks.append(update.text)
print(update.text, end="", flush=True) # 实时输出
return "".join(chunks)流式输出的好处：
- 用户可以看到生成过程，体验更流畅
- 避免长时间等待无响应
- 便于调试和观察 Agent 思考过程
4.4 交互式运行模式
python
async def interactive_mode(self):
"""交互式运行模式"""
print("Git 周报生成系统 (Microsoft Agent Framework RC6)")
while True:
print("\n请选择操作：")
print(" 1. 生成周报（默认：当前目录，过去 7 天）")
print(" 2. 自定义参数生成周报")
print(" 3. 退出")
choice = input("请输入选项: ").strip()
if choice == "1":
report = await self.generate_report()
self._save_report(report)
elif choice == "2":
repo_path = input("仓库路径: ") or "."
days = int(input("天数: ") or "7")
report = await self.generate_report(repo_path, days)
self._save_report(report)五、配置与使用
5.1 环境变量配置
创建 .env 文件：
env
# 方式一：使用 OpenAI 官方 API
OPENAI_API_KEY=sk-your-api-key
OPENAI_MODEL=gpt-4o-mini
# 方式二：使用本地模型（Ollama）
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen2.5:7b
OPENAI_API_KEY=ollama # Ollama 不需要真实 key
# 方式三：使用其他兼容服务（如 DeepSeek、Moonshot 等）
OPENAI_BASE_URL=https://api.deepseek.com/v1
OPENAI_API_KEY=sk-your-deepseek-key
OPENAI_MODEL=deepseek-chat5.2 运行程序
bash
python git_weekly_report_agent.py输出示例：
============================================================
Git 周报生成系统 - 配置检查
============================================================
使用 OpenAI 兼容模型端点
端点: http://localhost:11434/v1
模型: qwen2.5:7b
============================================================
请选择操作：
1. 生成周报（默认：当前目录，过去 7 天）
2. 自定义参数生成周报
3. 退出
请输入选项 (1/2/3): 1
正在生成周报...
============================================================
# 本周工作总结
## 工作摘要
本周主要完成了用户认证模块的开发工作，修复了若干系统稳定性问题，
并进行了代码结构优化和文档更新。整体提升了系统的安全性和可维护性。
## 【新功能开发】
- 完成了用户登录认证模块的开发与测试工作
- 实现了 JWT 令牌生成与验证机制
- 新增了用户权限管理功能
## 【问题修复与优化】
- 修复了系统运行过程中的异常问题，提升了稳定性
- 优化了数据库查询性能，响应时间缩短 30%
- 解决了前端页面渲染闪烁问题
## 【常规维护】
- 更新了项目技术文档，补充了关键接口说明
- 清理了冗余代码，提升了可维护性
- 配置了开发环境依赖项
## 数据统计
- 提交次数: 12
- 新增行数: 856
- 删除行数: 234
- 变更文件数: 15
============================================================
周报已保存至: reports/weekly_report_20260403_143052.md六、技术亮点解析
6.1 工具自动注册
框架会自动将 Python 函数转换为 Agent 可调用的工具：
python
tools=[get_git_commit_logs, get_git_stats]LLM 根据函数签名、参数类型和 Field 描述，自动决定：
- 是否需要调用工具
- 调用哪个工具
- 如何传递参数
6.2 编码问题处理
Windows 环境下 Git 命令可能返回 GBK 编码，代码做了兼容处理：
python
result = subprocess.run(
cmd,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace", # 非法字符替换而非报错
)输出时也处理了 GBK 编码问题：
python
try:
print(update.text, end="", flush=True)
except UnicodeEncodeError:
safe_text = update.text.encode("gbk", errors="replace").decode("gbk")
print(safe_text, end="", flush=True)6.3 模型兼容性
使用 OpenAIChatCompletionClient 而非 OpenAIChatClient：
| 客户端类型 | API 类型 | 兼容性 |
|---|---|---|
OpenAIChatClient |
Responses API | 仅 OpenAI 官方 |
OpenAIChatCompletionClient |
Chat Completions API | 兼容所有 OpenAI 兼容服务 |
这样可以使用：
- OpenAI GPT 系列
- Ollama 本地模型
- vLLM、LocalAI 等推理服务
- DeepSeek、Moonshot、Qwen 等 API 服务
七、扩展思路
7.1 添加更多工具
可以扩展更多 Git 分析工具：
python
def get_branch_info(repo_path: str = ".") -> str:
"""获取分支信息"""
def get_code_review_suggestions(repo_path: str = ".", days: int = 7) -> str:
"""分析代码变更并给出改进建议"""
def get_issue_links(repo_path: str = ".") -> str:
"""从提交信息中提取关联的 Issue/PR 编号"""7.2 多 Agent 协作
可以引入多个 Agent 进行协作：
python
data_collector = Agent(
name="Data_Collector",
tools=[get_git_logs, get_stats, get_branch_info],
instructions="负责收集和整理 Git 数据",
)
report_writer = Agent(
name="Report_Writer",
instructions="负责将数据转化为专业周报",
)
# Data_Collector 收集数据 → Report_Writer 撰写周报7.3 接入企业系统
- 定时任务自动生成周报并发送邮件
- 集成到钉钉/飞书/企业微信
- 与 Jira、GitLab 等平台对接
八、总结
Microsoft Agent Framework RC6 提供了一个简洁高效的 Agent 开发范式：
- 定义工具函数 ：使用
Annotated + Field描述参数 - 创建 Agent：配置 client、instructions 和 tools
- 运行 Agent ：调用
agent.run()执行任务
整个 Git 周报生成工具仅 300+ 行代码，却实现了：
- 自动获取 Git 数据
- 智能转化专业周报
- 流式输出实时展示
- 本地模型兼容
- 交互式用户体验
这正是 Agent 开发的魅力所在------让 AI 真正成为可编程的智能助手。
相关资源
- Microsoft Agent Framework: https://github.com/microsoft/agent-framework
- 完整代码: https://github.com/loveStudyWjj/git_weekly_report_agent
- Ollama 本地模型: https://ollama.ai
如果觉得有帮助，欢迎点赞收藏，有问题欢迎评论区讨论！