Integrer brugerdefinerede agenter med Recommended Actions Agent

Recommended Actions Agent i Dynamics 365 Sales fremstår med at prioritere anbefalinger til muligheder. Den tilbyder en delt scoringspipeline, datakontrakter og tovejs-tilstandssynkronisering, så enhver brugerdefineret agent kan fremsætte anbefalinger sammen med førstepartsagenter.

Denne artikel beskriver arkitekturen, nøglekomponenterne, datakontrakterne og integrationsflowet, der bruges, når en brugerdefineret agent integreres med Recommended Actions Agent. Den giver den grundlæggende viden, der kræves for at implementere en integration.

Forudsætninger

• NextBestActionAgent-løsningen implementeret i målorganisationen. For mere information, se Import en agent til et målmiljø.

• Sælgeren har passende Dataverse-sikkerhedsroller som beskrevet i Tilladelser, der kræves for brugerdefinerede sikkerhedsroller.

• En stabil, unik SourceAgentId-streng til den tilpassede agent. For mere information, se Tilføj brugerdefinerede agenter for anbefalede handlinger.

• Følgende tilladelser er nødvendige for at fremme anbefalede handlinger:

  Tabel	Påkrævede rettigheder	Omfanget
  msdyn_rawactioncatalogue	Læs, skriv, tilføj og tilføj til	Global
  msdyn_prioritizedactioncatalogue	Læs, skriv, tilføj og tilføj til	Global
  msdyn_recommendedactionsourceagentconfig	Læs	Global
  msdyn_salesagentprofile	Læs	Global

Integration arkitektur

Integrationen af Recommended Actions Agent bruger en behandlingspipeline, der indsamler rå handlinger fra kildeagenter, scorer dem ved hjælp af en UICE-engine (Urgency, Impact, Confidence, Effort) og fremviser de prioriterede resultater i sælgerkarrusellen.

Behandlingspipelinen fungerer som følger:

1. Custom agenten opdager en handlingsorienteret indsigt (for eksempel en handelsrisiko, en fastlåst handel eller en manglende interessent).
2. Den brugerdefinerede agent kalder den tilpassede msdyn_PushActionDataToRecommendedActionAgent API for at sende handlingen.
3. Handlingen gemmes i msdyn_rawactioncatalogue (inputtabellen).
4. For hver handling gælder Scoring Engine:
   • Henter enhedssignaler fra Dataverse.
   • Henter agentspecifikke prioriteringsdata fra handlingskataloget.
   • Kalder LLM'en til at bedømme handlingen på UICE (Hast, Effekt, Tillid, Indsats) dimensioner.
   • Gælder regler for gulv og loft.
   • Beregner den endelige prioritetsscore ved at bruge GetRecommendedActionAgentResponse.
5. Den scorede handling indsættes i msdyn_prioritizedactioncatalogue (output-tabellen).
6. Recommended Actions Agent Carousel henter scorede handlinger og renderer kort.

Nøglekomponenter

Integrationen bygger på følgende Dataverse-tabeller og API'er.

Agentregistrering

Registrer brugerdefinerede agenter hos Recommended Actions Agent, så platformen genkender og henter deres handlinger. For mere information om registrering af agenter, se Tilføj brugerdefinerede agenter for anbefalede handlinger.

Når du registrerer en agent, oprettes der en post i msdyn_recommendedactionsourceagentconfig. Den unikke SourceAgentId identificerer posten for custom agenten.

Konfiguration af helpdesk-medarbejder

Tabellen msdyn_recommendedactionsourceagentconfig indeholder en konfiguration pr. agent, der styrer, hvordan Recommended Actions Agent fortolker en agents handlinger. De to vigtigste felter at befolke er msdyn_internalprioritizationinstruction og msdyn_syncactionexecutionstateapiconfig.

Du kan anvende konfiguration enten ved manuelt at opdatere tabelposten eller ved at kalde det brugerdefinerede API.UpsertRecommendationAgentConfigRequest

UpsertRecommendationAgentConfigRequest schema

Følgende eksempel viser de tilgængelige konfigurationsfelter i skemaet.

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

Intern prioriteringsinstruktion

Den interne prioriteringsinstruktion indeholder agent-specifikke signalmetadata, der fortæller scoringsmotoren, hvordan den skal fortolke en agents prioriteringsdatafelter. Det er et JSON-objekt med et topniveau-array signals . Hvert signal deserialiseres til AgentSignalInstructionConfig med følgende felter:

Eksempel på signalblok:

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

Konfiguration af API til udførelse af synkroniseringshandling

Sync action execution state API-konfigurationen er et JSON-objekt, der angiver det brugerdefinerede API-navn, som Recommended Actions Agent kalder, når en sælger handler på et kort (for eksempel markerer det som komplet eller irrelevant). Denne API angiver status for handlingen i den brugerdefinerede kildeagent.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

Action push-kontrakt

Brugerdefinerede agenter sender handlinger ved hjælp af den brugerdefinerede msdyn_PushActionDataToRecommendedActionAgent API. API'et kaldes hver gang agenten genererer eller opdaterer en handling for en målentitet.

Anmod om parametre

Eksempel: C# plugin-kald

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 payload-kontrakt

Feltet msdyn_ActionUIPayload indeholder en JSON-payload, der styrer, hvordan et handlingskort fremstår i Recommended Actions Agent-karrusellen.

{
  "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 lader en agent sende agent-specifikke signaler, der påvirker, hvordan UICE-scoremotoren prioriterer en handling.

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

Scoringsmotoren læser disse signaler sammen med entitetsniveau-signaler (aftaleværdi, niveau, konkurrenter osv.). I msdyn_internalprioritizationinstruction agentkonfigurationen fortæller LLM'en, hvordan hvert signal skal fortolkes, og scoringsmotoren kombinerer alle signaler i UICE-scoringsprompten.

Versionsmanipulation og ugyldiggørelse af handlinger

Når en agent opdaterer data for en tidligere sendt handling, opretter den en ny post med den samme msdyn_ActionId ved at kalde msdyn_PushActionDataToRecommendedActionAgent igen. Systemet opretter en ny række i msdyn_rawactioncatalogue med det samme msdyn_actionid , men en ny msdyn_rawactioncatalogueid. Applied Actions Agent bliver ved med at vise den gamle version, indtil den behandler den nye.

For at ugyldiggøre en handling (for eksempel når en risiko løses), kalder agenten det brugerdefinerede msdyn_RAAgent_RemoveActionsV2 API med .actionId Denne handling markerer alle msdyn_rawactioncatalogue poster for den handling som inaktive, og kortet forsvinder fra karrusellen.

Tovejs-tilstandssynkronisering

Handlingstilstand synkroniseres både i Anbefalede Handlingers Agent-karrusel og din brugeragent for at sikre, at sælgere ser ensartede oplysninger uanset, hvor de handler under en handling.
Anbefalede handlinger Agent → specialagent (sælger handler i karrusellen): Når en sælger markerer en handling som Udført eller Afvist i karrusellen:

1. Anbefalet handlingsagent opdaterer msdyn_actionuistatus i msdyn_prioritizedactioncatalogue.
2. Recommended Actions Agent læser dem msdyn_syncactionexecutionstateapiconfig fra agentens konfiguration.
3. Recommended Actions Agent kalder agentens tilpassede API med:

Agenten skal implementere et brugerdefineret API, der accepterer disse to parametre og opdaterer handlingstilstanden i sin egen datalager.

Brugerdefineret agent → Anbefalede handlinger agent (sælger handler i agentens brugerflade): Når en sælger handler på en handling i agentens egen brugerflade (for eksempel markerer den som mitigeret på en brugerdefineret agentside), synkroniserer agenten denne tilstand til Anbefalede Handlings-agenten ved at kalde msdyn_SyncActionExecutionStateFromAgent. Denne handling opdaterer tilstanden i outputtabellen Anbefalet handlingsagent, så den skjules fra karrusellen.

Test og validering

Efter konfiguration og implementering valideres end-to-end-flowet ved at udføre følgende kontroller.

Verificér agentens konfiguration:

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

Skub en testaktion ved at kalde msdyn_PushActionDataToRecommendedActionAgent og bekræft, at det er sandt, msdyn_IsSuccess og en ny post vises i msdyn_rawactioncatalogue.

Udløs scoring på bestilling ved at ringe msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration (i stedet for at vente på 4-timers timeren).

Bekræft scoret 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

Forventede værdier:

• msdyn_actionscore udfyldes med en værdi i intervallet 0-10.
• msdyn_hascrossedfloor er falsk (handlingen er over gulvet og vises i karrusellen).
• msdyn_actionuistatus er 1 (Aktiv).
• msdyn_scoredetails indeholder den LLM-genererede forklaring.

Verificér karrusellens display ved at åbne en Mulighedsformular i Dynamics 365 Sales og tjekke sektionen Foreslåede handlinger. Verificér tilstandssynkronisering ved at afvise en handling i karrusellen (sync-back API'en skal kaldes med state = "Dismissed") og ved at markere en handling i agentens UI (outputtabellens post skal afspejle den opdaterede msdyn_actionuistatus).

Eksempel: Salgsmulighedsagent

Sales Opportunity Agent er den første agent, der er blevet indlemmet i Recommended Actions Agent, og dens integration fungerer som referenceimplementering.

Agentkonfigurationsværdier:

Når salgsmulighedsagentens undersøgelse fuldfører og identificerer dealrisici, DealRiskToNBAService pushes hver risiko som en separat handling:

Tilstandssynkroniseringsadfærd:

• Salgsmulighedsagent → Anbefalede Handlinger: Når en sælger markerer en risiko som udført på researchsiden, ringer msdyn_SyncActionExecutionStateFromAgentagenten.
• Anbefalede handlinger Agent → Salgsmulighedsagent: Når en sælger afviser et kort i karrusellen, kalder ora_UpdatedActionStateFromRAAgent Recommended Actions Agent (konfigureret i agentkonfigurationen).

Relaterede oplysninger

• Konfigurer Recommended Actions-agenten
• Oversigt over anbefalede handlinger