欢迎来到 Microsoft Agent Framework！

欢迎来到微软的全面多语言框架，用于构建、编排和部署 AI 代理，同时支持 .NET 和 Python 实现。该框架提供从简单聊天代理到复杂多代理工作流的一切功能，并采用基于图的编排方式。

观看完整的 Agent Framework 介绍（30 分钟）

📋 入门指南

📦 安装

Python

pip install agent-framework --pre
# 这将安装所有子包，单个包请参阅 `python/packages`。
# 在 Windows 上首次安装时可能需要一分钟。

.NET

dotnet add package Microsoft.Agents.AI

📚 文档

• 概述 - 框架的高层次概述
• 快速入门 - 使用简单代理开始
• 教程 - 分步教程
• 用户指南 - 构建代理和工作流的深入用户指南
• 从 Semantic Kernel 迁移指南 - 从 Semantic Kernel 迁移的指南
• 从 AutoGen 运行时迁移指南 - 从 AutoGen 运行时迁移的指南

仍有疑问？加入我们的 每周办公时间 或在我们的 Discord 频道 中提问，以获得团队和其他用户的帮助。

✨ 亮点

• 基于图的工作流：使用数据流连接代理和确定性函数，具备流式处理、检查点、人机协作和时间旅行等功能
  • Python 工作流 | .NET 工作流
• AF Labs：用于前沿功能的实验性包，包括基准测试、强化学习和研究项目
  • Labs 目录
• DevUI：用于代理开发、测试和调试工作流的交互式开发者界面
  • DevUI 包

查看 DevUI 的实际效果（1 分钟）

• Python 和 C#/ .NET 支持：完整框架同时支持 Python 和 C#/ .NET 实现，且 API 一致
  • Python 包 | .NET 源代码
• 可观测性：内置 OpenTelemetry 集成，用于分布式追踪、监控和调试
  • Python 可观测性 | .NET 链路追踪
• 多代理提供商支持：支持多种 LLM 提供商，并将持续增加更多提供商
  • Python 示例 | .NET 示例
• 中间件：灵活的中间件系统，用于请求/响应处理、异常处理和自定义管道
  • Python 中间件 | .NET 中间件

💬 我们期待您的反馈！

• 如发现任何问题，请提交 GitHub 问题。

快速入门

基础代理 - Python

创建一个简单的 Azure Responses 代理，撰写一首关于 Microsoft Agent Framework 的俳句。

# pip install agent-framework --pre
# 使用 `az login` 通过 Azure CLI 进行身份验证
import os
import asyncio
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential


async def main():
    # 初始化一个使用 Microsoft Foundry 的聊天代理
    # 终端节点、部署名称和 API 版本可以通过环境变量设置
    # 或直接传递给 FoundryChatClient 构造函数
    agent = Agent(
      client=FoundryChatClient(
          credential=AzureCliCredential(),
          # project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
          # model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
      ),
      name="HaikuBot",
      instructions="你是一位乐观开朗、文笔优美的助手。",
    )

    print(await agent.run("写一首关于 Microsoft Agent Framework 的俳句。"))

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

基础代理 - .NET

使用 OpenAI 响应创建一个简单的代理，该代理会撰写一首关于 Microsoft 代理框架的俳句。

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

// 将 <apikey> 替换为您的 OpenAI API 密钥。
var agent = new OpenAIClient("<apikey>")
    .GetResponsesClient("gpt-4o-mini")
    .AsAIAgent(name: "HaikuBot", instructions: "您是一位积极向上、文笔优美的助手。");

Console.WriteLine(await agent.RunAsync("请写一首关于 Microsoft 代理框架的俳句。"));

使用基于令牌的身份验证的 Microsoft Foundry 创建一个简单的代理，该代理会撰写一首关于 Microsoft 代理框架的俳句。

// dotnet add package Microsoft.Agents.AI.AzureAI --prerelease
// dotnet add package Azure.Identity
// 使用 `az login` 通过 Azure CLI 进行身份验证
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT 未设置。");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

var agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(model: deploymentName, name: "HaikuBot", instructions: "您是一位积极向上、文笔优美的助手。");

Console.WriteLine(await agent.RunAsync("请写一首关于 Microsoft 代理框架的俳句。"));

更多示例与样本

Python

• 入门：从“Hello World”到托管的逐步教程
• 代理概念：按主题深入探讨的示例（工具、中间件、提供商等）
• 工作流：工作流的创建及与代理的集成
• 托管：A2A、Azure Functions、Durable Task 托管
• 端到端：完整应用、评估和演示

.NET

• 入门：从简单代理到托管的逐步教程
• 代理概念：基础代理的创建及工具的使用
• 代理提供商：展示不同代理提供商的示例
• 工作流：高级多代理模式及工作流编排
• 托管：A2A、Durable Agents、Durable Workflows
• 端到端：完整应用及演示

故障排除

身份验证

问题	原因	解决方法
使用 Azure 凭证时出现身份验证错误	未登录 Azure CLI	在启动应用程序前运行 az login
API 密钥错误	API 密钥错误或缺失	验证密钥，并确保其适用于正确的资源/提供商

提示：DefaultAzureCredential 在开发阶段很方便，但在生产环境中，建议使用特定的凭证（例如 ManagedIdentityCredential），以避免延迟问题、意外的凭证探测以及回退机制可能带来的安全风险。

环境变量

示例通常从环境变量中读取配置。常见的必需变量如下：

变量	使用于	目的
AZURE_OPENAI_ENDPOINT	Azure OpenAI 示例	您的 Azure OpenAI 资源 URL
AZURE_OPENAI_DEPLOYMENT_NAME	Azure OpenAI 示例	模型部署名称（例如 gpt-4o-mini）
AZURE_AI_PROJECT_ENDPOINT	Microsoft Foundry 示例	您的 Microsoft Foundry 项目端点
AZURE_AI_MODEL_DEPLOYMENT_NAME	Microsoft Foundry 示例	模型部署名称
OPENAI_API_KEY	OpenAI（非 Azure）示例	您的 OpenAI 平台 API 密钥

贡献者资源

• 贡献指南
• Python 开发指南
• 设计文档
• 架构决策记录

重要说明

如果您使用 Microsoft 代理框架构建与第三方服务器或代理交互的应用程序，则需自行承担相关风险。我们建议您仔细审查与第三方服务器或代理共享的所有数据，并了解其在数据保留和存储位置方面的做法。确保您的数据不会流出贵组织的 Azure 合规范围和地理边界，以及由此可能产生的任何影响，这完全由您负责。

Microsoft Agent Framework 快速上手指南

Microsoft Agent Framework 是一个用于构建、编排和部署 AI 代理的多语言框架，支持 .NET 和 Python。它涵盖了从简单的聊天代理到基于图编排的复杂多代理工作流。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Windows, macOS 或 Linux
• Python 用户:
  • Python 3.10 或更高版本
  • pip 包管理工具
  • (可选) 若使用 Azure 服务，需安装 Azure CLI 并登录 (az login)
• .NET 用户:
  • .NET 8.0 SDK 或更高版本
• 账号与密钥:
  • 若使用 OpenAI：需要有效的 OPENAI_API_KEY
  • 若使用 Azure OpenAI 或 Microsoft Foundry：需要相应的 Azure 订阅、资源端点及部署名称

提示：国内开发者若遇到 PyPI 下载缓慢问题，可使用清华或阿里镜像源加速安装。

安装步骤

根据您的开发语言选择对应的安装命令。

Python 安装

使用 pip 安装预发布版本（当前为 pre-release）：

pip install agent-framework --pre -i https://pypi.tuna.tsinghua.edu.cn/simple

注：首次安装可能需要一分钟时间，该命令会安装所有子包。

.NET 安装

在您的项目目录中运行以下命令添加 NuGet 包：

dotnet add package Microsoft.Agents.AI

若需使用特定提供商（如 OpenAI 或 Azure AI），还需安装对应包：

# 用于 OpenAI
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

# 用于 Azure AI / Microsoft Foundry
dotnet add package Microsoft.Agents.AI.AzureAI --prerelease
dotnet add package Azure.Identity

基本使用

以下是创建简单 AI 代理的最小化示例，代理将输出一首关于 Microsoft Agent Framework 的俳句。

Python 示例 (使用 Microsoft Foundry/Azure)

此示例使用 Azure CLI 凭据进行身份验证。

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


async def main():
    # Initialize a chat agent with Microsoft Foundry
    # the endpoint, deployment name, and api version can be set via environment variables
    # or they can be passed in directly to the FoundryChatClient constructor
    agent = Agent(
      client=FoundryChatClient(
          credential=AzureCliCredential(),
          # project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
          # model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
      ),
      name="HaikuBot",
      instructions="You are an upbeat assistant that writes beautifully.",
    )

    print(await agent.run("Write a haiku about Microsoft Agent Framework."))

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

.NET 示例

方案 A：使用 OpenAI

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

// Replace the <apikey> with your OpenAI API key.
var agent = new OpenAIClient("<apikey>")
    .GetResponsesClient("gpt-4o-mini")
    .AsAIAgent(name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");

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

方案 B：使用 Microsoft Foundry (Token 认证)

// dotnet add package Microsoft.Agents.AI.AzureAI --prerelease
// dotnet add package Azure.Identity
// Use `az login` to authenticate with Azure CLI
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

var endpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT") ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

var agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(model: deploymentName, name: "HaikuBot", instructions: "You are an upbeat assistant that writes beautifully.");

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

运行上述代码前，请确保已设置必要的环境变量（如 AZURE_AI_PROJECT_ENDPOINT）或替换代码中的 API Key。