wehub-resource-sync
7e389c1c83
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
221 lines
12 KiB
Markdown
221 lines
12 KiB
Markdown
<!-- 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！
|
||
|
||
[](https://discord.gg/b5zjErwbQM)
|
||
[](https://learn.microsoft.com/en-us/agent-framework/)
|
||
[](https://pypi.org/project/agent-framework/)
|
||
[](https://www.nuget.org/profiles/MicrosoftAgentFramework/)
|
||
[](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？** [](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)
|