カスタムエージェントを推奨アクションエージェントと統合する

Dynamics 365 SalesのRecommended Actions Agentは、機会の優先順位付け推奨を担当しました。 共有スコアリングパイプライン、データ契約、双方向の状態同期を提供し、任意のカスタムエージェントがファーストパーティエージェントと並行して推奨値を表示できるようにします。

この記事では、カスタムエージェントが推奨アクションエージェントと統合する際に使われるアーキテクチャ、主要コンポーネント、データ契約、統合フローについて説明します。 統合を実装するために必要な基礎知識を提供します。

前提条件

• NextBestActionAgent ソリューションが対象組織に展開されました。 詳細については、「 エージェントをターゲット環境にインポートする」をご覧ください。

• 販売者は、カスタム セキュリティ ロールに必要なアクセス許可に記載されている適切なDataverse セキュリティ ロールを持っています。

• カスタムエージェント用の安定で一意な SourceAgentId 文字列。 詳細については、「推奨されるアクション用のカスタム エージェントを追加する」を参照してください。

• 推奨アクションをプッシュするためには以下の権限が必要です:

  テーブル	必要な特権	Scope
  msdyn_rawactioncatalogue	読む、書く、付け加え、付録を	グローバル
  msdyn_prioritizedactioncatalogue	読み取り、書き込み、追記、および追記先の指定	グローバル
  msdyn_recommendedactionsourceagentconfig	読む	グローバル
  msdyn_salesagentprofile	読む	グローバル

統合アーキテクチャ

Recommended Actions Agentの統合は、ソースエージェントから生のアクションを取り込み、 UICE(緊急性、影響、信頼度、努力)スコアリングエンジンでスコアリングし、優先順位付けの結果をセラーカルーセルに表示する処理パイプラインを使用します。

処理パイプラインの動作は以下の通りです:

1. カスタムエージェントは 、取引リスク、停滞した取引、欠落したステークホルダーなど、実行可能なインサイトを検出します。
2. カスタムエージェントはmsdyn_PushActionDataToRecommendedActionAgentカスタムAPIを呼び出してアクションをプッシュします。
3. アクションは msdyn_rawactioncatalogue (入力テーブル)に保存されます。
4. 各アクションごとに、 スコアリングエンジンは以下の通りです:
   • Dataverse からエンティティ シグナルを取得します。
   • アクションカタログからエージェント固有の優先順位付けデータを取得します。
   • LLMを呼び出し、アクションをUICE（緊急性、影響、確信度、労力）の各次元でスコアリングします。
   • 最低限と上限のルールを適用します。
   • GetRecommendedActionAgentResponseを用いて最終優先度スコアを計算します。
5. 得点されたアクションは msdyn_prioritizedactioncatalogue (出力表)に挿入されます。
6. 推奨アクション エージェント・カルーセルは得点されたアクションを取り出し、カードをレンダリングします。

主なコンポーネント

この統合は以下のDataverseテーブルとAPIに依存しています。

エージェントの登録

カスタムエージェントをRecommended Actions Agentに登録し、プラットフォームがそのアクションを認識し取得できるようにします。 エージェントの登録について詳しくは、推奨されるアクション用のカスタム エージェントの追加を参照してください。

エージェントを登録すると、 msdyn_recommendedactionsourceagentconfigにエントリーが作成されます。 一意の SourceAgentId はカスタムエージェントのエントリを識別します。

エージェントの構成

msdyn_recommendedactionsourceagentconfigテーブルには、推奨アクションエージェントがエージェントの行動をどのように解釈するかを制御するエージェントごとの構成が収められています。 入力する必要がある最も重要な2つの項目は、msdyn_internalprioritizationinstructionとmsdyn_syncactionexecutionstateapiconfigです。

設定はテーブルレコードを手動で更新するか、カスタムAPI UpsertRecommendationAgentConfigRequest呼び出すことで適用できます。

UpsertRecommendationAgentConfigRequest スキーマ

以下の例はスキーマ内で利用可能な構成フィールドを示しています。

{
  "agentName": "YourAgentName",
  "agentType": "CustomAgent",
  "isRecommendedActionAgentEnabled": true,
  "salesAgentProfileId": "<SourceAgentId that was configured>",
  "agentImpactMapping": "[]",
  "internalPrioritizationInstruction": "{\"signals\":[...]}",
  "syncActionExecutionStateApiConfig": "{\"syncactionuistatusapiname\":\"your_SyncBackCustomApiName\"}",
  "description": "Brief description of your agent"
}

内部の優先順位付け命令

内部優先順位付け命令には、スコアリングエンジンがエージェントの優先順位データフィールドをどのように解釈するかを示すエージェント固有の信号メタデータが含まれています。 これはJSONオブジェクトで、トップレベルに signals 配列があります。 各信号は、以下のフィールドを持つAgentSignalInstructionConfigにデシリアライズされます:

信号例ブロック:

{
  "signals": [
    {
      "name": "risk_type",
      "type": "string",
      "source": "action_data",
      "dimension_influence": { "urgency": "moderate", "confidence": "weak" },
      "interpretation": "Risk category code assigned by the source agent (e.g. 8 = Missing BANT Info). Used for pre-filter rule matching and prompt context.",
      "reliability": "high",
      "required": false,
      "fetch_info": { "fetch_type": "action_data", "crm_field": "riskType" }
    },
    {
      "name": "risk_label",
      "type": "string",
      "source": "action_data",
      "dimension_influence": { "urgency": "weak", "confidence": "weak" },
      "interpretation": "Human-readable risk name from the source agent (e.g. 'Missing BANT Info', 'Stalled Pipeline'). Useful for prompt context and seller explanation.",
      "reliability": "high",
      "required": false,
      "fetch_info": { "fetch_type": "action_data", "crm_field": "risk" }
    }
  ]
}

同期アクション実行状態APIの設定

同期アクション実行状態API設定は、販売者がカードに対応した際に推奨アクションエージェントが呼び出すカスタムAPI名を指定するJSONオブジェクトです(例えば、カードを完了または無関係にマークするなど)。 この API は、ソース カスタム エージェントのアクションの状態を設定します。

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

アクションプッシュ契約

カスタムエージェントは msdyn_PushActionDataToRecommendedActionAgent カスタムAPIを使ってアクションをプッシュします。 エージェントがターゲットエンティティのアクションを生成または更新するたびにAPIが呼び出されます。

要求パラメーター

例:C#プラグイン呼び出し

var request = new OrganizationRequest("msdyn_PushActionDataToRecommendedActionAgent")
{
    ["msdyn_ActionId"] = $"DealRisk_{opportunityId}_{riskType}",
    ["msdyn_SourceAgentId"] = "DealClosingAgent",
    ["msdyn_TargetEntityId"] = opportunityId, // Guid
    ["msdyn_TargetEntityTypeName"] = "opportunity",
    ["msdyn_ActionReason"] = "Customer has not responded in 14 days, deal is at risk of stalling",

    ["msdyn_ActionUIPayload"] = JsonConvert.SerializeObject(new
    {
        version = "1.0",
        payload = new
        {
            header = "Follow up with Contoso",
            description = "No customer response in 14 days. Deal may stall without re-engagement.",
            oncardClickActionType = "Navigate",
            oncardClickActionTypeParameters =
                "{etn=\"opportunity\", id=\"aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb\", pagetype=\"entityrecord\"}"
        }
    }),

    ["msdyn_ActionPrioritizationData"] = JsonConvert.SerializeObject(new
    {
        riskType = "14",
        risk = "low"
    })
};

var response = orgService.Execute(request);

bool success = (bool)response["msdyn_IsSuccess"];

アクションUIペイロード契約

msdyn_ActionUIPayloadフィールドには、アクションカードが推奨アクションエージェントのカルーセルでどのように表示されるかを制御するJSONペイロードが含まれています。

{
  "version": 1.0,
  "header": "Follow up with Contoso on pricing proposal",
  "description": "Stakeholder engagement has dropped. The customer expressed interest in the enterprise tier but hasn't responded to the last proposal sent 10 days ago.",
  "oncardClickActionType": "Navigate",
  "oncardClickActionTypeParameters": "{\"etn\":\"opportunity\",\"id\":\"<guid>\",\"pagetype\":\"entityrecord\"}",
  "onctaClickActionType": "Navigate",
  "onctaClickActionTypeParameters": "{\"etn\":\"opportunity\",\"id\":\"<guid>\",\"pagetype\":\"entityrecord\"}"
}

優先順位付けデータ契約

msdyn_prioritizationdataフィールドはエージェントがエージェント固有の信号を渡し、それがUICEスコアリングエンジンのアクションの優先順位付けに影響を与えることを可能にします。

[
  { "signalName": "risk", "value": "low" },
  { "signalName": "riskType", "value": "4" }
]

スコアリングエンジンはこれらのシグナルをエンティティレベルのシグナル(ディールバリュー、ステージ、競合他社など)と併せて読み取ります。 エージェント設定内の msdyn_internalprioritizationinstruction はLLMに各信号の解釈方法を伝え、スコアリングエンジンはすべての信号をUICEスコアリングプロンプトに統合します。

アクションのバージョン設定と無効化

エージェントが以前にプッシュされたアクションのデータを更新すると、同じ msdyn_ActionId で新しいレコードが作成され、再度 msdyn_PushActionDataToRecommendedActionAgent を呼び出します。 システムは、同じmsdyn_rawactioncatalogueと新しいmsdyn_actionidを持つ新しい行をmsdyn_rawactioncatalogueidに作成します。 推奨アクションエージェントは新しいバージョンを処理するまで古いバージョンを表示し続けます。

アクションを無効化する(例えばリスクが解決された場合)には、エージェントはactionIdを含むmsdyn_RAAgent_RemoveActionsV2カスタムAPIを呼び出します。 このアクションはそのアクションに関するすべての記録 msdyn_rawactioncatalogue 非アクティブとマークし、カードはカルーセルから消えます。

双方向状態同期

アクションステートは推奨アクションエージェントのカルーセルとカスタムエージェントの両方で同期し、どこで行動しても売主が一貫した情報を得られるようにします。
推奨行動 エージェント → カスタムエージェント(売り手がカルーセル内で行動): 売り手がカルーセルでアクションを 完了 または 却下 とマークした場合:

1. 推奨アクション エージェントは、msdyn_actionuistatus 内の msdyn_prioritizedactioncatalogue を更新します。
2. 推奨アクションエージェントはエージェント設定から msdyn_syncactionexecutionstateapiconfig を読み取ります。
3. 推奨アクションエージェントは以下の方法でエージェントのカスタムAPIを呼び出します:

エージェントはこれら2つのパラメータを受け入れ、自身のデータストアでアクション状態を更新するカスタムAPIを実装しなければなりません。

カスタムエージェント→推奨アクションエージェント(売り手がエージェントのUIで行動): セラーがエージェント自身のUIでアクションを実行した場合(例えばカスタムエージェントページで緩和措置としてマークした場合)、エージェントは msdyn_SyncActionExecutionStateFromAgentを呼び出してその状態を推奨アクションエージェントに同期させます。 このアクションにより、推奨されるアクション エージェントの出力テーブルの状態が更新され、カルーセルから非表示になります。

テストと検証

設定と実装の後、以下のチェックを行いエンドツーエンドのフローを検証します。

エージェント設定の確認:

GET [org-url]/api/data/v9.2/msdyn_recommendedactionsourceagentconfigs
?$filter=msdyn_agentname eq 'YourAgentName'
&$select=msdyn_agentname,msdyn_agentimpactmapping,msdyn_internalprioritizationinstruction,msdyn_syncactionexecutionstateapiconfig

msdyn_PushActionDataToRecommendedActionAgentを呼び出してテストアクションをプッシュし、msdyn_IsSuccessが真であることを確認し、新しいレコードがmsdyn_rawactioncatalogueに現れます。

4時間タイマーを待つ代わりに msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration に電話してオンデマンドでスコアリングをトリガーします。

スコア付き出力を検証:

    GET [org-url]/api/data/v9.2/msdyn_prioritizedactioncatalogues
    ?$filter=msdyn_actionid eq 'your-action-id'
    &$select=msdyn_actionid,msdyn_actionscore,msdyn_actionuipayload,msdyn_hascrossedceiling,msdyn_hascrossedfloor,msdyn_actionuistatus,msdyn_scoredetails

想定される値:

• msdyn_actionscore は、0 ~ 10 の範囲の値で設定されます。
• msdyn_hascrossedfloor は false です（アクションは floor より上にあり、カルーセルに表示されます）。
• msdyn_actionuistatus は1(アクティブ)です。
• msdyn_scoredetails には、LLM で生成された説明が含まれています。

Dynamics 365 Salesのオポチュニティフォームを開き、「推奨アクション」セクションをチェックすることでカルーセル表示を確認してください。 状態同期は、カルーセルでアクションを終了(同期バックAPIは state = "Dismissed"で呼び出す必要があります)や、エージェントUIでアクションをマークすることで確認します(出力テーブルレコードは更新された msdyn_actionuistatusを反映しているはずです)。

例:営業機会エージェント

セールス・オポチュニティ・エージェントは、推奨アクション・エージェントに最初にオンボーディングされたエージェントであり、その統合がリファレンス実装として機能します。

エージェントの設定値:

営業案件エージェントの調査が完了し、取引リスクを特定すると、 DealRiskToNBAService は各リスクを個別のアクションとしてプッシュします。

状態同期の動作:

• セールスオポチュニティエージェント→推奨アクションエージェント: 売り手がリサーチページでリスクをマークすると、エージェントは msdyn_SyncActionExecutionStateFromAgentに連絡します。
• 推奨行動エージェント→セールスオポチュニティエージェント: 販売者がカルーセルでカードを破ると、推奨アクションエージェントが ora_UpdatedActionStateFromRAAgent (エージェント設定で設定済み)を呼び出します。

関連情報

• 推奨アクション エージェントを構成する
• 推奨されるアクションの概要