Logic Apps をプラグインとして追加する

[アーティクル]
07/02/2024

多くの場合、企業には、Logic Apps で実際の作業を実行する一連のワークフローが既にあります。これらは、人間が操作する他のオートメーションサービスや電源フロントエンドアプリケーションで使用できます。セマンティックカーネルでは、これらのワークフローをプラグインとまったく同じに追加して、エージェントで使用することもできます。

たとえば、セマンティックカーネルチームが新しい PR に関する質問に回答するために使用する Logic Apps ワークフローを考えてみます。次のワークフローでは、エージェントには、コード変更の取得、関連ファイルの検索、エラーログの確認に必要なものがすべて含まれています。

Logic Apps

ファイルの検索 – 特定の問題に関連するコードスニペットを検索します
ファイルの取得 – GitHub リポジトリ内のファイルの内容を取得します
PR の詳細を取得する – PR の詳細 (PR のタイトル、説明、作成者など) を取得します。
PR ファイルの取得 – PR で変更されたファイルを取得します。
ビルドとテストの失敗を取得する – 特定の GitHub アクション実行のビルドとテストの失敗を取得します
ログファイルの取得 – 特定の GitHub アクション実行のログファイルを取得します

セマンティックカーネルプラグインに Logic Apps を利用することは、Logic Apps で使用可能な 1,400 以上のコネクタを活用する優れた方法でもあります。つまり、コードを記述することなく、さまざまなサービスやシステムに簡単に接続できます。

重要

現時点では、標準の Logic Apps (シングルテナント Logic Apps とも呼ばれます) のみをプラグインとして追加できます。従量課金ロジックアプリは近日公開予定です。

Logic Apps をプラグインとしてインポートする

Logic Apps ワークフローをセマンティックカーネルに追加するには、 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
    }
);

セマンティックカーネル用の Logic Apps の設定

ロジックアプリをプラグインとしてインポートするには、まず、セマンティックカーネルからアクセスできるようにロジックアプリを設定する必要があります。これには、メタデータエンドポイントを有効にし、アプリケーションを Easy Auth 用に構成してから、最後に認証を含むプラグインとしてロジックアプリをインポートする必要があります。

メタデータエンドポイントを有効にする

最も簡単なセットアップのために、ロジックアプリのメタデータエンドポイントへの認証されていないアクセスを有効にすることができます。これにより、ロジックアプリをプラグインとしてセマンティックカーネルにインポートできます。初期インポートの認証を処理するカスタム HTTP クライアントを作成する必要はありません。

以下のhost.jsonファイルでは、2 つの認証されていないエンドポイントが作成されます。これを azure portal で行うには、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 に既に慣れている (使用する 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"

セマンティックカーネルをプラグインとして Logic Apps を使用する

ロジックアプリをセキュリティで保護し、メタデータエンドポイントを有効にしたので、すべてのハードパーツを完了しました。 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 エージェントでプラグインを使用する方法を学習できるようになりました。プラグインに追加した関数の種類に応じて、従う必要があるパターンが異なります。取得関数については、取得関数の使用に関する記事参照してください。タスク自動化関数については、タスク自動化関数の使用に関する記事参照してください。

取得関数の使用について説明します

次の方法で共有

Logic Apps をプラグインとして追加する

Logic Apps をプラグインとしてインポートする

セマンティックカーネル用の Logic Apps の設定

メタデータエンドポイントを有効にする

Easy Auth 用にアプリケーションを構成する

セマンティックカーネルをプラグインとして Logic Apps を使用する

次のステップ

その他のリソース

次の方法で共有

Logic Apps をプラグインとして追加する

Logic Apps をプラグインとしてインポートする

セマンティック カーネル用の Logic Apps の設定

メタデータ エンドポイントを有効にする

Easy Auth 用にアプリケーションを構成する

セマンティック カーネルをプラグインとして Logic Apps を使用する

次のステップ

その他のリソース

セマンティックカーネル用の Logic Apps の設定

メタデータエンドポイントを有効にする

セマンティックカーネルをプラグインとして Logic Apps を使用する