Integreer aangepaste agenten met Aanbevolen Acties Agent

De Recommended Actions Agent in Dynamics 365 Sales geeft prioriteit aan aanbevelingen voor kansen. Het biedt een gedeelde scorepipeline, datacontracten en bidirectionele toestandssynchronisatie, zodat elke custom agent aanbevelingen kan doen naast first-party agenten.

Dit artikel beschrijft de architectuur, belangrijke componenten, datacontracten en integratieflow die worden gebruikt wanneer een custom agent integreert met de Recommended Actions Agent. Het biedt de basiskennis die nodig is voor het implementeren van een integratie.

Prerequisites

• NextBestActionAgent-oplossing die wordt ingezet bij de doelorganisatie. Voor meer informatie, zie Een agent importeren in een doelomgeving.

• De verkoper heeft passende Dataverse-beveiligingsrollen zoals beschreven in Rechten die vereist zijn voor aangepaste beveiligingsrollen.

• Een stabiele, unieke SourceAgentId-string voor de custom agent. Voor meer informatie, zie Aangepaste agenten toevoegen voor aanbevolen acties.

• De volgende rechten zijn vereist om aanbevolen acties te pushen:

  Tabel	Vereiste bevoegdheden	Omvang
  msdyn_rawactioncatalogue	Lezen, Schrijven, Toevoegen en AppendTo	Global
  msdyn_prioritizedactioncatalogue	Lezen, Schrijven, Toevoegen en AppendTo	Global
  msdyn_recommendedactionsourceagentconfig	Read	Global
  msdyn_salesagentprofile	Read	Global

Integratiearchitectuur

De integratie van de Aanbevolen Acties Agent gebruikt een verwerkingspijplijn die ruwe acties van bronagenten opneemt, deze beoordeelt met behulp van een UICE (Urgency, Impact, Confidence, Effort) score-engine en de geprioriteerde resultaten in de verkoperscarrousel naar boven brengt.

De verwerkingspijplijn werkt als volgt:

1. De custom agent detecteert een bruikbaar inzicht (bijvoorbeeld een dealrisico, een vastgelopen deal of een ontbrekende stakeholder).
2. De custom agent roept de msdyn_PushActionDataToRecommendedActionAgent custom API aan om de actie te pushen.
3. De actie wordt opgeslagen in msdyn_rawactioncatalogue (invoertabel).
4. Voor elke actie volgt de Scoring Engine:
   • Haalt entiteitssignalen op uit Dataverse.
   • Haalt agentspecifieke prioriteitsaanduidingsgegevens op uit de actiecatalogus.
   • Roept de LLM op om de actie te beoordelen op UICE (Urgency, Impact, Confidence, Effort) dimensies.
   • Past vloer- en plafondregels toe.
   • Berekent de eindprioriteitsscore door gebruik te maken van GetRecommendedActionAgentResponse.
5. De gescorede actie wordt ingevoegd in msdyn_prioritizedactioncatalogue (outputtabel).
6. De Aanbevolen Acties Agent Carrousel haalt scorede acties op en rendert kaarten.

Belangrijke onderdelen

De integratie is afhankelijk van de volgende Dataverse-tabellen en API's.

Agentregistratie

Registreer aangepaste agenten bij de Aanbevolen Acties-agent zodat het platform hun acties herkent en ophaalt. Voor meer informatie over registrerende agenten, zie Aangepaste agenten toevoegen voor aanbevolen acties.

Wanneer je een agent registreert, wordt er een invoer in msdyn_recommendedactionsourceagentconfiggemaakt. De unieke SourceAgentId identificeert de invoer voor de custom agent.

Agentconfiguratie

De msdyn_recommendedactionsourceagentconfig tabel bevat de configuratie per agent die bepaalt hoe de Aanbevolen Acties-agent de acties van een agent interpreteert. De twee belangrijkste velden om te bevolken zijn msdyn_internalprioritizationinstruction en msdyn_syncactionexecutionstateapiconfig.

Je kunt configuratie toepassen door handmatig het tabelrecord bij te werken of door de aangepaste API UpsertRecommendationAgentConfigRequestaan te roepen.

UpsertRecommendationAgentConfigRequest schema

Het volgende voorbeeld toont de beschikbare configuratievelden in het schema.

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

Interne prioriteitstellingsinstructie

De interne prioriteringsinstructie bevat agent-specifieke signaalmetadata die de score-engine vertelt hoe de prioriteringsdatavelden van een agent moeten interpreteren. Het is een JSON-object met een array op topniveau signals . Elk signaal wordt gedeserialiseerd met AgentSignalInstructionConfig de volgende velden:

Voorbeeld van signaalblok:

{
  "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-configuratie voor het synchroniseren van de uitvoeringsstatus van acties

De sync action execution state API-configuratie is een JSON-object dat de aangepaste API-naam specificeert die de Aanbevolen Actiesagent aanroept wanneer een verkoper op een kaart handelt (bijvoorbeeld deze als compleet of irrelevant markeert). Met deze API stelt u de status van de actie in de aangepaste bronagent in.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

Actie push-contract

Custom agents pushen acties via de msdyn_PushActionDataToRecommendedActionAgent custom API. De API wordt aangeroepen telkens wanneer de agent een actie genereert of bijwerkt voor een doelentiteit.

Aanvraagparameters

Voorbeeld: C# plugin-aanroep

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"];

Action UI payloadcontract

Het msdyn_ActionUIPayload veld bevat een JSON-payload die bepaalt hoe een actiekaart verschijnt in de Recommended Actions Agent-carrousel.

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

Prioriteringsdatacontract

Het msdyn_prioritizationdata veld laat een agent agent-specifieke signalen doorgeven die bepalen hoe de UICE-scoreengine een actie prioriteert.

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

De score-engine leest deze signalen samen met entiteitsniveau-signalen (dealwaarde, stage, concurrenten, enzovoort). De msdyn_internalprioritizationinstruction agent config vertelt de LLM hoe elk signaal moet interpreteren, en de scoring engine combineert alle signalen in de UICE-scoreprompt.

Actieversieering en ongeldigverklaring

Wanneer een agent gegevens bijwerkt voor een eerder gepushte actie, maakt hij een nieuw record aan met dezelfde msdyn_ActionId door opnieuw aan te roepen msdyn_PushActionDataToRecommendedActionAgent . Het systeem maakt een nieuwe rij in msdyn_rawactioncatalogue met hetzelfde msdyn_actionid, maar een nieuwe msdyn_rawactioncatalogueid. De Aanbevolen Acties-agent blijft de oude versie tonen totdat de nieuwe wordt verwerkt.

Om een actie ongeldig te maken (bijvoorbeeld wanneer een risico is opgelost), roept de agent de msdyn_RAAgent_RemoveActionsV2 aangepaste API aan met de actionId. Deze actie markeert alle msdyn_rawactioncatalogue records voor die actie als inactief, en de kaart verdwijnt uit de carrousel.

Bidirectionele toestandssynchronisatie

De actiestatus synchroniseert zowel in de Aanbevolen Acties-agentcarrousel als in uw custom agent, zodat verkopers consistente informatie zien, ongeacht waar ze handelen tijdens een actie.
Aanbevolen Acties Agent → Custom Agent (verkoper handelt in de carrousel): Wanneer een verkoper een handeling als Voltooid of Afgewezen markeert in de carrousel:

1. Agent voor aanbevolen acties werkt de msdyn_actionuistatus bij in msdyn_prioritizedactioncatalogue.
2. Aanbevolen Acties Agent leest de msdyn_syncactionexecutionstateapiconfig uit de agentconfiguratie.
3. Aanbevolen Acties Agent roept de aangepaste API van de agent aan met:

De agent moet een aangepaste API implementeren die deze twee parameters accepteert en de actiestatus in zijn eigen datastore bijwerkt.

Custom agent → Aanbevolen Acties Agent (verkoper handelt in de gebruikersinterface van de agent): Wanneer een verkoper handelt op een actie in de eigen UI van de agent (bijvoorbeeld deze markeert als gemitigeerd op een aangepaste agentpagina), synchroniseert de agent die status met de Aanbevolen Acties-agent door aan te roepen msdyn_SyncActionExecutionStateFromAgent. Met deze actie wordt de status in de uitvoertabel van de agent Aanbevolen acties bijgewerkt, waardoor deze niet meer in de carrousel wordt weergegeven.

Testen en validatie

Na configuratie en implementatie valideert u de end-to-end flow door de volgende controles uit te voeren.

Controleer de configuratie van de agent:

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

Push een testactie door aan te roepen msdyn_PushActionDataToRecommendedActionAgent en te controleren of dat msdyn_IsSuccess waar is, en een nieuw record verschijnt in msdyn_rawactioncatalogue.

Activeer de score op aanvraag door te bellen msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration (in plaats van te wachten op de 4-uurs timer).

Controleer de gescorede output:

    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

Verwachte waarden:

• msdyn_actionscore wordt gevuld met een waarde in het bereik van 0-10.
• msdyn_hascrossedfloor is vals (actie is boven de vloer en wordt weergegeven in de draaimolen).
• msdyn_actionuistatus is 1 (Actief).
• msdyn_scoredetails bevat de door LLM gegenereerde uitleg.

Controleer het carrouseldisplay door een Opportunity-formulier te openen in Dynamics 365 Sales en het gedeelte Voorgestelde Acties aan te vinken. Controleer de statussynchronisatie door een actie in de carrousel te verwijzen (de sync-back API moet worden aangeroepen met state = "Dismissed") en door een actie te markeren in de agent-UI (het uitvoertabelrecord moet de bijgewerkte msdyn_actionuistatusweergave weergeven).

Voorbeeld: Sales Opportunity Agent

Sales Opportunity Agent is de eerste agent die wordt ingeboord bij de Recommended Actions Agent, en de integratie ervan dient als referentie-implementatie.

Agentconfiguratiewaarden:

Wanneer het onderzoek van de verkoopkansagent is voltooid en dealrisico's identificeert, plaatst DealRiskToNBAService elk risico als een aparte actie:

Status-synchronisatiegedrag:

• Verkoopkansagent → Aanbevolen Acties-agent: Wanneer een verkoper een risico als gedaan aangeeft op de onderzoekspagina, belt msdyn_SyncActionExecutionStateFromAgentde makelaar.
• Aanbevolen Acties Agent → Verkoopkansagent: Wanneer een verkoper een kaart in de carrousel negeert, roept ora_UpdatedActionStateFromRAAgent de Aanbevolen Acties-agent (geconfigureerd in de agentconfiguratie).

Verwante informatie

• Configureer de Aanbevolen Acties-agent
• Overzicht van aanbevolen acties