快速入门：使用 .NET 创建和测试基本代理

2025-10-28

此示例演示如何从 GitHub 下载并运行快速入门/空代理示例。

可通过两种主要方法开始使用 Microsoft 365 代理 SDK：

克隆并运行 GitHub 上提供的快速入门/空代理代理示例
使用 Microsoft 365 代理工具包。智能体工具包内置两个模板：Visual Studio 模板和 Visual Studio Code 模板，均基于 Microsoft 365 智能体 SDK 构建。其中 QuickStart/Empty 智能体提供基础框架，天气智能体则集成 Azure Foundry 或 OpenAI 服务（可选配 Semantic Kernel 或 LangChain）。

先决条件

在开始之前你需要一些东西。这些步骤使用 .NET 快速入门中的快速入门/空代理示例，但也可以使用任何代理 SDK 示例。

打开解决方案

在 Visual Studio 中打开解决方案文件 QuickStart.csproj 。
启动项目。

此时您的智能体已在本地端口 3978 运行。

在本地测试代理

安装 Agents Playground （如果尚未安装）。
```
winget install agentsplayground
```
在 Visual Studio 或 Visual Studio Code 中启动代理
启动 Teams 应用测试器。在命令提示：agentsplayground
- 该工具将打开一个 Web 浏览器，其中显示了 Teams 应用测试工具，可以向代理发送消息。
端口 3978 上运行的代理应自动连接到浏览器中的代理场，并且应该能够与本地运行的代理进行交互

代理的工作原理是什么？

使用 Agents SDK 时，代理是使用 AgentApplication 和 AgentApplicationOptions 类生成的。这是在 Program.cs 示例文件中生成的。

生成智能体

示例中可见：构建智能体时会加载 AgentApplicationOptions，并加载继承自 AgentApplication 的自定义智能体类 MyAgent.cs

// Add AgentApplicationOptions from appsettings section "AgentApplication".
builder.AddAgentApplicationOptions();

// Add the AgentApplication, which contains the logic for responding to
// user messages.
builder.AddAgent<MyAgent>();

然后，默认情况下使用 MemoryStorage 类加载存储。这允许在使用 TurnState 时跨轮次跟踪上下文，但在生产环境中应切换为更为持久的存储解决方案，例如 BlobsStorage 或 CosmosDbPartitionedStorage。

builder.Services.AddSingleton<IStorage, MemoryStorage>();

代理应用程序的其余部分使用标准 .NET 托管模式，并添加路由以接受特定终结点的消息。这些路由使用 IAgent 接口来接受代理活动，并向开发人员提供 AgentApplication 对象，以便处理从通道或客户端传递来的 Activity 有效负载。进一步了解活动及与活动的交互

// This receives incoming messages from Azure Bot Service or other SDK Agents
var incomingRoute = app.MapPost("/api/messages", async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken cancellationToken) =>
{
    await adapter.ProcessAsync(request, response, agent, cancellationToken);
});

在方法中添加新的自定义逻辑

开发人员在实现MyAgent.cs的AgentApplication类中添加自定义逻辑。该类通过 AgentApplicationOptions 配置文件设置特定参数，并通过 Program.cs 注册智能体 SDK 的活动监听器。这些监听器存在于 AgentApplication 类中，当客户端触发活动时会调用对应的自定义方法。

在以下示例中， OnConversationUpdate 触发 WelcomeMessageAsync 该方法， OnActivity 触发该方法 OnMessageAsync。

   public MyAgent(AgentApplicationOptions options) : base(options)
   {
      OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeMessageAsync);
      OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
   }

这些活动通过 MyProgram.cs 中配置的端点进行路由，您可使用多种活动类型。最常见的是 OnActivity。若要详细了解 SDK 实现的事件，请查看有关使用活动和活动协议规范的详细信息。

触发方法（例如 OnMessageAsync 结束轮次）后，可以在自定义逻辑中选择，以使用在方法中可用的方法和 TurnContext 类的实例（应为方法中的参数）来响应将消息发送回客户端，如以下示例所示：

private async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
{
   await turnContext.SendActivityAsync($"You said: {turnContext.Activity.Text}", cancellationToken: cancellationToken);
}

小窍门

查看可用于返回到客户端的其他 TurnContext 方法。

现在，你已了解基础知识，请查看后续步骤，并努力将自定义处理程序逻辑添加到代理中并发送回不同的事件。

后续步骤

如果已在使用 Microsoft 365 代理工具包，则默认情况下可以使用 Agents Playground。若要开始使用工具包，可以使用以下指南之一：

反馈

此页面是否有帮助？