教程：使用Microsoft语义内核或 Foundry 代理服务（.NET）在 Azure 应用服务中生成代理 Web 应用

本教程演示如何将代理功能添加到现有数据驱动的 ASP.NET Core CRUD 应用程序。 它使用两种不同的方法执行此作：Microsoft语义内核和 Foundry 代理服务。

如果 Web 应用程序已具有有用的功能（如购物、酒店预订或数据管理），则通过将这些功能包装在插件（对于语义内核）或 OpenAPI 终结点（对于 Foundry 代理服务）中来向 Web 应用程序添加代理功能相对简单。 本教程从简单的 to-do 列表应用开始。 最后，你将能够使用应用服务应用中的代理创建、更新和管理任务。

语义内核

Foundry 智能体服务

通过语义内核和 Foundry 代理服务，您可以构建具备 AI 驱动能力的代理 Web 应用程序。 下表显示了一些注意事项和权衡：

Consideration	语义内核	Foundry 代理服务
Performance	快速（在本地运行）	速度较慢（托管的远程服务）
Development	完整代码，最大控制	低代码，快速集成
Testing	代码中的手动/单元测试	用于快速测试的内置沙盒
Scalability	应用托管	Azure 托管，自动缩放

本教程中，您将学习如何：

• 将现有应用功能转换为语义内核的插件。
• 将插件添加到语义内核代理并在 Web 应用中使用它。
• 将现有应用的功能性转换为 Foundry 代理服务的 OpenAPI 端点。
• 在 Web 应用中调用 Microsoft Foundry 代理。

• 分配建立托管标识连接所需的权限。

Prerequisites

• 具有活动订阅的 Azure 帐户 - 免费创建帐户。
• GitHub 帐户用于使用 GitHub Codespaces - 详细了解 GitHub Codespaces。

使用 Codespaces 打开示例

最简单的入门方法是使用 GitHub Codespaces，它提供一个完整的开发环境，并预装了所有必需的工具。

1. 请导航至位于https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent的 GitHub 存储库。

2. 选择 “代码 ”按钮，选择 “Codespaces ”选项卡，然后选择 “在 main 上创建代码空间”。

3. 请稍等片刻，让 Codespace 初始化。 准备就绪后，浏览器中会显示完全配置的开发环境。

4. 在本地运行应用程序：

   dotnet run
   

5. 当看到 端口 5280 上运行的应用程序可用时，请选择“ 在浏览器中打开 ”并添加一些任务。

查看代理代码

这两种方法使用相同的实现模式，其中代理初始化为提供程序中的服务（Program.cs），并注入到相应的 Blazor 组件中。

语义内核

在 SemanticKernelAgentProvider 文件中对 进行了初始化。 初始化代码执行以下作：

• 创建具有聊天完成功能的内核。
• 添加一个内核插件，该插件封装 CRUD 应用程序的功能（在 Plugins/TaskCrudPlugin.cs 中）。 插件的唯一有趣部分是 KernelFunction 方法定义的属性和 Description 帮助内核智能调用插件的属性。
• 创建 聊天完成代理，并将其配置为让 AI 模型自动调用函数（FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()）。

public class SemanticKernelAgentProvider : ISemanticKernelAgentProvider
{
    public bool IsConfigured { get; }
    public ChatCompletionAgent? Agent { get; }

    public SemanticKernelAgentProvider(IConfiguration config, IServiceProvider sp)
    {
        IsConfigured = false;
        Agent = null;

        // Initialize a semantic kernel
        var deployment = config["ModelDeployment"];
        var endpoint = config["AzureOpenAIEndpoint"];
        if (string.IsNullOrWhiteSpace(deployment) || string.IsNullOrWhiteSpace(endpoint))
        {
            return;
        }
        var kernel = Kernel.CreateBuilder()
            .AddAzureOpenAIChatCompletion(
                deploymentName: deployment,
                endpoint: endpoint,
                new DefaultAzureCredential()
            ).Build();
        // Add the tasks CRUD plugin
        kernel.Plugins.AddFromType<TaskCrudPlugin>(serviceProvider: sp);

        // Create a chat completion agent
        Agent = new ChatCompletionAgent
        {
            Name = "TaskManagerAgent",
            Instructions =
                @"""
                Your are an agent that manages tasks using CRUD operations. 
                Use the TaskCrudPlugin functions to create, read, update, and delete tasks. 
                Always call the appropriate plugin function for any task management request.
                Don't try to handle any requests that are not related to task management.
                When handling requests, if you're missing any information, don't make it up but prompt the user for it instead.
                """,
            Kernel = kernel,
            Arguments = new KernelArguments(new AzureOpenAIPromptExecutionSettings()
            {
                FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
            })
        };

        IsConfigured = true;
    }
}

Foundry 智能体服务

提供程序 FoundryAgentProvider 在 Services/FoundryAgentProvider.cs 中初始化。 初始化代码执行以下作：

• 创建新的代理客户端。
• 创建新线程。
• 获取由代理 ID 指定的命名代理。

public class FoundryAgentProvider : IFoundryAgentProvider
{
    public bool IsConfigured { get; }
    public PersistentAgentsClient? Client { get; }
    public string? ThreadId { get; }
    public PersistentAgent? Agent { get; }

    public FoundryAgentProvider(IConfiguration config)
    {
        IsConfigured = false;

        // Create a new client instance
        var endpoint = config["AzureAIFoundryProjectEndpoint"];
        if (string.IsNullOrWhiteSpace(endpoint))
        {
            return; // Fail gracefully
        }
        Client = new PersistentAgentsClient(endpoint, new Azure.Identity.DefaultAzureCredential());

        // Create a new thread. 
        PersistentAgentThread agentThread = Client.Threads.CreateThread();
        ThreadId = agentThread.Id;

        // Create a new angent instance
        var agentId = config["AzureAIFoundryAgentId"];
        if (string.IsNullOrWhiteSpace(agentId))
        {
            return; // Fail gracefully
        }
        Agent = Client.Administration.GetAgent(agentId);

        IsConfigured = true;
    }
}

此初始化代码不定义代理的任何功能，因为通常会在 Foundry 门户中生成代理。 作为示例方案的一部分，它还遵循 在 Foundry 代理服务（.NET）中将应用服务应用添加为工具的 OpenAPI 模式，并将其 CRUD 功能作为 OpenAPI 终结点提供。 这允许稍后将其作为可调用工具添加到代理。

OpenAPI 代码在 Program.cs中定义。 例如，“获取任务”API 使用 WithName()定义操作 ID，这是 Microsoft Foundry 中的 OpenAPI 规范工具所需，它帮助代理确定如何调用 API。

app.MapGet("/api/tasks", async (TaskService taskService) =>
{
    return Results.Ok(await taskService.GetAllTasksAsync());
})
.WithDescription("Gets all tasks.")
.WithName("GetAllTasks");

部署示例应用程序

示例存储库包含一个 Azure 开发人员 CLI （AZD） 模板，该模板使用托管标识创建应用服务应用并部署示例应用程序。

1. 在终端中，使用 Azure 开发人员 CLI 登录到 Azure：

   azd auth login
   

   按照说明完成身份验证过程。

2. 使用 AZD 模板部署 Azure 应用服务应用：

   azd up
   

3. 出现提示时，请提供以下答案：

   Question	Answer
   输入新的环境名称：	键入唯一名称。
   选择要使用的 Azure 订阅：	选择订阅。
   选择要使用的资源组：	选择“新建资源组”。
   选择要在其中创建资源组的位置：	选择任何区域。 实际上，资源将在 美国东部 2 中生成。
   输入新资源组的名称：	键入 Enter。

4. 在 AZD 输出中，找到应用的 URL 并在浏览器中导航到该 URL。 该 URL 在 AZD 输出中如下所示：

    Deploying services (azd deploy)
   
      (✓) Done: Deploying service web
      - Endpoint: <URL>
    

5. 选择 OpenAPI 架构 项以在默认 /openapi/v1.json 路径中打开自动生成的 OpenAPI 架构。 稍后需要此架构。

6. 成功部署后，会看到已部署应用程序的 URL。

   现在已有了一个具有系统分配的托管标识的应用服务应用。

创建和配置 Microsoft Foundry 资源

1. 在 Foundry 门户中，部署所选的模型（请参阅 快速入门：Microsoft Foundry 入门）。 在此过程中会为你创建一个项目和一个默认代理。

2. 从左侧菜单中选择“概述”。

3. 选择 Microsoft Foundry ，并在 Microsoft Foundry 项目终结点中复制 URL。

4. 选择 Azure OpenAI ，并在 Azure OpenAI 终结点 中复制 URL 供以后使用。

   

5. 从左侧菜单中选择 “代理”，然后选择默认代理。

6. 在 “安装 ”窗格中，复制 代理 ID 以及 部署中的模型名称。

   

7. 在 “设置” 窗格中，使用 OpenAPI 规格工具添加操作。 使用从部署的 Web 应用和 匿名 身份验证获取的 OpenAPI 架构。 有关详细步骤，请参阅 如何使用 OpenAPI 规范工具。

   应用程序代码已配置为包含服务器的 url 和 operationId，这两项为代理所需。 有关详细信息，请参阅 如何将 Foundry 代理服务与 OpenAPI 指定工具配合使用：先决条件。

8. 选择 在测试环境中试用，并使用如 “显示所有任务” 和 “请添加任务” 的提示来测试 Foundry 代理。

   如果收到有效的响应，代理正在对已部署的 Web 应用上的 OpenAPI 终结点进行工具调用。

分配所需的权限

1. 在 Foundry 门户的右上角，选择资源的名称，然后选择 资源组 以在 Azure 门户中打开它。

   

2. 使用下表为应用服务应用的管理标识的两个资源中的每一个添加一个角色：

   目标资源	所需角色	用于
   Microsoft Foundry	认知服务 OpenAI 用户	语义内核中的聊天完成服务。
   Microsoft Foundry 项目	Azure AI 用户	读取并调用 Foundry 代理。

   有关说明，请参阅使用 Azure 门户分配 Azure 角色。

在示例应用程序中配置连接变量

1. 打开 appsettings.json。 使用前面从 Foundry 门户复制的值，配置以下变量：

   Variable	Description
   AzureOpenAIEndpoint	Azure OpenAI 终结点（从“概述”页面复制）。 语义内核代理需要此项。
   ModelDeployment	部署中的模型名称（从“代理配置窗口”复制）。 语义内核代理需要此项。
   AzureAIFoundryProjectEndpoint	Microsoft Foundry 项目终结点（从“概述”页复制）。 Foundry 代理服务需要此项。
   AzureAIFoundryAgentId	代理 ID（从“代理设置”窗格复制）。 为了调用现有的 Microsoft Foundry 代理，需要这个。

   Note

   为了简化本教程，你将在 appsettings.json 使用这些变量，而不是用应用服务中的应用设置覆盖它们。

2. 使用 Azure CLI 登录到 Azure：

   az login
   

   这允许示例代码中的 Azure 标识客户端库接收已登录用户的身份验证令牌。 请记住，之前已为此用户添加了所需的角色。

3. 在本地运行应用程序：

   dotnet run
   

4. 当看到 端口 5280 上运行的应用程序可用时，请选择“ 在浏览器中打开”。

5. 选择 语义内核代理 链接和 Microsoft Foundry 代理 链接以试用聊天界面。 如果收到响应，应用程序将成功连接到 Microsoft Foundry 资源。

6. 返回 GitHub codespace，部署应用更改。

   azd up
   

7. 再次导航到已部署的应用程序并测试聊天代理。

语义内核

Foundry 智能体服务

清理资源

完成应用程序后，可以删除应用服务资源，以避免产生进一步的成本：

azd down --purge

由于 AZD 模板不包含 Microsoft Foundry 资源，需要根据需要手动删除它们。

更多资源

• 将 AI 集成到 Azure 应用服务应用程序中
• 什么是 Foundry 智能体服务？
• 语义内核简介