財務と運用アプリで Copilot 用クライアント プラグインを作成する

クライアント プラグイン、またはクライアント アクションは、クライアント コードを呼び出す Microsoft Copilot プラグインです。クライアント エクスペリエンスのコンテキストではユーザー財務と運用アプリ。 開発者は、X++ コード ベースの機能、操作、およびビジネス ロジックを、ユーザーが Copilot インターフェイスを使用して自然言語で呼び出して通信できるアクションに変換するプラグインを定義できます。 たとえば、クライアント プラグインを使用すると、財務と運用アプリの Copilot を拡張して、ユーザーがアプリケーション アクションの実行、フォーム値の入力、アプリケーションからの計算やビジネス ロジックを必要とする質問を行う自然な言語のプロンプトを入力することができます。

この記事では、クライアント プラグインのコンポーネントとオプションの詳細についても説明します。 クライアント プラグインの作成方法を説明するステップ バイ ステップのチュートリアルについては、チュートリアル: 財務と運用アプリで Copilot 用クライアント プラグインを作成するを参照してください。

クライアント プラグインのアーキテクチャ

クライアント プラグインの開発には、次の 2 つの主要なコンポーネントが含まれます。

• プラグインは、Copilot Studio の財務と運用の Copilot チャットボットを使用して作成する必要があります。 プラグインはユーザーの自然な言語プロンプトを理解し、ユーザーの Copilot プロンプトに基づいてプラグインのオーケストレーションと実行を管理します。 実行時に、プラグインは財務と運用クライアントにイベントを送信します。
• メソッドは X++ で作成する必要があります。 このメソッドが Copilot Studio に呼び出され、定義されたクライアント コードが実行されます。 Copilot Studio がイベントを財務と運用アプリに送信すると、クラスが呼び出され、クライアント操作が実行されます。

プラグインのアーキテクチャと実行の詳細については、財務と運用の Copilot のアーキテクチャを参照してください。

X++ でのアクションの定義

X++ で、Copilot Studio でメソッドを呼び出すと呼び出されてコードを実行できるクラスを作成する必要があります。 新しいクラスは、SysCopilotChatAction クラスを拡張するサブクラスである必要があります。

データ契約

メソッドは、データ コントラクト クラスである必要があります。 この方法で、複雑なデータ型をメソッドの入力および出力パラメーターとして渡すことができます。 その結果、パラメーターのシリアル化および逆シリアル化が Copilot Studio との通信に必要ありません 。 メソッドをデータ コントラクトとして定義するには、DataContract 属性で修飾します。 X++ でデータ コントラクトを実装する方法の詳細については、X++ でのデータ コントラクトの使用を参照してください。

アクション定義を提供する

アクションを定義するには、SysCopilotChatActionDefinition関数でクラスを修飾します。

パラメーター

例

[SysCopilotChatActionDefinition(
    identifierStr(MS.PA.CopilotExample.ClientNavigate),
    'Navigate',
    'Navigates to or opens a defined form in the application client',
    menuItemActionStr(SysCopilotChatCustomNavigateAction), MenuItemType::Action)]

アクション タイプを定義する

アクション タイプは、Copilot に対するアクションの使用を制御するためのメカニズムです。 Copilot を使用すると、ユーザーが実行できるアクションを使用可能にするコンテキストを定義できます。

グローバル アクション

グローバル アクションには特定のアプリケーション コンテキストはないので、Copilot チャット ウィンドウが開いているときはいつでも、ユーザーがアプリケーション任意の形式で実行できます。 クライアント アクションをグローバルとして定義するには、メソッドを SysCopilotChatGlobalAction 属性で修飾します。

フォーム アクション

フォーム アクションは、特定のフォームのコンテキストでのみ適用できます。 たとえば、請求書レコードの承認や、特定のフォームで使用できるデータに対する計算の実行などのフォーム アクションを呼び出すことができます。

アクションが使用できる 1 つまたは複数のフォームを定義するには、1 つ以上の ExportMetadata 属性でメソッドを修飾します。 アクションは、アクションに対して定義されているフォームのいずれかを使用している場合のみ、Copilot プラグインのオーケストレーションで考慮されます。 それらのフォームのいずれかを使用していない場合、オーケストレーションではアクションを無視します。

次の例では、Batch フォームと BatchGroup フォームで使用可能なフォーム アクションとして、アクションを定義します。

[ExportMetadata(formStr(BatchGroup), identifierStr(FormName))]
[ExportMetadata(formStr(Batch), identifierStr(FormName))]
[Export(identifierstr(Microsoft.Dynamics.AX.Application.SysCopilotChatAction))]

ランタイム アクション

ランタイム アクションは、開発者が使用可能なアクションの一覧に追加して、使用可能と定義すると使用できます。

使用可能なアクションの一覧にクライアント アクションを追加するには、SysCopilotChatAction::addToCopilotRuntimeActions を使用します。

ユーザーの Copilot で使用できるアクションの一覧からランタイム アクションを削除するには、 SysCopilotChatAction::removeFromCopilotRuntimeActions を使用します。

入力パラメーターを定義する

入力および出力パラメーターは、Copilot オーケストレーションと財務と運用クライアントの間で値を渡す場合に使用されます。

入力パラメーターは、アクションを呼び出するために Copilot Studio から財務と運用アプリに送信されるイベント ペイロードで受信されるアクションに定義されます。 データ コントラクトのデータ メンバーとして定義されます。

入力パラメーターのプロパティを定義するには、SysCopilotChatActionInputParameter 関数を使用します。

各パラメーターに、変数を取得および設定するアクセサー メソッドを定義する必要もあります。 次の例ではmenuItemName、クライアントをこのパラメーターに定義されたフォームに移動させるナビゲーション アクション用の入力パラメーターの定義を示します。

[DataMember('menuItemName'),
SysCopilotChatActionInputParameter('The name of the menu for the form to launch', true)]
internal MenuItemName parmMenuItemName(MenuItemName _menuItemName = menuItemName)
{
    menuItemName = _menuItemName;
    return menuItemName;
}

出力パラメーターを定義する

出力パラメーターは、財務と運用アプリから Copilot Studio に応答としてイベント ペイロードで送信されるアクションに定義されます。 入力パラメーターと同様に、出力パラメーターはデータ コントラクトのデータ メンバーとして定義されます。 たとえば、クライアント アクションがフォーム データに基づく計算を実行した場合、出力パラメーターが計算の結果になる場合があります。 その結果は、応答として Copilot に送信できます。

出力パラメーターのプロパティを定義するには、SysCopilotChatActionOutputParameter 関数を使用します。

出力パラメーターごとに、アクセサー メソッドを定義する必要があります。 次の例は、クライアント アクション用の navResponse 出力パラメーターの定義を示しています。 このパラメーターは、Copilot に返されるアクション応答で、チャット セッションでユーザーに表示できます。

[DataMember('navResponse'),
SysCopilotChatActionOutputParameter('The response from the navigation, whether an error or successful navigation')]
public str parmNavResponse(str _navResponse = navResponse)
{
    navResponse = _navResponse;
    return navResponse;
}

クライアント アクションの実行を定義する

アクションに対して実行するビジネス ロジックを定義し、出力パラメーターの値を設定するには、SysCopilotChatActionDefinitionAttribute クラスのインスタンスを作成します。 executeAction を呼び出すと、出力パラメーターが再シリアル化され、イベント ペイロードで Copilot Studio に返されます。

たとえば、Copilot アクションを使用してクライアントのフォームに移動する場合は、次のコードを使用してナビゲーションを実行し、Copilot に送信する出力パラメーターとして設定するメッセージを定義できます。

public void executeAction(SysCopilotChatActionDefinitionAttribute _actionDefinition, Object _context)
{
    super(_actionDefinition, _context);

    if (this.parmMenuItemName())
    {
        // Navigate
        MenuFunction::runClient(this.parmMenuItemName(), MenuItemType::Display, false, new Args());
        this.parmNavResponse("You were successfully navigated to the " + menuItemName + " form.");
    }
    else
    {
        throw Error(Error::wrongUseOfFunction(funcName()));
        this.parmNavResponse("There was an error navigating you to the " + menuItemName + " form. See the action menu for more information.");
    }
}

Copilot Studio でのトピックを作成する

データ アクションを呼び出す

ユーザーがクライアント アクションを呼び出す意図で Copilot チャット ウィンドウにプロンプトを入力すると、ユーザーの意図に基づいてアクションのオーケストレーションとオーケストレーションを管理できるように、プロンプトが Copilot Studio に送信されます。 Copilot Studio で、プロンプトに対して呼び出すプラグインを指定します。 クライアント アクションの場合は、呼び出す X++ アクションをプラグインで定義する必要があります。 次に、Copilot Studio でイベントを財務と運用アプリに送信し、アクションを呼び出します。 イベント ペイロードで、X++ クラスの入力パラメーターの値を JAVAScript Object Notation (JAVA) オブジェクトとして定義します。

Copilot Studio のトピックまたはプラグインで、X++ に送信するイベントとイベント ペイロードを定義するイベント活動ノードを作成し、クライアント アクションの入力パラメーターとして含めるイベントのデータを作成します。 イベント活動の名前プロパティの値は、X++ クラスの IdentifierName SysCopilotChatActionDefinition 属性で定義されているパラメーターの値です。 イベント活動の値プロパティの値は、X++ クラスに送信する必要がある入力パラメーターの値を定義する JSON 文字列です。

クライアント アクションの出力パラメーターを受け取る

クライアント アクションに、Copilot のユーザーに対する自然な言語応答として返す出力パラメーター、または別のアクションを続行する出力パラメーターが含まれる場合があります。 クライアント アクションを X++ で実行すると、出力パラメーターがイベントとして Copilot Studio に送信されます。

Copilot Studio では、X++ クラスから応答を受け取る別のトピックを作成する必要があります。 イベント受信トリガーを含むトピックを作成します。 トリガーのイベント名プロパティの値は、X++ クラスの IdentifierName SysCopilotChatActionDefinition 属性で定義されているパラメーターの値です。 System.Activity.Text 変数は、JSON 文字列としてイベント ペイロードに設定されます。 値の解析ノードをトピックに追加して、クライアント アクションの出力パラメーターの値のために System.Activity.Text 値を解析することができます。