将逻辑应用添加为插件

项目
07/02/2024

企业中通常已有一组工作流，可在逻辑应用中执行实际工作。这些应用可由人类与之交互的其他自动化服务或电源前端应用程序使用。在语义内核中，可以添加与插件完全相同的工作流，以便代理也可以使用它们。

例如，语义内核团队用来回答有关新 PR 的问题的逻辑应用工作流。通过以下工作流，代理具有检索代码更改、搜索相关文件以及检查失败日志所需的所有内容。

逻辑应用程序

搜索文件 - 查找与给定问题相关的代码片段
获取文件 - 检索 GitHub 存储库中文件的内容
获取 PR 详细信息 - 检索 PR 的详细信息（例如 PR 标题、说明和作者）
获取 PR 文件 - 检索 PR 中已更改的文件
获取生成和测试失败 - 检索给定 GitHub 操作运行的生成和测试失败
获取日志文件 - 检索给定 GitHub 操作运行的日志文件

利用逻辑应用进行语义内核插件也是利用逻辑应用中提供的 1,400 多个连接器的好方法。这意味着，无需编写任何代码即可轻松连接到各种服务和系统。

重要

目前，只能添加标准逻辑应用（也称为单租户逻辑应用）作为插件。即将推出消耗逻辑应用。

将逻辑应用作为插件导入

若要将逻辑应用工作流添加到语义内核，请使用与在 OpenAPI 规范中加载相同的方法。下面是一些示例代码。

await kernel.ImportPluginFromOpenApiAsync(
    pluginName: "openapi_plugin",
    uri: new Uri("https://example.azurewebsites.net/swagger.json"),
    executionParameters: new OpenApiFunctionExecutionParameters()
    {
        // Determines whether payload parameter names are augmented with namespaces.
        // Namespaces prevent naming conflicts by adding the parent parameter name
        // as a prefix, separated by dots
        EnablePayloadNamespacing = true
    }
);

为语义内核设置逻辑应用

必须先将逻辑应用设置为可由语义内核访问，然后才能将逻辑应用导入为插件。这涉及到在最终将逻辑应用导入为具有身份验证的插件之前，启用元数据终结点并配置应用程序以进行 Easy Auth。

启用元数据终结点

对于最简单的设置，可以启用对逻辑应用的元数据终结点的未经身份验证的访问。这样，就可以将逻辑应用作为插件导入语义内核，而无需创建自定义 HTTP 客户端来处理初始导入的身份验证。

以下host.json文件将创建两个未经身份验证的终结点。可以在 Azure 门户中执行此操作，方法是转到 kudu 控制台并编辑位于 C：\home\site\wwwroot\host.json 的 host.json 文件。

{ 
  "version": "2.0", 
  "extensionBundle": { 
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Workflows", 
    "version": "[1.*, 2.0.0)" 
  }, 
  "extensions": { 
    "http": { 
      "routePrefix": "" 
    }, 
    "workflow": { 
      "MetadataEndpoints": { 
        "plugin": { 
          "enable": true, 
          "Authentication":{ 
              "Type":"Anonymous" 
          } 
        }, 
        "openapi": { 
          "enable": true, 
          "Authentication":{ 
              "Type":"Anonymous" 
          } 
        } 
      }, 
      "Settings": { 
        "Runtime.Triggers.RequestTriggerDefaultApiVersion": "2020-05-01-preview" 
      } 
    } 
  } 
}

为应用程序配置 Easy Auth

现在，你希望保护逻辑应用工作流，以便只有经过授权的用户才能访问它们。为此，可以在逻辑应用上启用 Easy Auth。这样，就可以使用与其他 Azure 服务相同的身份验证机制，以便更轻松地管理安全策略。

有关设置 Easy Auth 的深入演练，请参阅本教程标题为使用 Easy Auth 的标准逻辑应用中的“触发工作流”。

对于熟悉 Easy Auth（并且已有要使用的 Entra 客户端应用）的用户，这是要发布到 Azure 管理的配置。

#!/bin/bash

# Variables
subscription_id="[SUBSCRIPTION_ID]"
resource_group="[RESOURCE_GROUP]"
app_name="[APP_NAME]"
api_version="2022-03-01"
arm_token="[ARM_TOKEN]"
tenant_id="[TENANT_ID]"
aad_client_id="[AAD_CLIENT_ID]"
object_ids=("[OBJECT_ID_FOR_USER1]" "[OBJECT_ID_FOR_USER2]" "[OBJECT_ID_FOR_APP1]")

# Convert the object_ids array to a JSON array
object_ids_json=$(printf '%s\n' "${object_ids[@]}" | jq -R . | jq -s .)

# Request URL
url="https://management.azure.com/subscriptions/$subscription_id/resourceGroups/$resource_group/providers/Microsoft.Web/sites/$app_name/config/authsettingsV2?api-version=$api_version"

# JSON payload
json_payload=$(cat <<EOF
{
    "properties": {
        "platform": {
            "enabled": true,
            "runtimeVersion": "~1"
        },
        "globalValidation": {
            "requireAuthentication": true,
            "unauthenticatedClientAction": "AllowAnonymous"
        },
        "identityProviders": {
            "azureActiveDirectory": {
                "enabled": true,
                "registration": {
                    "openIdIssuer": "https://sts.windows.net/$tenant_id/",
                    "clientId": "$aad_client_id"
                },
                "validation": {
                    "jwtClaimChecks": {},
                    "allowedAudiences": [
                        "api://$aad_client_id"
                    ],
                    "defaultAuthorizationPolicy": {
                        "allowedPrincipals": {
                            "identities": $object_ids_json
                        }
                    }
                }
            },
            "facebook": {
                "enabled": false,
                "registration": {},
                "login": {}
            },
            "gitHub": {
                "enabled": false,
                "registration": {},
                "login": {}
            },
            "google": {
                "enabled": false,
                "registration": {},
                "login": {},
                "validation": {}
            },
            "twitter": {
                "enabled": false,
                "registration": {}
            },
            "legacyMicrosoftAccount": {
                "enabled": false,
                "registration": {},
                "login": {},
                "validation": {}
            },
            "apple": {
                "enabled": false,
                "registration": {},
                "login": {}
            }
        }
    }
}
EOF
)

# HTTP PUT request
curl -X PUT "$url" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $arm_token" \
    -d "$json_payload"

将具有语义内核的逻辑应用用作插件

现在，你已保护逻辑应用并启用了元数据终结点，你已完成所有硬部分。现在，可以使用 OpenAPI 导入方法将逻辑应用作为插件导入到语义内核。

创建插件时，需要提供可以处理逻辑应用的身份验证的自定义 HTTP 客户端。这样就可以在 AI 代理中使用插件，而无需担心身份验证。

下面是 C# 中的一个示例，它利用交互式身份验证来获取令牌，并为逻辑应用对用户进行身份验证。

string ClientId = "[AAD_CLIENT_ID]";
string TenantId = "[TENANT_ID]";
string Authority = $"https://login.microsoftonline.com/{TenantId}";
string[] Scopes = new string[] { "api://[AAD_CIENT_ID]/SKLogicApp" };

var app = PublicClientApplicationBuilder.Create(ClientId)
            .WithAuthority(Authority)
            .WithDefaultRedirectUri() // Uses http://localhost for a console app
            .Build();

AuthenticationResult authResult = null;
try
{
    authResult = await app.AcquireTokenInteractive(Scopes).ExecuteAsync();
}
catch (MsalException ex)
{
    Console.WriteLine("An error occurred acquiring the token: " + ex.Message);
}

// Add the plugin to the kernel with a custom HTTP client for authentication
kernel.Plugins.Add(await kernel.ImportPluginFromOpenApiAsync(
    pluginName: "[NAME_OF_PLUGIN]",
    uri: new Uri("https://[LOGIC_APP_NAME].azurewebsites.net/swagger.json"),
    executionParameters: new OpenApiFunctionExecutionParameters()
    {
        HttpClient = new HttpClient()
        {
            DefaultRequestHeaders =
            {
                Authorization = new AuthenticationHeaderValue("Bearer", authResult.AccessToken)
            }
        },
    }
));

后续步骤

了解如何创建插件后，现在可以了解如何将其与 AI 代理配合使用。根据添加到插件的函数类型，应遵循不同的模式。有关检索函数，请参阅 using 检索函数一文。有关任务自动化函数，请参阅使用任务自动化函数一文。

了解如何使用检索函数

通过