Integrer tilpassede agenter med Recommended Actions Agent

Agenten for anbefalte handlinger i Dynamics 365 Sales viser prioriterte anbefalinger for salgsmuligheter. Den tilbyr en delt scorepipeline, datakontrakter og toveis tilstandssynkronisering slik at enhver tilpasset agent kan fremlegge anbefalinger sammen med førstepartsagenter.

Denne artikkelen beskriver arkitekturen, nøkkelkomponentene, datakontraktene og integrasjonsflyten som brukes når en tilpasset agent integreres med Recommended Actions Agent. Den gir den grunnleggende kunnskapen som kreves for å implementere en integrasjon.

Forutsetninger

  • NextBestActionAgent-løsning distribuert til målorganisasjonen. For mer informasjon, se Importer en agent til et målmiljø.

  • Selger har passende Dataverse-sikkerhetsroller som beskrevet i Tillatelser som kreves for tilpassede sikkerhetsroller.

  • En stabil, unik SourceAgentId-streng for den tilpassede agenten. For mer informasjon, se Legg til tilpassede agenter for anbefalte tiltak.

  • Følgende tillatelser kreves for å pushe anbefalte handlinger:

    Tabell Nødvendige rettigheter Område
    msdyn_rawactioncatalogue Les, skriv, legg til og legg ved. Global
    msdyn_prioritizedactioncatalogue Les, skriv, legg til og legg ved. Global
    msdyn_recommendedactionsourceagentconfig Les Global
    msdyn_salesagentprofile Les Global

Integrasjon arkitektur

Integrasjonen med Recommended Actions Agent bruker en prosesseringspipeline som tar inn rå handlinger fra kildeagenter, scorer dem ved hjelp av en UICE-motor (Urgency, Impact, Confidence, Effort), og viser de prioriterte resultatene i selgerkarusellen.

Behandlingsrørledningen fungerer som følger:

  1. Custom agenten oppdager en handlingsrettet innsikt (for eksempel en avtalerisiko, en stoppet avtale eller en manglende interessent).
  2. Den tilpassede agenten kaller det tilpassede API-et msdyn_PushActionDataToRecommendedActionAgent for å sende handlingen.
  3. Handlingen lagres i msdyn_rawactioncatalogue (inndatatabell).
  4. For hver handling gjør Scoring Engine:
    • Henter enhetssignaler fra Dataverse.
    • Henter agentspesifikke prioriteringsdata fra handlingskatalogen.
    • Bruker LLM-en til å vurdere handlingen langs UICE-dimensjonene (Hast, Påvirkning, Tiltro, Innsats).
    • Gjelder regler for gulv og tak.
    • Beregner den endelige prioritetsscoren ved å bruke GetRecommendedActionAgentResponse.
  5. Den scorede handlingen settes inn i msdyn_prioritizedactioncatalogue (utdatatabellen).
  6. Agent Carousel henter scorede handlinger og gjengir kort.

Nøkkelkomponenter

Integrasjonen baserer seg på følgende Dataverse-tabeller og API-er.

Komponent Lokasjon Description
Inndatatabell msdyn_rawactioncatalogue (Dataverse) Råhandlinger som egendefinerte agenter sender
Utdatatabell msdyn_prioritizedactioncatalogue (Dataverse) Resultater og rangerte handlinger for brukergrensesnittet
Agentkonfigurasjon msdyn_recommendedactionsourceagentconfig (Dataverse) Per agent-registrering og -konfigurasjon
Push-API msdyn_PushActionDataToRecommendedActionAgent (Egendefinert API) Agent → Anbefalte handlinger Agenthandling: push

Agentregistrering

Registrer tilpassede agenter hos Recommended Actions Agent slik at plattformen gjenkjenner og henter handlingene deres. For mer informasjon om registrerende agenter, se Legg til tilpassede agenter for anbefalte tiltak.

Når du registrerer en agent, opprettes det en oppføring i msdyn_recommendedactionsourceagentconfig. Den unike SourceAgentId identifiserer oppføringen til den egendefinerte agenten.

Agentkonfigurasjon

Tabellen msdyn_recommendedactionsourceagentconfig inneholder per-agent-konfigurasjon som styrer hvordan Anbefales Handlinger-agenten tolker agentens handlinger. De to viktigste feltene å befolke er msdyn_internalprioritizationinstruction og msdyn_syncactionexecutionstateapiconfig.

Du kan bruke konfigurasjon enten ved å manuelt oppdatere tabellposten eller ved å kalle det tilpassede API-et UpsertRecommendationAgentConfigRequest.

UpsertRecommendationAgentConfigRequest-skjema

Følgende eksempel viser de tilgjengelige konfigurasjonsfeltene i skjemaet.

{
  "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-felt Type Description
agentName streng Karter til msdyn_agentname (maks 850 tegn). Påkrevd for nye oppføringer.
agentType streng Agentkategori. Bruk "CustomAgent" for ikke-Sales Opportunity Agent-agenter for å automatisk opprette en profil.
isRecommendedActionAgentEnabled boolsk Kart til msdyn_isrecommendedactionagentenabled. Null = la være uendret.
salesAgentProfileId Guid? Lenker til msdyn_salesagentprofile. Brukes til postoppslag på upsert.
agentImpactMapping streng Flat JSON-array av hovednavn. Kart til msdyn_agentimpactmapping.
internPrioriteringsinstruksjon streng JSON med signalarray. Kart til msdyn_internalprioritizationinstruction.
syncActionExecutionStateApiConfig streng JSON-objekt {"syncactionuistatusapiname":"..."}. Kart til msdyn_syncactionexecutionstateapiconfig.
sourceAgentUniqueId streng Kart til msdyn_sourceagentuniqueid.
beskrivelse streng Karter til msdyn_sourcedescription (maks 1000 karakterer).

Intern prioriteringsinstruksjon

Den interne prioriteringsinstruksjonen inneholder agent-spesifikke signalmetadata som forteller poengmotoren hvordan den skal tolke agentens prioriteringsdatafelt. Det er et JSON-objekt med et toppnivå-array signals . Hvert signal deserialiseres inn i AgentSignalInstructionConfig med følgende felt:

Felt Type Description
name streng Signalidentifikator — brukt som nøkkel i poengpromptens Signal Reference-seksjon
type streng Datatype: "streng", "tall", "boolean"
kilde streng Beskrivende etikett for hvor signalet kommer fra. Brukes ikke til ruting — fetch_info.fetch_type styrer selve hentemekanismen. Vanligvis «action_data» for signaler sendt av agenten.
dimension_influence {dimensjon: styrke} Hvilke UICE-dimensjoner dette signalet påvirker og hvor sterkt. Nøkler: «hastverk», «påvirkning», «selvtillit», «innsats». Styrker: "sterk", "moderat", "svak"
Tolkning streng Naturlig språklig beskrivelse av hva signalet betyr for poenggiving — injisert i LLM-prompten
pålitelighet streng Hvor pålitelig dette signalet er: "høy", "middels", "lav"
obligatorisk boolsk Om signalet må være til stede for scoring
fetch_info objekt Styrer hvor og hvordan signalverdien hentes ved scoringstidspunkt.

Eksempel på signalblokk:

{
  "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-konfigurasjon for synkroniseringshandlingstilstand

API-konfigurasjonen for synkroniseringshandlingsutførelse er et JSON-objekt som spesifiserer det tilpassede API-navnet Recommended Actions Agent kaller når en selger handler på et kort (for eksempel markerer det som fullført eller irrelevant). Denne API-en angir statusen for handlingen i den egendefinerte kildeagenten.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

Aksjonspush-kontrakt

Egendefinerte agenter sender handlinger ved å bruke det tilpassede msdyn_PushActionDataToRecommendedActionAgent API-et. API-et kalles hver gang agenten genererer eller oppdaterer en handling for en målenhet.

Forespørselsparametere

Parameteren Type Påkrevd Description
msdyn_ActionId streng Ja Agentens unike identifikator for denne handlingen. Brukes til deduplisering og tilstandssynkronisering. Må være deterministisk (samme handling = samme ID). Eksempelformat: DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId streng Ja Agentens identifikator. Må matche msdyn_agentname i agentens konfigurasjonspost. Eksempel: "DealClosingAgent"
msdyn_TargetEntityId Unikidentifikator (GUID) Ja GUID for målposten (Mulighet, Lead) som denne handlingen relaterer seg til
msdyn_TargetEntityTypeName streng Ja Logisk navn på målentiteten. Eksempel: «mulighet», «lede»
msdyn_ActionReason streng Ja Årsaken til at handlingen ble generert. Brukes av poengmotoren for tilordning av prinsipper.
msdyn_ActionUIPayload streng Nei JSON-data for gjengivelse av kort. Hvis det utelates, kan ikke Recommended Actions Agent vise kortet.
msdyn_ActionPrioritizationData streng Nei JSON med agentspesifikke data for poengberegning
msdyn_ActionCTA streng Nei CTA-typestreng. Eksempel: «E-post», «Anmeldelse», «Samtale»
msdyn_PrioritizationPrinciples streng Nei JSON-matrise med prioriteringsprinsipper som denne bestemte handlingen tilordnes til (kan overstyre tilordning på agentnivå)

Eksempel: C# plugin-kall

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-nyttelastkontrakt

Feltet msdyn_ActionUIPayload inneholder en JSON-nyttelast som styrer hvordan et handlingskort vises 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

Feltet msdyn_prioritizationdata lar en agent sende agentspesifikke signaler som påvirker hvordan UICE-poengmotoren prioriterer en handling.

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

Poengmotoren leser disse signalene sammen med entitetsnivå-signaler (avtaleverdi, nivå, konkurrenter, og så videre). Agent-konfigurasjonen msdyn_internalprioritizationinstruction forteller LLM-en hvordan den skal tolke hvert signal, og poengmotoren kombinerer alle signalene i UICE-poengprompten.

Handlingsversjonering og ugyldiggjøring

Når en agent oppdaterer data for en tidligere pushet handling, oppretter den en ny post med samme msdyn_ActionId ved å kalle msdyn_PushActionDataToRecommendedActionAgent igjen. Systemet oppretter en ny rad med msdyn_rawactioncatalogue samme msdyn_actionid , men en ny msdyn_rawactioncatalogueid. Agent for anbefalte handlinger viser stadig den gamle versjonen til den behandler den nye.

For å ugyldiggjøre en handling (for eksempel når en risiko løses), kaller agenten det tilpassede msdyn_RAAgent_RemoveActionsV2 API-et med .actionId Denne handlingen markerer alle msdyn_rawactioncatalogue poster for den handlingen som inaktive, og kortet forsvinner fra karusellen.

Toveis tilstandssynkronisering

Handlingstilstanden synkroniseres både i Recommended Actions Agent-karusellen og din tilpassede agent for å sikre at selgere ser konsistent informasjon uansett hvor de handler under en handling.
Anbefalte handlinger Agent → spesialagent (selger handler i karusellen): Når en selger markerer en handling som utført eller avvist i karusellen:

  1. Anbefalt handlingsagent oppdaterer msdyn_actionuistatus i msdyn_prioritizedactioncatalogue.
  2. Recommended Actions Agent leser fra msdyn_syncactionexecutionstateapiconfig agentkonfigurasjonen.
  3. Recommended Actions Agent kaller agentens tilpassede API med:
Parameteren Type Description
actionid GUID Handlingsidentifikatoren
Staten streng "MarkertFerdig" eller "Avskjediget"

Agenten må implementere et tilpasset API som aksepterer disse to parameterne og oppdaterer handlingstilstanden i sin egen datalagring.

Custom agent → Recommended Actions Agent (selger handler i agentens brukergrensesnitt): Når en selger handler på en handling i agentens eget brukergrensesnitt (for eksempel markerer den som mitigert på en egendefinert agentside), synkroniserer agenten den tilstanden til Recommended Actions Agent ved å kalle msdyn_SyncActionExecutionStateFromAgent. Denne handlingen oppdaterer tilstanden i utdatatabellen Anbefalte handlinger-agenten, og skjuler den for karusellen.

Parameteren Type Påkrevd Description
msdyn_ActionId streng Ja Handlingsidentifikatoren (samme som den som ble pushet)
msdyn_ActionState heltall Ja Ny tilstand — verdier (mappet til MarkAsDone/Dismissed)
msdyn_TargetEntityId Unikidentifikator Ja GUID for målentitet
TargetEntityTypeName streng Ja Logisk navn på målentitet
msdyn_TrackingId streng Nei Valgfri sporing/korrelasjons-ID

Testing og validering

Etter konfigurasjon og implementering, valider ende-til-ende-flyten ved å utføre følgende kontroller.

Verifiser agentkonfigurasjonen:

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

Utfør en testhandling ved å anrope msdyn_PushActionDataToRecommendedActionAgent og bekreft at msdyn_IsSuccess er sann, og at en ny post vises i msdyn_rawactioncatalogue.

Trigger poengscoring på forespørsel ved å ringe msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration (i stedet for å vente på 4-timers timeren).

Verifiser scoret 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

Forventede verdier:

  • msdyn_actionscore fylles ut med en verdi i området 0–10.
  • msdyn_hascrossedfloor er falsk (handlingen er over gulvet og vises i karusellen).
  • msdyn_actionuistatus er 1 (Aktiv).
  • msdyn_scoredetails inneholder llm-generert forklaring.

Verifiser karusellvisning ved å åpne et Mulighetsskjema i Dynamics 365 Sales og krysse av i seksjonen Foreslåtte handlinger. Verifiser tilstandssynkronisering ved å avvise en handling i karusellen (sync-back-API-et skal kalles med state = "Dismissed") og ved å markere en handling i agentgrensesnittet (utdatatabellposten skal gjenspeile den oppdaterte msdyn_actionuistatus).

Eksempel: Salgsmulighetsagent

Sales Opportunity Agent er den første agenten som blir integrert i Recommended Actions Agent, og integrasjonen fungerer som referanseimplementasjon.

Agentkonfigurasjonsverdier:

Konfigurasjonsfelt Verdi for salgsmulighetsagent (fra OraDefaults.cs)
msdyn_agentname "SalgsMulighetAgent"
msdyn_agentimpactmapping ["DealRisk","Avtaletempo"]
msdyn_syncactionexecutionstateapiconfig {"syncactionuistatusapiname":"msdyn_SyncDealRiskActionFromNba"}
msdyn_internalprioritizationinstruction Se salgsmulighetsagentens produksjonsverdi

Når Sales Opportunity Agent har fullført undersøkelsen og identifisert risikoer knyttet til avtalen, DealRiskToNBAService oppretter hver risiko som en egen handling:

pushparameter Verdi av salgsmulighetsagent
msdyn_ActionId DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId "DealRiskAgent"
msdyn_TargetEntityTypeName "mulighet"
msdyn_ActionReason Risikobeskrivelse fra forskning
msdyn_ActionUIPayload Kort med risikooverskrift + beskrivelse
msdyn_ActionPrioritizationData {"riskType":"8","risk":"Missing BANT Info"} (eksempel)

Tilstandssynkroniseringsoppførsel:

  • Salgsmulighetsagent → Agent for anbefalte handlinger: Når en selger markerer en risiko som gjort på forskningssiden, ringer msdyn_SyncActionExecutionStateFromAgentagenten.
  • Anbefalte handlinger Agent → Salgsmulighetsagent: Når en selger avviser et kort i karusellen, kaller ora_UpdatedActionStateFromRAAgent Recommended Actions Agent (konfigurert i agentkonfigurasjonen).
  • Last updated on