Microsoft Agent Framework部署指南：从开发到生产环境

2026-02-05 05:03:13作者：邓越浪Henry

Microsoft Agent Framework是一个用于构建、编排和部署AI代理及多代理工作流的框架，支持Python和.NET两种编程语言。本指南将详细介绍如何从开发环境搭建到生产环境部署的完整流程，帮助普通用户及运营人员快速上手。

开发环境准备

环境要求

在开始之前，请确保你的系统满足以下要求：

Python 3.10及以上版本（用于Python开发）
.NET SDK 6.0及以上版本（用于.NET开发）
Git工具（用于代码仓库克隆）
适当的代码编辑器，如VSCode

代码仓库克隆

首先，克隆项目仓库到本地：

git clone https://gitcode.com/GitHub_Trending/age/agent-framework
cd agent-framework

Python开发环境设置

对于Python开发者，推荐使用uv工具进行依赖管理。以下是详细的环境搭建步骤：

安装uv工具：

# Windows系统
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Linux或MacOS系统
curl -LsSf https://astral.sh/uv/install.sh | sh

# MacOS系统（使用Homebrew）
brew install uv

创建虚拟环境并安装依赖：

# 安装指定版本的Python
uv python install 3.10 3.11 3.12 3.13

# 创建虚拟环境（以Python 3.13为例）
uv venv --python 3.13

# 安装项目依赖
uv sync --dev
uv run poe install

# 安装pre-commit钩子
uv run poe pre-commit-install

或者，你可以使用更简便的命令一键设置环境：

uv run poe setup -p 3.13

VSCode配置：
- 安装Python扩展
- 打开python文件夹作为工作区
- 选择刚刚创建的虚拟环境作为解释器
详细的Python开发环境设置可以参考Python Development Guide。

.NET开发环境设置

对于.NET开发者，环境搭建步骤如下：

安装.NET SDK：请从微软官方网站下载并安装.NET SDK 6.0及以上版本。
安装项目依赖：
```
cd dotnet
dotnet restore
```

框架核心组件介绍

项目结构概览

Microsoft Agent Framework的项目结构清晰，主要包含以下几个部分：

文档目录：docs/，包含项目文档、设计决策记录等
Python代码目录：python/，包含Python版本的源代码、示例和测试
.NET代码目录：dotnet/，包含.NET版本的源代码、示例和测试
工作流示例：workflow-samples/，包含各种工作流示例

核心功能模块

代理创建与管理：框架提供了灵活的代理创建接口，支持多种LLM提供商。
工作流编排：支持基于图的工作流，可连接代理和确定性函数。
DevUI工具：交互式开发者UI，用于代理开发、测试和调试工作流。
可观测性：内置OpenTelemetry集成，支持分布式追踪、监控和调试。

开发实战：创建第一个代理

Python代理示例

以下是一个简单的Python代理示例，使用Azure OpenAI服务创建一个生成俳句的代理：

# pip install agent-framework --pre
# Use `az login` to authenticate with Azure CLI
import os
import asyncio
from agent_framework.azure import AzureOpenAIResponsesClient
from azure.identity import AzureCliCredential


async def main():
    # 初始化Azure OpenAI响应客户端
    agent = AzureOpenAIResponsesClient(
        credential=AzureCliCredential(),  # 使用Azure CLI凭据进行身份验证
    ).create_agent(
        name="HaikuBot",
        instructions="You are an upbeat assistant that writes beautifully.",
    )

    # 运行代理，生成关于Microsoft Agent Framework的俳句
    print(await agent.run("Write a haiku about Microsoft Agent Framework."))

if __name__ == "__main__":
    asyncio.run(main())

更多Python示例可以参考python/samples/getting_started/agents目录。

.NET代理示例

以下是一个简单的.NET代理示例，使用OpenAI服务创建一个生成俳句的代理：

// dotnet add package Microsoft.Agents.AI.OpenAI --prerelease
using System;
using OpenAI;

// 替换<apikey>为你的OpenAI API密钥
var agent = new OpenAIClient("<apikey>")
    .GetOpenAIResponseClient("gpt-4o-mini")
    .CreateAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");

Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));

更多.NET示例可以参考dotnet/samples/GettingStarted/Agents目录。

工作流开发与测试

工作流示例

Microsoft Agent Framework提供了丰富的工作流示例，位于workflow-samples/目录下。以下是一个简单的工作流示例：

# 工作流示例：HumanInLoop.yaml
name: HumanInLoop
description: A workflow that includes human-in-the-loop approval
steps:
- name: GenerateContent
  agent: ContentGenerator
  input: "{{ $input.prompt }}"
  output: generated_content
  
- name: HumanApproval
  type: human_approval
  input: "{{ $steps.GenerateContent.output }}"
  timeout: 86400  # 24 hours
  
- name: Finalize
  agent: ContentFinalizer
  input: "{{ $steps.HumanApproval.approved_content }}"
  output: final_content

DevUI工具使用

DevUI是一个交互式开发者UI，可帮助你开发、测试和调试工作流。你可以通过以下命令启动DevUI：

cd python
uv run poe devui

启动后，访问http://localhost:8000即可打开DevUI界面。更多关于DevUI的信息可以参考python/packages/devui目录。

生产环境部署

部署准备

在部署到生产环境之前，请确保完成以下准备工作：

代码质量检查：

# Python代码检查
cd python
uv run poe check

# .NET代码检查
cd dotnet
dotnet build
dotnet test

环境变量配置：创建.env文件，配置必要的环境变量，如API密钥、端点等：

# 示例.env文件
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=your-api-key
AZURE_OPENAI_API_VERSION=2023-05-15

部署选项

Docker容器化部署

创建Dockerfile：

# Python示例Dockerfile
FROM python:3.13-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "your_agent_app.py"]

构建并运行Docker镜像：

docker build -t agent-framework-app .
docker run -d -p 8000:8000 --env-file .env agent-framework-app

云服务部署

Microsoft Agent Framework可以部署到各种云服务平台，如Azure、AWS、Google Cloud等。以下是部署到Azure App Service的简要步骤：

创建Azure App Service：

az webapp create --name my-agent-app --resource-group my-resource-group --plan my-app-service-plan --runtime "PYTHON|3.13"

部署代码：

az webapp deployment source config --name my-agent-app --resource-group my-resource-group --repo-url https://gitcode.com/GitHub_Trending/age/agent-framework --branch main --manual-integration

配置环境变量：

az webapp config appsettings set --name my-agent-app --resource-group my-resource-group --settings AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/ AZURE_OPENAI_API_KEY=your-api-key

监控与维护

可观测性设置

Microsoft Agent Framework内置了OpenTelemetry集成，可帮助你实现分布式追踪、监控和日志记录。以下是启用可观测性的示例代码：

# Python可观测性示例
from agent_framework import configure_telemetry
from agent_framework.observability import TelemetrySettings

# 配置遥测
configure_telemetry(
    TelemetrySettings(
        service_name="my-agent-service",
        service_version="1.0.0",
        exporter_type="otlp",
        otlp_endpoint="http://otel-collector:4317"
    )
)

更多关于可观测性的信息可以参考python/samples/getting_started/observability目录。

性能优化建议

合理设置缓存策略，减少重复计算
使用异步编程模式，提高并发处理能力
根据实际需求选择合适的LLM模型，平衡性能和成本
定期更新框架版本，获取性能优化和新功能

常见问题解决

开发环境问题

依赖安装失败：尝试使用uv工具代替pip安装依赖
```
uv add agent-framework
```
Python版本不兼容：确保使用Python 3.10及以上版本，可以使用uv管理多个Python版本
```
uv python install 3.13
uv venv --python 3.13
```