docs: make Chinese README the default
dotnet-build-and-test / paths-filter (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Debug, windows-latest, net9.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, ubuntu-latest, net10.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, ubuntu-latest, net8.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, windows-latest, net472) (push) Has been cancelled
dotnet-build-and-test / dotnet-test (Release, integration, true, ubuntu-latest, net10.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-test (Release, integration, true, windows-latest, net472) (push) Has been cancelled
dotnet-build-and-test / dotnet-foundry-hosted-it (push) Has been cancelled
dotnet-build-and-test / dotnet-test-functions (push) Has been cancelled
dotnet-build-and-test / dotnet-build-and-test-check (push) Has been cancelled
dotnet-build-and-test / Integration Test Report (push) Has been cancelled
CodeQL / Analyze (csharp) (push) Has been cancelled
CodeQL / Analyze (python) (push) Has been cancelled
dotnet-build-and-test / paths-filter (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Debug, windows-latest, net9.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, ubuntu-latest, net10.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, ubuntu-latest, net8.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, windows-latest, net472) (push) Has been cancelled
dotnet-build-and-test / dotnet-test (Release, integration, true, ubuntu-latest, net10.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-test (Release, integration, true, windows-latest, net472) (push) Has been cancelled
dotnet-build-and-test / dotnet-foundry-hosted-it (push) Has been cancelled
dotnet-build-and-test / dotnet-test-functions (push) Has been cancelled
dotnet-build-and-test / dotnet-build-and-test-check (push) Has been cancelled
dotnet-build-and-test / Integration Test Report (push) Has been cancelled
CodeQL / Analyze (csharp) (push) Has been cancelled
CodeQL / Analyze (python) (push) Has been cancelled
This commit is contained in:
wehub-resource-sync
@@ -1,6 +1,12 @@
|
||||
<!-- 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 文件为准。
|
||||
|
||||
|
||||
|
||||
# Welcome to Microsoft Agent Framework!
|
||||
# 欢迎使用 Microsoft Agent Framework！
|
||||
|
||||
[](https://discord.gg/b5zjErwbQM)
|
||||
[](https://learn.microsoft.com/en-us/agent-framework/)
|
||||
@@ -9,70 +15,70 @@
|
||||
[](https://github.com/microsoft/agent-framework)
|
||||
|
||||
|
||||
Microsoft Agent Framework (MAF) is an open, multi-language framework for building **production-grade AI agents and multi-agent workflows** in **.NET and Python**.
|
||||
Microsoft Agent Framework (MAF) 是一个开放、多语言的框架，用于在 **.NET 和 Python** 中构建**生产级 AI 智能体（agent）与多智能体工作流**。
|
||||
|
||||
Microsoft Agent Framework is built for teams taking agents from prototype to production. It provides a consistent foundation for building, orchestrating, and operating agent systems across Python and .NET, while keeping architecture choices open as requirements evolve, and supports a broad ecosystem including Microsoft Foundry, Azure OpenAI, OpenAI, and the GitHub Copilot SDK, with samples and hosting patterns for both local development and cloud deployment.
|
||||
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="Watch the full Agent Framework introduction (30 min)">
|
||||
<a href="https://www.youtube.com/watch?v=AAgdMhftj8w" title="观看完整的 Agent Framework 介绍（30 分钟）">
|
||||
<img src="https://img.youtube.com/vi/AAgdMhftj8w/hqdefault.jpg"
|
||||
alt="Watch the full Agent Framework introduction (30 min)" width="480">
|
||||
alt="观看完整的 Agent Framework 介绍（30 分钟）" width="480">
|
||||
</a>
|
||||
</p>
|
||||
<p align="center">
|
||||
<a href="https://www.youtube.com/watch?v=AAgdMhftj8w">
|
||||
Watch the full Agent Framework introduction (30 min)
|
||||
观看完整的 Agent Framework 介绍（30 分钟）
|
||||
</a>
|
||||
</p>
|
||||
|
||||
## Is this the right framework for you?
|
||||
## 这个框架适合你吗？
|
||||
|
||||
MAF is a strong fit if you:
|
||||
- are building agents and workflows you expect to run in production,
|
||||
- need orchestration beyond a single prompt or stateless chat loop,
|
||||
- want graph-based patterns such as sequential, concurrent, handoff, and group collaboration,
|
||||
- care about durability, restartability, observability, governance, or human-in-the-loop control,
|
||||
- need provider flexibility so your architecture can evolve without major rewrites.
|
||||
如果你符合以下情况，MAF 会是很好的选择：
|
||||
- 正在构建预期在生产环境运行的智能体与工作流，
|
||||
- 需要超越单次提示或无状态聊天循环的编排能力，
|
||||
- 希望采用基于图（graph）的模式，例如顺序、并发、交接（handoff）和群组协作，
|
||||
- 关注持久性、可重启性、可观测性、治理或人在回路（human-in-the-loop）控制，
|
||||
- 需要提供商灵活性，以便架构演进时无需大规模重写。
|
||||
|
||||
## Key Features
|
||||
Explore new MAF capabilities and real implementation patterns on the [official blog](https://devblogs.microsoft.com/agent-framework/).
|
||||
## 核心特性
|
||||
在[官方博客](https://devblogs.microsoft.com/agent-framework/).探索 MAF 的新能力与真实实现模式。
|
||||
|
||||
- **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
|
||||
- [Python packages](./python/packages/) | [.NET source](./dotnet/src/)
|
||||
- **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
|
||||
- [Python examples](./python/samples/02-agents/providers/) | [.NET examples](./dotnet/samples/02-agents/AgentProviders/)
|
||||
- **Middleware**: Flexible middleware system for request/response processing, exception handling, and custom pipelines
|
||||
- [Python middleware](./python/samples/02-agents/middleware/) | [.NET middleware](./dotnet/samples/02-agents/Agents/Agent_Step11_Middleware/)
|
||||
- **Orchestration Patterns & Workflows**: Build multi-agent systems with graph-based workflows supporting sequential, concurrent, handoff, and group collaboration patterns; includes checkpointing, streaming, human-in-the-loop, and time-travel
|
||||
- [Python workflows](./python/samples/03-workflows/) | [.NET workflows](./dotnet/samples/03-workflows/)
|
||||
- **Foundry Hosted Agents (new)**: Deploy and host your agents to Foundry-hosted infrastructure with just 2 additional lines of code
|
||||
- [Python samples](./python/samples/04-hosting/foundry-hosted-agents/) | [.NET samples](./dotnet/samples/04-hosting/FoundryHostedAgents/)
|
||||
- **Observability**: Built-in OpenTelemetry integration for distributed tracing, monitoring, and debugging
|
||||
- [Python observability](./python/samples/02-agents/observability/) | [.NET telemetry](./dotnet/samples/02-agents/AgentOpenTelemetry/)
|
||||
- **Declarative Agents**: Define agents using YAML for faster setup and versioning
|
||||
- [Declarative agent samples](./declarative-agents/)
|
||||
- **Agent Skills**: Build domain-specific knowledge bases from multiple sources—files, inline code, class libraries—for agents to discover and use
|
||||
- [Skills design](./docs/decisions/0021-agent-skills-design.md)
|
||||
- **AF Labs**: Experimental packages for cutting-edge features including benchmarking, reinforcement learning, and research initiatives
|
||||
- [Labs directory](./python/packages/lab/)
|
||||
- **DevUI**: Interactive developer UI for agent development, testing, and debugging workflows
|
||||
- [See the DevUI in action](https://www.youtube.com/watch?v=mOAaGY4WPvc)
|
||||
- **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)
|
||||
|
||||
## Table of Contents
|
||||
## 目录
|
||||
|
||||
- [Getting Started](#getting-started)
|
||||
- [Installation](#installation)
|
||||
- [Learning Resources](#learning-resources)
|
||||
- [Quickstart](#quickstart)
|
||||
- [Basic Agent - Python](#basic-agent---python)
|
||||
- [Basic Agent - .NET](#basic-agent---net)
|
||||
- [More Examples & Samples](#more-examples--samples)
|
||||
- [Community & Feedback](#community--feedback)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
- [Contributor Resources](#contributor-resources)
|
||||
- [入门](#getting-started)
|
||||
- [安装](#installation)
|
||||
- [学习资源](#learning-resources)
|
||||
- [快速入门](#quickstart)
|
||||
- [基础智能体 - Python](#basic-agent---python)
|
||||
- [基础智能体 - .NET](#basic-agent---net)
|
||||
- [更多示例与样例](#more-examples--samples)
|
||||
- [社区与反馈](#community--feedback)
|
||||
- [故障排除](#troubleshooting)
|
||||
- [贡献者资源](#contributor-resources)
|
||||
|
||||
## Getting Started
|
||||
### Installation
|
||||
## 入门
|
||||
### 安装
|
||||
Python
|
||||
|
||||
```bash
|
||||
@@ -91,20 +97,20 @@ dotnet add package Azure.AI.Projects
|
||||
dotnet add package Azure.Identity
|
||||
```
|
||||
|
||||
### Learning Resources
|
||||
### 学习资源
|
||||
|
||||
- **[Overview](https://learn.microsoft.com/agent-framework/overview/agent-framework-overview)** - High level overview of the framework
|
||||
- **[Quick Start](https://learn.microsoft.com/agent-framework/tutorials/quick-start)** - Get started with a simple agent
|
||||
- **[Tutorials](https://learn.microsoft.com/agent-framework/tutorials/overview)** - Step by step tutorials
|
||||
- **[User Guide](https://learn.microsoft.com/en-us/agent-framework/user-guide/overview)** - In-depth user guide for building agents and workflows
|
||||
- **[Migration from Semantic Kernel](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-semantic-kernel)** - Guide to migrate from Semantic Kernel
|
||||
- **[Migration from AutoGen](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-autogen)** - Guide to migrate from AutoGen
|
||||
- **[概述](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 迁移指南
|
||||
|
||||
### Quickstart
|
||||
### 快速入门
|
||||
|
||||
#### Basic Agent - Python
|
||||
#### 基础智能体 - Python
|
||||
|
||||
Create a simple Azure Responses Agent that writes a haiku about the Microsoft Agent Framework
|
||||
创建一个简单的 Azure Responses Agent，撰写一首关于 Microsoft Agent Framework 的俳句
|
||||
|
||||
```python
|
||||
# pip install agent-framework
|
||||
@@ -136,8 +142,8 @@ if __name__ == "__main__":
|
||||
asyncio.run(main())
|
||||
```
|
||||
|
||||
#### Basic Agent - .NET
|
||||
Create a simple Agent, using Microsoft Foundry that writes a haiku about the Microsoft Agent Framework
|
||||
#### 基础智能体 - .NET
|
||||
创建一个简单的 Agent，使用 Microsoft Foundry 撰写一首关于 Microsoft Agent Framework 的俳句
|
||||
|
||||
```c#
|
||||
// This sample shows how to create and run a basic agent with AIProjectClient.AsAIAgent(...).
|
||||
@@ -157,57 +163,58 @@ AIAgent agent =
|
||||
Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));
|
||||
```
|
||||
|
||||
## More Examples & Samples
|
||||
## 更多示例与样例
|
||||
|
||||
### Python
|
||||
|
||||
- [Getting Started](./python/samples/01-get-started): progressive tutorial from hello-world to hosting
|
||||
- [Agent Concepts](./python/samples/02-agents): deep-dive samples by topic (tools, middleware, providers, etc.)
|
||||
- [Workflows](./python/samples/03-workflows): workflow creation and integration with agents
|
||||
- [Hosting](./python/samples/04-hosting): A2A, Azure Functions, Durable Task hosting
|
||||
- [End-to-End](./python/samples/05-end-to-end): full applications, evaluation, and demos
|
||||
- [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): progressive tutorial from hello agent to hosting
|
||||
- [Agent Concepts](./dotnet/samples/02-agents/Agents): basic agent creation and tool usage
|
||||
- [Agent Providers](./dotnet/samples/02-agents/AgentProviders): samples showing different agent providers
|
||||
- [Workflows](./dotnet/samples/03-workflows): advanced multi-agent patterns and workflow orchestration
|
||||
- [Hosting](./dotnet/samples/04-hosting): A2A, Durable Agents, Durable Workflows
|
||||
- [End-to-End](./dotnet/samples/05-end-to-end): full applications and demos
|
||||
- [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)：完整应用与演示
|
||||
|
||||
## Community & Feedback
|
||||
## 社区与反馈
|
||||
|
||||
- **Found a bug?** File a [GitHub issue](https://github.com/microsoft/agent-framework/issues) to help us improve.
|
||||
- **Enjoying MAF?** [](https://github.com/microsoft/agent-framework) to show your support and help others discover the project.
|
||||
- **Have questions?** Join our [Discord](https://discord.gg/b5zjErwbQM) or visit [weekly office hours](./COMMUNITY.md#public-community-office-hours).
|
||||
- **发现 bug？** 请提交 [GitHub issue](https://github.com/microsoft/agent-framework/issues) 以帮助我们改进。
|
||||
- **喜欢 MAF？** [](https://github.com/microsoft/agent-framework) 来表达支持，并帮助他人发现该项目。
|
||||
- **有问题？** 加入我们的 [Discord](https://discord.gg/b5zjErwbQM) 或访问 [weekly office hours（每周公开办公时间）](./COMMUNITY.md#public-community-office-hours)。
|
||||
|
||||
## Troubleshooting
|
||||
## 故障排除
|
||||
|
||||
### Authentication
|
||||
### 身份验证
|
||||
|
||||
| Problem | Cause | Fix |
|
||||
| 问题 | 原因 | 解决方案 |
|
||||
|---------|-------|-----|
|
||||
| Authentication errors when using Azure credentials | Not signed in to Azure CLI | Run `az login` before starting your app |
|
||||
| API key errors | Wrong or missing API key | Verify the key and ensure it's for the correct resource/provider |
|
||||
| 使用 Azure 凭据时出现身份验证错误 | 未登录 Azure CLI | 在启动应用前运行 `az login` |
|
||||
| API 密钥错误 | API 密钥错误或缺失 | 验证密钥，并确保其适用于正确的资源/提供方 |
|
||||
|
||||
> **Tip:** `DefaultAzureCredential` is convenient for development but in production, consider using a specific credential (e.g., `ManagedIdentityCredential`) to avoid latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
|
||||
> **提示：** `DefaultAzureCredential` 便于开发，但在生产环境中，建议使用特定凭据（例如 `ManagedIdentityCredential`），以避免延迟问题、意外的凭据探测，以及回退机制可能带来的安全风险。
|
||||
|
||||
### Environment Variables
|
||||
For environment variable configuration specific to each sample, refer to the README in the sample directory ([Python samples](./python/samples/) | [.NET samples](./dotnet/samples/)).
|
||||
### 环境变量
|
||||
|
||||
## Contributor Resources
|
||||
各样例专有的环境变量配置，请参阅样例目录中的 README（[Python samples（Python 样例）](./python/samples/) | [.NET samples（.NET 样例）](./dotnet/samples/)）。
|
||||
|
||||
- [Contributing Guide](./CONTRIBUTING.md)
|
||||
- [Python Development Guide](./python/DEV_SETUP.md)
|
||||
- [Design Documents](./docs/design)
|
||||
- [Architectural Decision Records](./docs/decisions)
|
||||
## 贡献者资源
|
||||
|
||||
## Important Notes
|
||||
- [Contributing Guide（贡献指南）](./CONTRIBUTING.md)
|
||||
- [Python Development Guide（Python 开发指南）](./python/DEV_SETUP.md)
|
||||
- [Design Documents（设计文档）](./docs/design)
|
||||
- [Architectural Decision Records（架构决策记录）](./docs/decisions)
|
||||
|
||||
## 重要说明
|
||||
|
||||
> [!IMPORTANT]
|
||||
> If you use Microsoft Agent Framework to build applications that operate with any third-party servers, agents, code, or non-Azure Direct models (“Third-Party Systems”), you do so at your own risk. Third-Party Systems are Non-Microsoft Products under the Microsoft Product Terms and are governed by their own third-party license terms. You are responsible for any usage and associated costs.
|
||||
> 若你使用 Microsoft Agent Framework 构建与任何第三方服务器、智能体、代码或非 Azure Direct 模型（“第三方系统”，Third-Party Systems）交互的应用，风险由你自行承担。第三方系统属于 Microsoft 产品条款下的非 Microsoft 产品（Non-Microsoft Products），并受其各自的第三方许可条款约束。你须对任何使用行为及相关费用负责。
|
||||
>
|
||||
>We recommend reviewing all data being shared with and received from Third-Party Systems and being cognizant of third-party practices for handling, sharing, retention and location of data. It is your responsibility to manage whether your data will flow outside of your organization’s Azure compliance and geographic boundaries and any related implications, and that appropriate permissions, boundaries and approvals are provisioned.
|
||||
>我们建议审阅与第三方系统共享及接收的全部数据，并留意第三方在处理、共享、保留及存储数据位置方面的做法。你有责任管理数据是否会流出组织的 Azure 合规与地理边界及相关影响，并确保已配置适当的权限、边界与审批。
|
||||
>
|
||||
>You are responsible for carefully reviewing and testing applications you build using Microsoft Agent Framework in the context of your specific use cases, and making all appropriate decisions and customizations. This includes implementing your own responsible AI mitigations such as metaprompt, content filters, or other safety systems, and ensuring your applications meet appropriate quality, reliability, security, and trustworthiness standards. See also: [Transparency FAQ](./TRANSPARENCY_FAQ.md)
|
||||
>你有责任结合具体用例，仔细审阅并测试使用 Microsoft Agent Framework 构建的应用，并做出一切适当决策与定制。这包括实施你自己的负责任 AI 缓解措施，例如 metaprompt、内容过滤器或其他安全系统，并确保应用达到适当的质量、可靠性、安全性与可信度标准。另请参阅：[Transparency FAQ（透明度常见问题）](./TRANSPARENCY_FAQ.md)
|
||||
|
||||
Reference in New Issue
Block a user