/README.md

<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。  
> [English](./README.en.md) · [原始项目](https://github.com/microsoft/agent-framework) · [上游 README](https://github.com/microsoft/agent-framework/blob/HEAD/README.md)  
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

![Microsoft Agent Framework](docs/assets/readme-banner.png)

# 欢迎使用 Microsoft Agent Framework！

[![Microsoft Foundry Discord](https://dcbadge.limes.pink/api/server/b5zjErwbQM?style=flat)](https://discord.gg/b5zjErwbQM)
[![MS Learn Documentation](https://img.shields.io/badge/MS%20Learn-Documentation-blue)](https://learn.microsoft.com/en-us/agent-framework/)
[![PyPI](https://img.shields.io/pypi/v/agent-framework)](https://pypi.org/project/agent-framework/)
[![NuGet](https://img.shields.io/nuget/v/Microsoft.Agents.AI)](https://www.nuget.org/profiles/MicrosoftAgentFramework/)
[![GitHub stars](https://img.shields.io/github/stars/microsoft/agent-framework?style=social)](https://github.com/microsoft/agent-framework)


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

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

<p align="center">
  <a href="https://www.youtube.com/watch?v=AAgdMhftj8w" title="观看完整的 Agent Framework 介绍（30 分钟）">
    <img src="https://img.youtube.com/vi/AAgdMhftj8w/hqdefault.jpg"
         alt="观看完整的 Agent Framework 介绍（30 分钟）" width="480">
  </a>
</p>
<p align="center">
  <a href="https://www.youtube.com/watch?v=AAgdMhftj8w">
    观看完整的 Agent Framework 介绍（30 分钟）
  </a>
</p>

## 这个框架适合你吗？

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

## 核心特性
在[官方博客](https://devblogs.microsoft.com/agent-framework/).探索 MAF 的新能力与真实实现模式。

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

## 目录

- [入门](#getting-started)
  - [安装](#installation)
  - [学习资源](#learning-resources)
  - [快速入门](#quickstart)
    - [基础智能体 - Python](#basic-agent---python)
    - [基础智能体 - .NET](#basic-agent---net)
- [更多示例与样例](#more-examples--samples)
- [社区与反馈](#community--feedback)
- [故障排除](#troubleshooting)
- [贡献者资源](#contributor-resources)

## 入门
### 安装
Python

```bash
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

```bash
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
```

### 学习资源

- **[概述](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview)** - 框架的高层概览
- **[快速入门](https://learn.microsoft.com/agent-framework/tutorials/quick-start)** - 从一个简单智能体开始
- **[教程](https://learn.microsoft.com/agent-framework/tutorials/overview)** - 分步教程
- **[用户指南](https://learn.microsoft.com/en-us/agent-framework/user-guide/overview)** - 构建智能体与工作流的深入用户指南
- **[从 Semantic Kernel 迁移](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-semantic-kernel)** - 从 Semantic Kernel 迁移指南
- **[从 AutoGen 迁移](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-autogen)** - 从 AutoGen 迁移指南

### 快速入门

#### 基础智能体 - Python

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

```python
# 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 的俳句

```c#
// 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（入门）](./python/samples/01-get-started)：从 hello-world 到托管的渐进式教程
- [Agent Concepts（智能体概念）](./python/samples/02-agents)：按主题深入讲解的样例（工具、中间件、提供方等）
- [Workflows（工作流）](./python/samples/03-workflows)：工作流创建及与智能体的集成
- [Hosting（托管）](./python/samples/04-hosting)：A2A、Azure Functions、Durable Task 托管
- [End-to-End（端到端）](./python/samples/05-end-to-end)：完整应用、评估与演示

### .NET

- [Getting Started（入门）](./dotnet/samples/01-get-started)：从 hello agent 到托管的渐进式教程
- [Agent Concepts（智能体概念）](./dotnet/samples/02-agents/Agents)：基础智能体创建与工具使用
- [Agent Providers（智能体提供方）](./dotnet/samples/02-agents/AgentProviders)：展示不同智能体提供方的样例
- [Workflows（工作流）](./dotnet/samples/03-workflows)：高级多智能体模式与工作流编排
- [Hosting（托管）](./dotnet/samples/04-hosting)：A2A、Durable Agents、Durable Workflows
- [End-to-End（端到端）](./dotnet/samples/05-end-to-end)：完整应用与演示

## 社区与反馈

- **发现 bug？** 请提交 [GitHub issue](https://github.com/microsoft/agent-framework/issues) 以帮助我们改进。
- **喜欢 MAF？** [![GitHub stars](https://img.shields.io/badge/Star-us%20on%20GitHub-yellow)](https://github.com/microsoft/agent-framework) 来表达支持，并帮助他人发现该项目。
- **有问题？** 加入我们的 [Discord](https://discord.gg/b5zjErwbQM) 或访问 [weekly office hours（每周公开办公时间）](./COMMUNITY.md#public-community-office-hours)。

## 故障排除

### 身份验证

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

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

### 环境变量

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

## 贡献者资源

- [Contributing Guide（贡献指南）](./CONTRIBUTING.md)
- [Python Development Guide（Python 开发指南）](./python/DEV_SETUP.md)
- [Design Documents（设计文档）](./docs/design)
- [Architectural Decision Records（架构决策记录）](./docs/decisions)

## 重要说明

> [!IMPORTANT]
> 若你使用 Microsoft Agent Framework 构建与任何第三方服务器、智能体、代码或非 Azure Direct 模型（“第三方系统”，Third-Party Systems）交互的应用，风险由你自行承担。第三方系统属于 Microsoft 产品条款下的非 Microsoft 产品（Non-Microsoft Products），并受其各自的第三方许可条款约束。你须对任何使用行为及相关费用负责。
>
>我们建议审阅与第三方系统共享及接收的全部数据，并留意第三方在处理、共享、保留及存储数据位置方面的做法。你有责任管理数据是否会流出组织的 Azure 合规与地理边界及相关影响，并确保已配置适当的权限、边界与审批。
> 
>你有责任结合具体用例，仔细审阅并测试使用 Microsoft Agent Framework 构建的应用，并做出一切适当决策与定制。这包括实施你自己的负责任 AI 缓解措施，例如 metaprompt、内容过滤器或其他安全系统，并确保应用达到适当的质量、可靠性、安全性与可信度标准。另请参阅：[Transparency FAQ（透明度常见问题）](./TRANSPARENCY_FAQ.md)