Integrera anpassade agenter med Recommended Actions Agent

Agenten för rekommenderade åtgärder i Dynamics 365 Sales visar prioriterade rekommendationer för säljmöjligheter. Den tillhandahåller en delad poängpipeline, datakontrakt och tvåvägs tillståndssynkronisering så att vilken anpassad agent som helst kan lägga fram rekommendationer tillsammans med förstapartsagenter.

Denna artikel beskriver arkitekturen, nyckelkomponenterna, datakontrakten och integrationsflödet som används när en anpassad agent integreras med Recommended Actions Agent. Den ger den grundläggande kunskap som krävs för att genomföra en integration.

Förutsättningar

  • NextBestActionAgent-lösningen distribuerades till målorganisationen. För mer information, se Importera en agent till en målmiljö.

  • Säljaren har lämpliga säkerhetsroller i Dataverse som beskrivs i Behörigheter som krävs för anpassade säkerhetsroller.

  • En stabil, unik SourceAgentId-sträng för den anpassade agenten. För mer information, se Lägg till anpassade agenter för rekommenderade åtgärder.

  • Följande behörigheter krävs för att skicka rekommenderade åtgärder:

    Tabell Privilegier som krävs Scope
    msdyn_rawactioncatalogue Läs, skriv, lägg till och lägg till i Global
    msdyn_prioritizedactioncatalogue Läs, skriv, lägg till och lägg till i Global
    msdyn_recommendedactionsourceagentconfig Read Global
    msdyn_salesagentprofile Read Global

Integreringsarkitektur

Integrationen av Recommended Actions Agent använder en bearbetningspipeline som tar in råa åtgärder från källagenter, poängsätter dem med hjälp av en UICE-poängmotor (Urgency, Impact, Confidence, Effort) och visar de prioriterade resultaten i säljarkarusellen.

Bearbetningspipelinen fungerar enligt följande:

  1. Den anpassade agenten upptäcker en handlingsbar insikt (till exempel en affärsrisk, en avstängd affär eller en saknad intressent).
  2. Den anpassade agenten anropar det msdyn_PushActionDataToRecommendedActionAgent anpassade API:et för att skicka åtgärden.
  3. Åtgärden lagras i msdyn_rawactioncatalogue (inmatningstabell).
  4. För varje åtgärd gör Scoring Engine följande:
    • Hämtar entitetssignaler från Dataverse.
    • Hämtar agentspecifika prioriteringsdata från åtgärdskatalogen.
    • Anropar LLM för att poängsätta åtgärden utifrån UICE-dimensionerna (Brådska, påverkan, konfidens, insats).
    • Tillämpar golv- och takregler.
    • Beräknar den slutliga prioritetspoängen med hjälp av GetRecommendedActionAgentResponse.
  5. Den poängsatta handlingen infogas i msdyn_prioritizedactioncatalogue (utdatatabellen).
  6. Karusellen för agenten Rekommenderade åtgärder hämtar poängsatta åtgärder och visar kort.

Nyckelkomponenter

Integrationen bygger på följande Dataverse-tabeller och API:er.

Component Plats Beskrivning
Indatatabell msdyn_rawactioncatalogue (Dataverse) Obehandlade åtgärder som anpassade agenter skickar
Utdatatabell msdyn_prioritizedactioncatalogue (Dataverse) Poängsatta och rankade åtgärder för användargränssnittet
Agentkonfiguration msdyn_recommendedactionsourceagentconfig (Dataverse) Registrering och konfiguration per agent
Push-API msdyn_PushActionDataToRecommendedActionAgent (Anpassad API) Agent → Push för rekommenderade agentåtgärder

Agentregistrering

Registrera anpassade agenter hos Recommended Actions Agent så att plattformen känner igen och hämtar deras handlingar. För mer information om registrerade agenter, se Lägg till anpassade agenter för rekommenderade åtgärder.

När du registrerar en agent skapas en post i msdyn_recommendedactionsourceagentconfig. Den unika SourceAgentId identifierar posten för den anpassade agenten.

Agentkonfiguration

Tabellen msdyn_recommendedactionsourceagentconfig innehåller en konfiguration per agent som styr hur Rekommenderade Handlingsagenten tolkar en agents handlingar. De två viktigaste fälten att befolka är msdyn_internalprioritizationinstruction och msdyn_syncactionexecutionstateapiconfig.

Du kan tillämpa konfiguration antingen genom att manuellt uppdatera tabellposten eller genom att anropa det anpassade API:et UpsertRecommendationAgentConfigRequest.

UpsertRecommendationAgentConfigRequest schema

Följande exempel visar de tillgängliga konfigurationsfälten i schemat.

{
  "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-fält Type Beskrivning
agentName (agentnamn) string Kartar till msdyn_agentname (max 850 tecken). Krävs för nya poster.
agenttyp string Kategori för agent. Använd "CustomAgent" för agenter som inte är Sales Opportunity Agent för att automatiskt skapa en profil.
isRecommendedActionAgentEnabled Boolean Kartor till msdyn_isrecommendedactionagentenabled. Null = lämna oförändrat.
salesAgentProfileId Guid? Länkar till msdyn_salesagentprofile. Används för postsökning på upsert.
agentImpactMapping string Platt JSON-array av huvudnamn. Kartor till msdyn_agentimpactmapping.
internPrioriteringsinstruktion string JSON med signalmatris. Kartor till msdyn_internalprioritizationinstruction.
syncActionExecutionStateApiConfig string JSON-objekt {"syncactionuistatusapiname":"..."}. Kartor till msdyn_syncactionexecutionstateapiconfig.
sourceAgentUniqueId string Kartor till msdyn_sourceagentuniqueid.
description string Mappar till msdyn_sourcedescription (max 1000 tecken).

Intern prioriteringsinstruktion

Den interna prioriteringsinstruktionen innehåller agentspecifik signalmetadata som talar om för poängmotorn hur agentens prioriteringsdatafält ska tolkas. Det är ett JSON-objekt med en signals-array på toppnivå. Varje signal deserialiseras till AgentSignalInstructionConfig med följande fält:

Fält Type Beskrivning
Namn string Signalidentifierare — används som nyckel i poängpromptens Signal Reference-sektion
type string Datatyp: "sträng", "nummer", "boolesk"
source string Beskrivande etikett för var signalen kommer ifrån. Används inte för routing – fetch_info.fetch_type styr själva hämtningsmekanismen. Vanligtvis "action_data" för agentstyrda signaler.
dimension_influence {dimension: styrka} Vilka UICE-dimensioner denna signal påverkar och hur starkt. Nycklar: "brådska", "påverkan", "självförtroende", "ansträngning". Styrkor: "stark", "måttlig", "svag"
tolkning string Naturlig beskrivning av vad signalen betyder för poängräkning — injicerat i LLM-prompten
pålitlighet string Hur pålitlig denna signal är: "hög", "medel", "låg"
Krävs Boolean Om signalen måste finnas för bedömning
fetch_info object Styr var och hur signalvärdet hämtas vid bedömningstillfället.

Exempel på signalblock:

{
  "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-konfiguration för körningstillståndet för synkroniseringsåtgärder

API-konfigurationen för synkroniseringsåtgärdens exekveringstillstånd är ett JSON-objekt som specificerar det anpassade API-namnet som Recommended Actions Agent anropar när en säljare agerar på ett kort (till exempel markerar det som komplett eller irrelevant). Det här API:et anger status för åtgärden i den anpassade källagenten.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

Pushkontrakt för åtgärder

Anpassade agenter skickar handlingar genom att använda det msdyn_PushActionDataToRecommendedActionAgent anpassade API:et. API:et anropas varje gång agenten genererar eller uppdaterar en åtgärd för en målentitet.

Parametrar för begäran

Parameter Type Krävs Beskrivning
msdyn_ActionId string Yes Agentens unika identifiering för den här åtgärden. Används för deduplicering och tillståndssynkronisering. Måste vara deterministisk (samma åtgärd = samma ID). Exempelformat: DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId string Yes Agentens identifierare. Måste överensstämma med msdyn_agentname i agentkonfigurationsposten. Exempel: "DealClosingAgent"
msdyn_TargetEntityId unik identifierare (GUID) Yes GUID för målposten (Möjlighet, Led) som denna åtgärd avser
msdyn_TargetEntityTypeName string Yes Logiskt namn på målentiteten. Exempel: "möjlighet", "led"
msdyn_ActionReason string Yes Orsak till varför åtgärden genererades. Används av bedömningsmotorn för principmappning.
msdyn_ActionUIPayload string No JSON-payload för kortrendering. Om det utelämnas kan Recommended Actions Agent inte visa kortet.
msdyn_ActionPrioritizationData string No JSON med agentspecifik data för poängsättning
msdyn_ActionCTA string No CTA-typsträng. Exempel: "E-post", "Recension", "Samtal"
msdyn_PrioritizationPrinciples string No JSON-matris med prioriteringsprinciper som den här specifika åtgärden mappar till (kan åsidosätta mappning på agentnivå)

Exempel: C#-pluginanrop

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-kontrakt för nyttolast

Fältet msdyn_ActionUIPayload innehåller en JSON-payload som styr hur ett handlingskort visas i Recommended Actions Agent-karusellen.

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

Prioriteringsdatakontrakt

Fältet msdyn_prioritizationdata låter en agent skicka agentspecifika signaler som påverkar hur UICE:s poängmotor prioriterar en handling.

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

Poängmotorn läser dessa signaler tillsammans med entitetsnivåsignaler (dealvärde, nivå, konkurrenter och så vidare). I msdyn_internalprioritizationinstruction agentkonfigurationen talar LLM om hur varje signal ska tolkas, och poängmotorn kombinerar alla signaler i UICE:s poängprompt.

Versionshantering och ogiltigförklaring av åtgärder

När en agent uppdaterar data för en tidigare pushad åtgärd skapar den en ny post med samma msdyn_ActionId genom att anropa msdyn_PushActionDataToRecommendedActionAgent igen. Systemet skapar en ny rad i msdyn_rawactioncatalogue med samma msdyn_actionid men en ny msdyn_rawactioncatalogueid. Rekommenderade åtgärder-agenten fortsätter att visa den gamla versionen tills den behandlar den nya.

För att ogiltigförklara en åtgärd (till exempel när en risk löses) anropar agenten det msdyn_RAAgent_RemoveActionsV2 anpassade API:et med .actionId Denna åtgärd markerar alla msdyn_rawactioncatalogue poster för den åtgärden som inaktiva och kortet försvinner från karusellen.

Dubbelriktad synkronisering av tillstånd

Status för åtgärder synkroniseras både i karusellen för agenten Rekommenderade åtgärder och i din anpassade agent för att säkerställa att säljare ser samma information oavsett var de vidtar en åtgärd.
Rekommenderade åtgärder Agent → skräddarsydd agent (säljaren agerar i karusellen): När en säljare markerar en handling som Utförd eller Avvisad i karusellen:

  1. Rekommenderad åtgärdsagent uppdaterar msdyn_actionuistatus i msdyn_prioritizedactioncatalogue.
  2. Recommended Actions Agent läser msdyn_syncactionexecutionstateapiconfig från agentkonfigurationen.
  3. Recommended Actions Agent anropar agentens anpassade API med:
Parameter Type Beskrivning
actionid GUID Åtgärdsidentifieraren
state string "Markerad som klar" eller "Avfärdad"

Agenten måste implementera ett anpassat API som accepterar dessa två parametrar och uppdaterar åtgärdstillståndet i sin egen datalagring.

Anpassad agent → Rekommenderade åtgärder-agent (säljaren agerar i agentens användargränssnitt): När en säljare agerar på en åtgärd i agentens eget gränssnitt (till exempel markerar den som mitigerad på en anpassad agentsida), synkroniserar agenten det tillståndet till Rekommenderade åtgärder-agenten genom att anropa msdyn_SyncActionExecutionStateFromAgent. Den här åtgärden uppdaterar statusen i utdatatabellen för agenten Rekommenderade åtgärder, så att den inte visas i karusellen.

Parameter Type Krävs Beskrivning
msdyn_ActionId string Yes Åtgärdsidentifieraren (samma som den som skickades)
msdyn_ActionState integer Yes Nytt tillstånd — värden (mappat till MarkAsDone/Dismissed)
msdyn_TargetEntityId unik identifierare Yes Målentitets-GUID
TargetEntityTypeName string Yes Logisk målentitetsnamn
msdyn_TrackingId string No Valfritt spårnings-/korrelations-ID

Testning och validering

Efter konfiguration och implementering, validera end-to-end-flödet genom att utföra följande kontroller.

Verifiera agentkonfigurationen:

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

Skicka en teståtgärd genom att anropa msdyn_PushActionDataToRecommendedActionAgent och verifiera att msdyn_IsSuccess är sant och att en ny post visas i msdyn_rawactioncatalogue.

Trigga poängsättning på begäran genom att ringa msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration (istället för att vänta på 4-timmarstimern).

Verifiera poängsatta resultat:

    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

Förväntade värden:

  • msdyn_actionscore fylls med ett värde i intervallet 0–10.
  • msdyn_hascrossedfloor är falsk (handlingen är ovanför golvet och syns i karusellen).
  • msdyn_actionuistatus är 1 (Aktiv).
  • msdyn_scoredetails innehåller den LLM-genererade förklaringen.

Verifiera karusellens display genom att öppna ett Möjlighetsformulär i Dynamics 365 Sales och kryssa i avsnittet Föreslagna åtgärder. Verifiera tillståndssynkronisering genom att avvisa en åtgärd i karusellen (sync-back-API:et ska anropas med state = "Dismissed") och genom att markera en åtgärd i agentgränssnittet (utdatatabellens post ska återspegla den uppdaterade msdyn_actionuistatus).

Exempel: Försäljningsmöjlighetsagent

Sales Opportunity Agent är den första agenten som tas med i Recommended Actions Agent, och dess integration fungerar som referensimplementation.

Agentkonfigurationsvärden:

Konfigurationsfält Värde för försäljningsmöjlighetsagent (från OraDefaults.cs)
msdyn_agentname "Försäljningsmöjlighetsagent"
msdyn_agentimpactmapping ["DealRisk", "Affärshastighet"]
msdyn_syncactionexecutionstateapiconfig {"syncactionuistatusapiname":"msdyn_SyncDealRiskActionFromNba"}
msdyn_internalprioritizationinstruction Se Sales Opportunity Agentens produktionsvärde

När analysen i Sales Opportunity Agent har slutförts och identifierat affärsrisker skickar DealRiskToNBAService vidare varje risk som en separat åtgärd:

pushparameter Värde av försäljningsmöjlighetsagenter
msdyn_ActionId DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId DealRiskAgent
msdyn_TargetEntityTypeName "möjlighet"
msdyn_ActionReason Riskbeskrivning från forskning
msdyn_ActionUIPayload Kort med riskrubrik + beskrivning
msdyn_ActionPrioritizationData {"riskType":"8","risk":"Missing BANT Info"} (exempel)

Tillståndssynkroniseringsbeteende:

  • Agent för säljmöjligheter → Agent för rekommenderade åtgärder: När en säljare markerar en risk som slutförd på analyssidan anropar agenten msdyn_SyncActionExecutionStateFromAgent.
  • Agenten för rekommenderade åtgärder → Agenten för säljmöjligheter: När en säljare avvisar ett kort i karusellen anropar Agenten för rekommenderade åtgärder ora_UpdatedActionStateFromRAAgent (konfigurerad i agentkonfigurationen).
  • Last updated on