Intégrer des agents personnalisés avec l’Agent d’actions recommandées

L’agent des actions recommandées dans Dynamics 365 Sales présente des recommandations prioritaires pour les opportunités. Il fournit un pipeline de notation partagé, des contrats de données et une synchronisation bidirectionnelle des états afin que tout agent personnalisé puisse faire apparaître des recommandations aux côtés des agents first-party.

Cet article décrit l’architecture, les composants clés, les contrats de données et le flux d’intégration utilisés lorsqu’un agent personnalisé s’intègre à l’Agent d’Actions Recommandées. Il fournit les connaissances fondamentales nécessaires à la mise en œuvre d’une intégration.

Prerequisites

• La solution NextBestActionAgent déployée auprès de l’organisation cible. Pour plus d’informations, voir Importer un agent dans un environnement cible.

• Le vendeur a des rôles de sécurité Dataverse appropriés comme décrit dans les autorisations requises pour les rôles de sécurité personnalisés.

• Une chaîne SourceAgentId stable et unique pour l’agent personnalisé. Pour plus d’informations, consultez Ajouter des agents de customisation pour les actions recommandées.

• Les autorisations suivantes sont requises pour pousser les actions recommandées :

  Table	Privilèges requis	Scope
  msdyn_rawactioncatalogue	Lire, Écrire, Ajouter et Ajouter à	Global
  msdyn_prioritizedactioncatalogue	Lecture, Écriture, Ajout et Ajout à	Global
  msdyn_recommendedactionsourceagentconfig	Lire	Global
  msdyn_salesagentprofile	Lire	Global

Architecture d’intégration

L’intégration de l’Agent d’Actions Recommandées utilise un pipeline de traitement qui ingère les actions brutes des agents sources, leur attribue un score à l’aide de un moteur de notation UICE (Urgence, Impact, Confiance, Effort), et affiche les résultats classés par ordre de priorité dans le carrousel du vendeur.

Le pipeline de traitement fonctionne comme suit :

1. L’agent des douanes détecte un insight exploitable (par exemple, un risque de transaction, un accord bloqué ou un acteur manquant).
2. L’agent personnalisé appelle l’API msdyn_PushActionDataToRecommendedActionAgent personnalisée pour pousser l’action.
3. L’action est stockée dans msdyn_rawactioncatalogue (table d’entrée).
4. Pour chaque action, le Scoring Engine :
   • Récupère les signaux d’entité à partir de Dataverse.
   • Récupère les données de hiérarchisation spécifiques à l’agent à partir du catalogue d’actions.
   • Appelle le LLM pour évaluer l’action sur les dimensions UICE (Urgence, Impact, Confiance, Effort).
   • Applique les règles de plancher et plafond.
   • Calcule le score de priorité final en utilisant GetRecommendedActionAgentResponse.
5. L’action notée est insérée dans msdyn_prioritizedactioncatalogue (table de sortie).
6. L’Agent Actions Recommandées Carrousel récupère les actions notées et affiche les cartes.

Composants clés

L’intégration repose sur les tables et API Dataverse suivantes.

Inscription de l’agent

Enregistrez les agents personnalisés auprès de l’agent Actions recommandées afin que la plateforme reconnaisse et récupère leurs actions. Pour plus d’informations sur l’enregistrement des agents, consultez Ajouter des agents personnalisés pour les actions recommandées.

Lorsque vous enregistrez un agent, cela crée une entrée dans msdyn_recommendedactionsourceagentconfig. L’unique SourceAgentId identifie l’entrée de l’agent douanier.

Configuration de l’agent

La msdyn_recommendedactionsourceagentconfig table contient la configuration par agent qui régit la manière dont l’Agent des Actions Recommandées interprète les actions d’un agent. Les deux champs les plus importants à peupler sont msdyn_internalprioritizationinstruction et msdyn_syncactionexecutionstateapiconfig.

Vous pouvez appliquer la configuration soit en mettant à jour manuellement l’enregistrement de table, soit en appelant l’API UpsertRecommendationAgentConfigRequestpersonnalisée .

Schéma de UpsertRecommendationAgentConfigRequest

L’exemple suivant montre les champs de configuration disponibles dans le schéma.

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

Instruction de hiérarchisation interne

L’instruction de priorisation interne contient des métadonnées de signal spécifiques à chaque agent qui indiquent au moteur de notation comment interpréter les champs de données de priorisation d’un agent. C’est un objet JSON avec un tableau de haut niveau signals . Chaque signal est désérialisé en AgentSignalInstructionConfig avec les champs suivants :

Exemple de blocage de signaux :

{
  "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" }
    }
  ]
}

Configuration de l’API pour l’état d’exécution de l’action de synchronisation

La configuration de l’API d’état d’exécution de l’action de synchronisation est un objet JSON qui spécifie le nom d’API personnalisé que l’agent des actions recommandées appelle lorsqu’un vendeur effectue une action sur une carte (par exemple, la marque comme terminée ou non pertinente). Cette API définit l’état de l’action dans l’agent personnalisé source.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

Contrat de notification push

Les agents personnalisés déclenchent des actions à l’aide de l’API personnalisée msdyn_PushActionDataToRecommendedActionAgent. L’API est appelée à chaque fois que l’agent génère ou met à jour une action pour une entité cible.

Paramètres de la demande

Exemple : appel de plugin 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"];

Contrat de charge utile Action UI

Le msdyn_ActionUIPayload champ contient une charge utile JSON qui contrôle l’apparition d’une carte d’action dans le carrousel des Agents d’Actions Recommandées.

{
  "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\"}"
}

Contrat de hiérarchisation des données

Le msdyn_prioritizationdata champ permet à un agent de transmettre des signaux spécifiques à chaque agent qui influencent la façon dont le moteur de notation UICE priorise une action.

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

Le moteur de notation lit ces signaux aux côtés des signaux au niveau de l’entité (valeur de l’accord, étape, concurrents, etc.). La configuration msdyn_internalprioritizationinstruction de l’agent indique au LLM comment interpréter chaque signal, et le moteur d’évaluation combine tous les signaux pour former l’invite d’évaluation UICE.

Gestion des versions des actions et invalidation

Lorsqu’un agent met à jour les données d’une action précédemment poussée, il crée un nouvel enregistrement avec la même msdyn_ActionId en appelant msdyn_PushActionDataToRecommendedActionAgent à nouveau. Le système crée une nouvelle ligne dans msdyn_rawactioncatalogue avec le même msdyn_actionid mais un nouveau msdyn_rawactioncatalogueid. L’Agent d’Actions Recommandées continue d’afficher l’ancienne version jusqu’à ce qu’il traite la nouvelle.

Pour invalider une action (par exemple, lorsqu’un risque est résolu), l’agent appelle l’API personnalisée msdyn_RAAgent_RemoveActionsV2 avec le actionId. Cette action marque tous msdyn_rawactioncatalogue les enregistrements de cette action comme inactifs, et la carte disparaît du carrousel.

Synchronisation d’état bidirectionnelle

L’état de l’action se synchronise à la fois dans le carrousel de l’agent d’actions recommandées et votre agent personnalisé afin de garantir que les vendeurs voient des informations cohérentes, peu importe où ils agissent sur une action.
Actions recommandées Agent → agent des douanes (le vendeur agit dans le carrousel) : Lorsqu’un vendeur marque une action comme Accomplie ou Annulée dans le carrousel :

1. L’agent Actions recommandées met à jour msdyn_actionuistatus dans msdyn_prioritizedactioncatalogue.
2. L’agent des actions recommandées lit le msdyn_syncactionexecutionstateapiconfig à partir de la configuration de l’agent.
3. L’Agent d’Actions Recommandées appelle l’API personnalisée de l’agent avec :

L’agent doit implémenter une API personnalisée qui accepte ces deux paramètres et met à jour l’état de l’action dans son propre magasin de données.

Agent personnalisé → Agent des actions recommandées (le vendeur agit dans l’interface utilisateur de l’agent) : Lorsqu’un vendeur intervient sur une action dans la propre interface utilisateur de l’agent (par exemple, la marque comme atténuée sur une page d’agent personnalisé), l’agent synchronise cet état avec l’agent des actions recommandées en appelant msdyn_SyncActionExecutionStateFromAgent. Cette action met à jour l’état dans la table de sortie de l’Agent Actions recommandées, le masquant du carrousel.

Tests et validation

Après configuration et implémentation, validez le flux de bout en bout en effectuant les vérifications suivantes.

Vérifier la configuration de l’agent :

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

Poussez une action de test en appelant msdyn_PushActionDataToRecommendedActionAgent et vérifiez que c’est msdyn_IsSuccess vrai, et qu’un nouvel enregistrement apparaît dans msdyn_rawactioncatalogue.

Déclenchez le calcul du score à la demande en appelant msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration (au lieu d’attendre le temporisateur de 4 heures).

Vérifier la sortie évaluée :

    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

Valeurs attendues :

• msdyn_actionscore est rempli avec une valeur dans la plage 0 à 10.
• msdyn_hascrossedfloor est faux (l’action est au-dessus du plancher et s’affiche dans le carrousel).
• msdyn_actionuistatus est 1 (Actif).
• msdyn_scoredetails contient l’explication générée par LLM.

Vérifiez l’affichage du carrousel en ouvrant un formulaire d’Opportunité dans Dynamics 365 Sales et en vérifiant la section Actions suggérées. Vérifiez la synchronisation d’état en rejetant une action dans le carrousel (l’API de synchronisation doit être appelée avec state = "Dismissed") et en marquant une action dans l’interface de l’agent (l’enregistrement de la table de sortie doit refléter la mise à jour msdyn_actionuistatus).

Exemple : Agent d’opportunités de vente

L’Agent d’Opportunité de Vente est le premier agent intégré à l’Agent des Actions Recommandées, et son intégration sert de référence à l’implémentation.

Valeurs de configuration des agents :

Lorsque les recherches de Sales Opportunity Agent sont terminées et qu’elles identifient des risques liés à l’opportunité, DealRiskToNBAService transmet chaque risque sous forme d’action distincte :

Comportement de synchronisation d’état :

• Agent d’opportunités de vente → agent d’actions recommandées : Lorsqu’un vendeur marque un risque comme réalisé sur la page de recherche, l’agent appelle msdyn_SyncActionExecutionStateFromAgent.
• Actions recommandées Agent → Agent d’opportunités de vente : Lorsqu’un vendeur rejette une carte dans le carrousel, l’Agent des Actions Recommandées appelle ora_UpdatedActionStateFromRAAgent (configuré dans la configuration de l’agent).

Informations associées

• Configurer l’agent des actions recommandées
• Vue d’ensemble des actions recommandées