翻译：https://devblogs.microsoft.com/dotnet/introducing-microsoft-agent-framework-preview/

构建 AI 代理并非难事。然而，许多开发者却发现自己被复杂的编排逻辑搞得焦头烂额，难以连接多个 AI 模型，或者花费数周时间构建托管基础设施，只是为了将一个简单的代理投入生产。

如果构建 AI 代理可以像创建 Web API 或控制台应用程序一样简单，那会怎样？

Agent (智能体) 与工作流 (Workflow)

在深入探讨之前，让我们先来定义一下智能体系统的两个核心构建块：智能体和工作流。

Agent 智能体

在网络上，你会发现许多关于智能体的定义。有些相互矛盾，有些则有所重叠。

在本文中，我们将简单概括：智能体就是实现目标的系统。

具备以下能力的智能体将更加强大：

• 推理和决策：由人工智能模型 (LLM)、搜索算法或规划和决策系统提供支持。
• 工具使用：访问模型上下文协议 (MCP) 服务器、代码执行和外部 API。
• 情境感知：由聊天记录、线程、向量存储、企业数据或知识图谱提供信息。
  这些功能使智能体能够更加自主、自适应和智能地运行。

工作流

随着目标的复杂性不断增加，需要将其分解为易于管理的步骤。这就是工作流的作用所在。

工作流定义了实现目标所需的步骤顺序。

想象一下，您正在企业网站上发布一项新功能。如果只是一个简单的更新，您可能只需几个小时就能从构思到投入生产。但对于更复杂的项目，该流程可能包括：

• 需求收集
• 设计和架构
• 实施
• 测试
• 部署

一些重要的观察：

• 每个步骤可能包含子任务。
• 不同的专家可能负责不同的阶段。
• 进度并非总是线性的。测试期间发现的错误可能会让您回到实施阶段。
• 成功取决于利益相关者之间的规划、编排和沟通。

智能体 + 工作流

工作流不需要代理，但代理可以增强工作流。

当代理具备推理能力、工具和上下文时，它们可以优化工作流。

这是多代理系统的基础，在多代理系统中，代理在工作流内协作以实现复杂的目标。

了解 Microsoft Agent Framework

Microsoft Agent Framework 是一套完整的 .NET 库，可降低代理开发的复杂性。无论您是构建简单的聊天机器人，还是在复杂的工作流中编排多个 AI 代理，Microsoft Agent Framework 都能提供您所需的工具：

• 使用最少的样板代码构建代理
• 轻松编排多代理工作流
• 使用熟悉的 .NET 模式托管和部署代理
• 监控和观察生产环境中的代理行为

更多详细内容，请参考：Introducing Microsoft Agent Framework post in the Foundry blog.

https://youtu.be/yOBcPuLLmuY

基于成熟基础

Microsoft Agent Framework 利用成熟技术简化 .NET 开发人员的代理开发：

• Semantic Kernel – 提供强大的编排功能
• AutoGen – 支持先进的多代理协作和尖端的研究驱动技术
• Microsoft.Extensions.AI – 为 .NET 提供标准化的 AI 构建模块。

通过整合这些技术，Agent Framework 提供了可靠性、灵活性和开发者友好的 API。这使您能够快速高效地构建和部署强大的 AI 代理。

从简单开始：几分钟内构建您的第一个代理

Microsoft Agent Framework 的入门非常简单。在以下示例中，您将构建一个用于生成引人入胜短篇故事的创意写作代理。

最快的试用方法是打开 GitHub Codespaces 中的 Hello World Agents 示例.

如果您愿意，可以按照以下分步说明在您自己的机器上设置项目。

步骤 0：配置先决条件

首先，您需要以下条件：

• .NET 9 SDK 或更高版本
• 一个包含模型范围的 GitHub 个人访问令牌 (PAT)。您可以在 GitHub 设置中创建一个。更多详情，请参阅 GitHub 文档。

此项目可以使用 GitHub 托管的模型，因此您需要使用 GITHUB_TOKEN 环境变量向您的应用程序提供 GitHub 个人访问令牌 (PAT)。

Windows:

setx GITHUB_TOKEN "YOUR-GITHUB-TOKEN"
# Restart your shell to pick up the value

Linux/Mac

export GITHUB_TOKEN="YOUR-GITHUB-TOKEN"

步骤 1：创建项目

1. 创建一个新的 C# 控制台项目，安装 Agent Framework 包

dotnet new console -o HelloWorldAgents
cd HelloWorldAgents
dotnet add package Microsoft.Agents.AI --prerelease

2. 还需要你安装如下的 NuGet 包以使用来自 GitHub 模型库中的模型

dotnet add package OpenAI
dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
dotnet add package Microsoft.Extensions.AI

步骤 2： 编写你的智能体

1. 将下面的代码添加到你的 Program.cs 文件中来创建编写-故事的智能体。

using Microsoft.Extensions.AI;
using Microsoft.Agents.AI;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel;

IChatClient chatClient =
    new ChatClient(
            "gpt-4o-mini",
            new ApiKeyCredential(Environment.GetEnvironmentVariable("GITHUB_TOKEN")!),
            new OpenAIClientOptions { Endpoint = new Uri("https://models.github.ai/inference") })
        .AsIChatClient();

AIAgent writer = new ChatClientAgent(
    chatClient,
    new ChatClientAgentOptions
    {
        Name = "Writer",
        Instructions = "Write stories that are engaging and creative."
    });

AgentRunResponse response = await writer.RunAsync("Write a short story about a haunted house.");

Console.WriteLine(response.Text);

2. 执行程序

就这样，只需要几行代码，你就已经拥有了一个全功能的 AI 智能体！

抽象的力量

Microsoft Agent Framework 围绕强大的抽象概念而设计，旨在简化代理开发。

其核心是 AI Agent 抽象，它为构建代理提供了统一的接口。Microsoft.Extensions.AI 提供了使用任何兼容 AI 模型提供程序的灵活性，它通过 IChatClient 接口标准化了模型访问。

AIAgent 的 ChatClientAgent 实现接受任何 IChatClient，让您可以轻松地在以下提供程序之间进行选择：

• OpenAI
• Azure OpenAI
• Foundry Local
• Ollama
• GitHub Models
• 其他

这意味着您可以更换提供程序或集成新的提供程序，而无需更改代理代码。相同的 AIAgent 接口可与以下平台无缝协作：

• Azure Foundry Agents
• OpenAI Assistants
• Copilot Studio
• 其他

如果您使用不同的 SDK 或平台构建了代理，那么使用 Microsoft Agent Framework 非常简单。您将获得一致的开发体验，并可以利用编排、托管和监控功能。

扩展：协调多个代理

单个代理功能强大，但实际场景中通常需要多个专门的代理协同工作。也许你的写作代理创作了精彩的内容，但你还需要一位编辑来润色，或者一位事实核查员来核实细节。

Agent Framework 使多代理协调变得像连接构建块一样简单。

添加专门的代理

让我们通过添加一位编辑代理来审核和改进作者的作品，从而增强我们的故事示例：

// Create a specialized editor agent
AIAgent editor = new ChatClientAgent(
    chatClient,
    new ChatClientAgentOptions
    {
        Name = "Editor",
        Instructions = "Make the story more engaging, fix grammar, and enhance the plot."
    });

构建工作流

现在进入魔术环节！在工作流中连接这些智能体。

1. 安装如下的 NuGet 包 Microsoft.Agengs.Workflows

dotnet add package Microsoft.Agents.AI.Workflows --prerelease

2. 创建工作流以编排你的智能体

// Create a workflow that connects writer to editor
Workflow workflow =
    AgentWorkflowBuilder
        .BuildSequential(writer, editor);

AIAgent workflowAgent = await workflow.AsAgentAsync();

AgentRunResponse workflowResponse =
    await workflowAgent.RunAsync("Write a short story about a haunted house.");

Console.WriteLine(workflowResponse.Text);

结果

现在，当您运行应用程序时，作者会创建初始故事，编辑会自动审核并改进。整个工作流程在外部世界中就像一个单一的、更强大的代理。

此模式可扩展至任何复杂程度：

• 研究工作流：研究员 → 事实核查员 → 摘要员
• 内容流水线：作者 → 编辑 → SEO 优化 → 发布者
• 客户服务：意图分类 → 客户专家代理 → 质量审核员

这里的关键点是，复杂的代理系统是由简单、专注的代理组成的。

所有类型的工作流

上面的示例使用顺序工作流，其中代理逐个处理任务，每个任务都基于前一个代理的输出进行构建。但是，Microsoft Agent Framework 支持多种工作流模式，以满足不同的需求：

• 顺序：代理按顺序执行，并将结果沿链传递。
• 并发：多个代理并行工作，同时处理任务的不同方面。
• 切换：根据上下文或结果，代理之间的职责切换。
• 群聊：代理在共享的实时对话空间中协作。
  这些灵活的工作流类型支持从简单流水线到动态多代理协作的所有内容的编排。

使用工具赋能代理

Microsoft Agent Framework 让您的代理能够轻松访问外部功能、API 和服务，从而轻松采取行动。

创建代理工具

让我们使用一些实用的工具来增强我们的写作代理。在我们的故事示例中，我们可能需要能够执行以下操作的代理：

[Description("Gets the author of the story.")]
string GetAuthor() => "Jack Torrance";

[Description("Formats the story for display.")]
string FormatStory(string title, string author, string story) =>
    $"Title: {title}\nAuthor: {author}\n\n{story}";

为智能体连接工具

将这些工具添加到您的代理非常简单。以下是我们的编写器代理的修改版本，配置为使用之前定义的工具。

AIAgent writer = new ChatClientAgent(
    chatClient,
    new ChatClientAgentOptions
    {
        Name = "Writer",
        Instructions = "Write stories that are engaging and creative.",
        ChatOptions = new ChatOptions
        {
            Tools = [
                AIFunctionFactory.Create(GetAuthor),
                AIFunctionFactory.Create(FormatStory)
            ],
        }
    });

再次运行该应用程序将生成一个按照您在 FormatStory 中提供的模板格式化的故事。

**Title: The Haunting of Blackwood Manor**
**Author: Jack Torrance**

On the outskirts of a quaint village, a grand but crumbling mansion, known as Blackwood Manor, loomed against the twilight sky. Locals spoke in hushed tones about the house, claiming it was haunted by the spirits of its former inhabitants, who had mysteriously vanished decades ago. Tales of flickering lanterns, echoing whispers, and the ghostly figure of a woman in white gliding through the halls filled the village’s atmosphere with a sense of dread
//...

超越简单功能

由
​​于 Microsoft Agent Framework 基于 Microsoft.Extensions.AI 构建，您的代理可以使用更强大的工具，包括：

• 模型上下文协议 (MCP) 服务器 – 连接到外部服务，例如数据库、API 和第三方工具
• 托管工具 – 访问服务器端工具，例如代码解释器、Bing Grounding 等等

例如，您可以连接到提供数据库访问、网页搜索甚至硬件控制的 MCP 服务器。在我们的 MCP 客户端快速入门中了解更多关于构建 MCP 集成的信息。

安心部署：托管变得简单

将代理投入生产环境并不意味着需要学习新的部署模型。Microsoft Agent Framework 可以与您已使用的 .NET 托管模式无缝集成。

精简 Web API 集成

在 REST API 中使用您的代理只需几行代码。

在 ASP.NET 精简 Web API 中，首先注册您的 IChatClient：

builder.AddOpenAIClient("chat")
    .AddChatClient(Environment.GetEnvironmentVariable("MODEL_NAME")!);

使用 Microsoft.Agents.AI.Hosting NuGet 包来注册你的智能体

```csharp
builder.AddAIAgent("Writer", (sp, key) =>
{
    var chatClient = sp.GetRequiredService<IChatClient>();

    return new ChatClientAgent(
        chatClient,
        name: key,
        instructions:
            """
            You are a creative writing assistant who crafts vivid, 
            well-structured stories with compelling characters based on user prompts, 
            and formats them after writing.
            """,
        tools: [
            AIFunctionFactory.Create(GetAuthor),
            AIFunctionFactory.Create(FormatStory)
        ]
    );
});

builder.AddAIAgent(
    name: "Editor",
    instructions:
        """
        You are an editor who improves a writer’s draft by providing 4–8 concise recommendations and 
        a fully revised Markdown document, focusing on clarity, coherence, accuracy, and alignment.
        """);

一旦完成注册，就可以在你的应用中的任何地方使用它。

app.MapGet("/agent/chat", async (
    [FromKeyedServices("Writer")] AIAgent writer,
    [FromKeyedServices("Editor")] AIAgent editor,
    HttpContext context,
    string prompt) =>
{
    Workflow workflow =
        AgentWorkflowBuilder
            .CreateGroupChatBuilderWith(agents =>
                new AgentWorkflowBuilder.RoundRobinGroupChatManager(agents)
                {
                    MaximumIterationCount = 2
                })
            .AddParticipants(writer, editor)
            .Build();

    AIAgent workflowAgent = await workflow.AsAgentAsync();

    AgentRunResponse response = await workflowAgent.RunAsync(prompt);
    return Results.Ok(response);
});

产品级别就绪的特性

Microsoft Agent Framework 托管包含您生产所需的一切：

• 配置 – 通过标准 .NET 配置管理代理设置
• 依赖注入 – 与您现有的 DI 容器和实践集成
• 中间件支持 – 添加身份验证、速率限制或自定义逻辑

部署

Microsoft Agent Framework 不会彻底改造部署。如果您知道如何发布 .NET 应用，那么您就已经知道如何发布代理。

无需新的工具。无需特殊的托管模型。只需添加代理并部署到任何 .NET 运行的地方即可。

观察和改进：内置监控

生产代理需要可观察性。Microsoft Agent Framework 提供全面的监控功能，可与您现有的可观察性堆栈集成。

OpenTelemetry 集成

只需一行代码即可启用详细的遥测：

// Enhanced telemetry for all your agents
writer.WithOpenTelemetry();
editor.WithOpenTelemetry();

这将获得：

• 对话流 – 可视化代理之间的消息传输方式
• 模型使用情况 – 跟踪令牌消耗、模型选择和成本
• 性能指标 – 监控响应时间和吞吐量
• 错误跟踪 – 快速识别和调试问题

丰富的仪表板

连接到您现有的可观察性平台（例如：

• Aspire
• Azure Monitor
• Grafana
• 其他平台

您可以获得代理行为的详细洞察，帮助您优化性能并在问题影响用户之前发现它们。

OpenTelemetry 与 Aspire

要将代理遥测数据发送到 Aspire 仪表板，请启用 OpenTelemetry 并允许敏感数据，以获得更丰富的洞察。

配置客户端时，将 EnableSensitiveTelemetryData 设置为 true：

builder
    .AddAzureChatCompletionsClient("chat", settings =>
    {
        settings.EnableSensitiveTelemetryData = true;
    })
    .AddChatClient(Environment.GetEnvironmentVariable("MODEL_NAME")!);

然后，配置 Aspire 来识别 Telemetry 源

public static TBuilder ConfigureOpenTelemetry<TBuilder>(this TBuilder builder) where TBuilder : IHostApplicationBuilder
{
    builder.Logging.AddOpenTelemetry(logging =>
    {
      //...
    })
    .AddTraceSource("Experimental.Microsoft.Extensions.AI.*");

    builder.Services.AddOpenTelemetry()
        .WithMetrics(metrics =>
        {
            metrics.AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation()
                .AddRuntimeInstrumentation()
                .AddMeter("Experimental.Microsoft.Extensions.AI.*");
        })
        .WithTracing(tracing =>
        {
            tracing.AddSource(builder.Environment.ApplicationName)
                .AddSource("Experimental.Microsoft.Extensions.AI.*")
                .AddAspNetCoreInstrumentation()
                .AddHttpClientInstrumentation();
        });
        //...
}

使用这些配置，Aspire 仪表板可以展示详细的遥测数据，包括会话流，模型使用，性能指标，以及错误跟踪。

确保质量：评估和测试

对人工智能系统的信任源于严格的评估。Microsoft Agent Framework 可以轻松与 Microsoft.Extensions.AI.Evaluations 集成，帮助您构建可靠、值得信赖的代理系统。

这将实现：

• 自动化测试 – 将评估套件作为 CI/CD 流水线的一部分运行
• 质量指标 – 衡量相关性、一致性和安全性
• 回归检测 – 在部署前发现质量下降
• A/B 测试 – 比较不同的配置

了解 如何使用 Microsoft.Extensions.AI.Evaluations 开始评估。

立即开始构建代理

Microsoft Agent Framework 将代理开发从一项复杂的专业技能转变为每个 .NET 开发人员都能掌握的技能。无论您是构建聊天机器人，还是在复杂的工作流中协调多个人工智能代理，Microsoft Agent Framework 都能为您提供清晰的指导。

关键要点

• 设计简洁：只需几行代码即可开始使用。只需几分钟，而不是几天，即可创建您的第一个代理。
• 随您扩展：从单个代理开始，然后随着需求的增长，轻松添加工作流、工具、托管和监控。
• 基于成熟技术构建：Microsoft Agent Framework 汇集了 AutoGen 和 Semantic Kernel 的精髓。它基于 Microsoft.Extensions.AI（现代 AI 开发的统一基础）构建，为 .NET 开发者提供强大而一致的体验。
• 生产就绪：使用熟悉的 .NET 模式进行部署，并内置可观察性、评估和托管功能。

下一步是什么？

准备好开始构建了吗？

运行 Hello World 代理示例。

然后，前往 Microsoft Agent Framework 文档 继续学习。

软件开发的未来将 AI 代理作为现代软件开发的首要组件。Microsoft Agent Framework 确保每个 .NET 开发人员都能轻松使用 AI 代理。