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

[アーティクル]
06/27/2024

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

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

重要

クライアントプラグインの開発は、統合開発者エクスペリエンスでのみ可能です。財務と運用アプリの統合管理者エクスペリエンスから統合開発者環境を作成する方法の詳細については、チュートリアル: 財務と運用プロビジョニングアプリをインストールするを参照してください。
クライアントプラグインを使用して財務と運用アプリの Copilot を拡張する機能は、財務と運用バージョン 10.0.40 以降で使用できます。財務と運用アプリのリリーススケジュールの詳細については、サービス更新の可用性を参照してください。
この機能はプレビュー機能です。これには、プレビュー補足利用規約が適用されます。プレビュー機能は、運用上の用途のためのものではなく、機能が制限されている場合があります。これらの機能は、早期アクセスを使用してフィードバックを提供できるよう、公式リリースより前に使用することができます。プレビューリリースの詳細については、1 つのバージョンのサービス更新に関するよく寄せられる質問を参照してください。

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

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

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

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

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

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

データ契約

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

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

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

パラメーター

パラメーター	型	Description
IdentifierName	文字列	プラグインアクションの識別子。この識別子は、Copilot Studio から財務と運用アプリに送信されるイベントに対して定義され、財務と運用アプリから Copilot Studio に出力パラメーターを返します。 identifierStr コンパイル時関数を使用して識別子を文字列に変換します。識別子名の先頭には接頭語 `MS.PA` が付く必要があります
氏名	文字列	アクションの内容を示す名前。
Description	文字列	アクションの自然言語での説明。 Copilot は現在このパラメーターを使用していませんが、定義で提供する必要があります。今後のリリースでは、このパラメーターを使用して、アクションをユーザーの意図にリンクすることで、プラグインのオーケストレーションを強化します。
MenuItemName	文字列	アクションに関連付けられているメニュー項目。このメニュー項目のアクセス許可によって、クライアントアクションを呼び出すユーザーのアクセス許可を決定します。既存のメニュー項目を使用するか、アクションに関連付ける新しいメニュー項目を作成できます。
MenuItemType	securingMenuItemType	`MenuItemName` パラメーターで定義されるメニュー項目の MenuItemType 値。

例

[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 を使用します。

パラメーター	型	Description
runtimeAction	ClassName	ユーザーが使用できるランタイムアクションの一覧に追加する、ランタイムアクションのクラス名。
removeOnFormChange	ブール型	この値が true の場合、ユーザーが別のフォームに移動するとアクションの登録が解除されます。 false の場合、アクションは登録されたままです。
context	オブジェクト	(オプション) アクションの実行時にアクションに渡すコンテキストオブジェクトインスタンス。

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

パラメーター	型	Description
runtimeAction	ClassName	ユーザーの Copilot で使用できるランタイムアクションの一覧から削除する、ランタイムアクションのクラス名。

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

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

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

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

パラメーター	型	Description
説明	文字列	パラメーターの自然言語での説明。 Copilot は現在このパラメーターを使用していませんが、定義で提供する必要があります。今後のリリースでは、このパラメーターを使用して、パラメーターをユーザーの自然言語プロンプトにリンクすることで、プラグインのオーケストレーションを強化します。
isRequired	ブール型	パラメーターに値を定義する必要かどうかを決定する値。

各パラメーターに、変数を取得および設定するアクセサーメソッドを定義する必要もあります。次の例では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 関数を使用します。

パラメーター	型	Description
説明	文字列	パラメーターの自然言語での説明。 Copilot は現在このパラメーターを使用していませんが、定義で提供する必要があります。今後のリリースでは、このパラメーターを使用して、パラメーターをユーザーの自然言語プロンプトにリンクすることで、プラグインのオーケストレーションを強化します。

出力パラメーターごとに、アクセサーメソッドを定義する必要があります。次の例は、クライアントアクション用の 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 値を解析することができます。

注意

今後のリリースでは、生成 AI を使用してクライアントプラグインを呼び出すようになるため、アクションを呼び出して出力パラメーターを受け取るトピックを作成する必要がなくなります。

次の方法で共有

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

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

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

データ契約

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

パラメーター

例

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

グローバルアクション

フォームアクション

ランタイムアクション

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

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

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

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

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

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

フィードバック

その他のリソース

次の方法で共有

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

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

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

データ契約

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

パラメーター

例

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

グローバル アクション

フォーム アクション

ランタイム アクション

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

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

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

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

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

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

フィードバック

その他のリソース

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

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

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

グローバルアクション

フォームアクション

ランタイムアクション

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

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

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