microsoft--agent-framework/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

欢迎使用 Microsoft Agent Framework！

Microsoft Agent Framework (MAF) 是一个开放、多语言的框架，用于在 .NET 和 Python 中构建生产级 AI 智能体（agent）与多智能体工作流。

Microsoft Agent Framework 面向将智能体从原型推向生产的团队。它在 Python 与 .NET 之间提供一致的基础，用于构建、编排和运行智能体系统，同时在需求演进时保持架构选择的开放性；支持包括 Microsoft Foundry、Azure OpenAI、OpenAI 和 GitHub Copilot SDK 在内的广泛生态系统，并提供适用于本地开发与云部署的示例与托管模式。

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

这个框架适合你吗？

如果你符合以下情况，MAF 会是很好的选择：

• 正在构建预期在生产环境运行的智能体与工作流，
• 需要超越单次提示或无状态聊天循环的编排能力，
• 希望采用基于图（graph）的模式，例如顺序、并发、交接（handoff）和群组协作，
• 关注持久性、可重启性、可观测性、治理或人在回路（human-in-the-loop）控制，
• 需要提供商灵活性，以便架构演进时无需大规模重写。

核心特性

在官方博客.探索 MAF 的新能力与真实实现模式。

• Python 与 C#/.NET 支持：为 Python 与 C#/.NET 实现提供完整框架支持，API 保持一致
  • Python 包 | .NET 源码
• 多智能体提供商支持：支持多种 LLM 提供商，并持续增加更多选项
  • Python 示例 | .NET 示例
• 中间件（Middleware）：灵活的中间件系统，用于请求/响应处理、异常处理和自定义管道
  • Python 中间件 | .NET 中间件
• 编排模式与工作流：使用基于图的工作流构建多智能体系统，支持顺序、并发、交接和群组协作模式；包含检查点（checkpointing）、流式传输、人在回路和时间旅行（time-travel）
  • Python 工作流 | .NET 工作流
• Foundry 托管智能体（新）：只需额外两行代码，即可将智能体部署并托管到 Foundry 托管基础设施
  • Python 示例 | .NET 示例
• 可观测性（Observability）：内置 OpenTelemetry 集成，用于分布式追踪、监控和调试
  • Python 可观测性 | .NET 遥测
• 声明式智能体（Declarative Agents）：使用 YAML 定义智能体，加快设置与版本管理
  • 声明式智能体示例
• 智能体技能（Agent Skills）：从多种来源——文件、内联代码、类库——构建领域专属知识库，供智能体发现与使用
  • 技能设计
• AF Labs：面向前沿功能的实验性包，包括基准测试、强化学习与研究计划
  • Labs 目录
• DevUI：用于智能体开发、测试和调试工作流的交互式开发者 UI
  • 查看 DevUI 实际效果

目录

• 入门
  • 安装
  • 学习资源
  • 快速入门
    • 基础智能体 - Python
    • 基础智能体 - .NET
• 更多示例与样例
• 社区与反馈
• 故障排除
• 贡献者资源

入门

安装

Python

pip install agent-framework
# This will install all sub-packages, see `python/packages` for individual packages.
# It may take a minute on first install on Windows.

.NET

dotnet add package Microsoft.Agents.AI
# For Foundry integration (used in the .NET quickstart below):
dotnet add package Microsoft.Agents.AI.Foundry
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

学习资源

• 概述 - 框架的高层概览
• 快速入门 - 从一个简单智能体开始
• 教程 - 分步教程
• 用户指南 - 构建智能体与工作流的深入用户指南
• 从 Semantic Kernel 迁移 - 从 Semantic Kernel 迁移指南
• 从 AutoGen 迁移 - 从 AutoGen 迁移指南

快速入门

基础智能体 - Python

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

# pip install agent-framework
# 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="HaikuAgent",
      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

创建一个简单的 Agent，使用 Microsoft Foundry 撰写一首关于 Microsoft Agent Framework 的俳句

// This sample shows how to create and run a basic agent with AIProjectClient.AsAIAgent(...).

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

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

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

// Once you have the agent, you can invoke it like any other AIAgent.
Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));

更多示例与样例

Python

• Getting Started（入门）：从 hello-world 到托管的渐进式教程
• Agent Concepts（智能体概念）：按主题深入讲解的样例（工具、中间件、提供方等）
• Workflows（工作流）：工作流创建及与智能体的集成
• Hosting（托管）：A2A、Azure Functions、Durable Task 托管
• End-to-End（端到端）：完整应用、评估与演示

.NET

• Getting Started（入门）：从 hello agent 到托管的渐进式教程
• Agent Concepts（智能体概念）：基础智能体创建与工具使用
• Agent Providers（智能体提供方）：展示不同智能体提供方的样例
• Workflows（工作流）：高级多智能体模式与工作流编排
• Hosting（托管）：A2A、Durable Agents、Durable Workflows
• End-to-End（端到端）：完整应用与演示

社区与反馈

• 发现 bug？ 请提交 GitHub issue 以帮助我们改进。
• 喜欢 MAF？ 来表达支持，并帮助他人发现该项目。
• 有问题？ 加入我们的 Discord 或访问 weekly office hours（每周公开办公时间）。

故障排除

身份验证

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

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

环境变量

各样例专有的环境变量配置，请参阅样例目录中的 README（Python samples（Python 样例） | .NET samples（.NET 样例））。

贡献者资源

• Contributing Guide（贡献指南）
• Python Development Guide（Python 开发指南）
• Design Documents（设计文档）
• Architectural Decision Records（架构决策记录）

重要说明

Important

若你使用 Microsoft Agent Framework 构建与任何第三方服务器、智能体、代码或非 Azure Direct 模型（“第三方系统”，Third-Party Systems）交互的应用，风险由你自行承担。第三方系统属于 Microsoft 产品条款下的非 Microsoft 产品（Non-Microsoft Products），并受其各自的第三方许可条款约束。你须对任何使用行为及相关费用负责。

我们建议审阅与第三方系统共享及接收的全部数据，并留意第三方在处理、共享、保留及存储数据位置方面的做法。你有责任管理数据是否会流出组织的 Azure 合规与地理边界及相关影响，并确保已配置适当的权限、边界与审批。

你有责任结合具体用例，仔细审阅并测试使用 Microsoft Agent Framework 构建的应用，并做出一切适当决策与定制。这包括实施你自己的负责任 AI 缓解措施，例如 metaprompt、内容过滤器或其他安全系统，并确保应用达到适当的质量、可靠性、安全性与可信度标准。另请参阅：Transparency FAQ（透明度常见问题）