Integra gli agenti personalizzati con l'Agente delle Azioni Raccomandate

L'Agente delle Azioni Raccomandate in Dynamics 365 Remote Assist presenta raccomandazioni prioritarie per opportunità. Fornisce una pipeline di punteggio condivisa, contratti dati e sincronizzazione bidirezionale degli stati in modo che qualsiasi agente personalizzato possa presentare raccomandazioni insieme agli agenti di prima parte.

Questo articolo descrive l'architettura, i componenti chiave, i contratti dati e il flusso di integrazione utilizzati quando un agente personalizzato si integra con l'Agente delle Azioni Raccomandate. Fornisce le conoscenze fondamentali necessarie per implementare un'integrazione.

Prerequisiti

• soluzione NextBestActionAgent distribuita all'organizzazione di destinazione. Per maggiori informazioni, vedi Importa un agente in un ambiente target.

• Il venditore ha ruoli di sicurezza Dataverse appropriati come descritto in Permessi richiesti per ruoli di sicurezza personalizzati.

• Una stringa SourceAgentId stabile e unica per l'agente personalizzato. Per maggiori informazioni, consulta Aggiungi agenti personalizzati per le azioni consigliate.

• I seguenti permessi sono necessari per spingere le azioni raccomandate:

  Tabella	Privilegi obbligatori	Scope
  msdyn_rawactioncatalogue	Leggi, Scrivi, Appendi e AppendA	Global
  msdyn_prioritizedactioncatalogue	Leggi, Scrivi, Appendi e AppendA	Global
  msdyn_recommendedactionsourceagentconfig	Leggi	Global
  msdyn_salesagentprofile	Leggi	Global

Architettura di integrazione

L'integrazione con l'Agente di Azioni Raccomandate utilizza una pipeline di elaborazione che assume le azioni grezze dagli agenti sorgente, le valuta tramite un motore di punteggio UICE (Urgenza, Impatto, Fiducia, Sforzo) e mostra i risultati prioritari nel carosello del venditore.

La pipeline di elaborazione funziona come segue:

1. L'agente doganale rileva un'intuizione azionabile (ad esempio, un rischio di accordo, un accordo bloccato o un stakeholder assente).
2. L'agente personalizzato chiama l'API msdyn_PushActionDataToRecommendedActionAgent personalizzata per spingere l'azione.
3. L'azione è memorizzata in msdyn_rawactioncatalogue (tabella di input).
4. Per ogni azione, il motore di punteggio:
   • Recupera i segnali dell'entità da Dataverse.
   • Recupera i dati di priorità specifici dell'agente dal catalogo delle azioni.
   • Chiama l'LLM per assegnare un punteggio all'azione secondo le dimensioni UICE (Urgenza, Impatto, Confidenza, Sforzo).
   • Applica i limiti minimo e massimo.
   • Calcola il punteggio finale di priorità usando GetRecommendedActionAgentResponse.
5. L'azione segnata viene inserita in msdyn_prioritizedactioncatalogue (tabella di output).
6. Il carosello Agente delle azioni consigliate recupera le azioni con punteggio e visualizza le schede.

Componenti chiave

L'integrazione si basa sulle seguenti tabelle e API Dataverse.

Registrazione dell'agente

Registra gli agenti personalizzati con l'agente Azioni consigliate in modo che la piattaforma ne riconosca e recuperi le relative azioni. Per maggiori informazioni sulla registrazione degli agenti, vedi Aggiungi agenti personalizzati per le azioni consigliate.

Quando registri un agente, viene creata una voce in msdyn_recommendedactionsourceagentconfig. L'identificatore univoco SourceAgentId identifica la voce per l'agente personalizzato.

Configurazione dell'agente

La msdyn_recommendedactionsourceagentconfig tabella contiene la configurazione per agente che governa come l'Agente delle Azioni Raccomandate interpreta le azioni di un agente. I due campi più importanti da popolare sono msdyn_internalprioritizationinstruction e msdyn_syncactionexecutionstateapiconfig.

Puoi applicare la configurazione aggiornando manualmente l'record della tabella o chiamando l'API UpsertRecommendationAgentConfigRequestpersonalizzata .

Schema di UpsertRecommendationAgentConfigRequest

L'esempio seguente mostra i campi di configurazione disponibili nello 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"
}

Istruzione di definizione delle priorità interna

L'istruzione interna di priorità contiene metadati di segnale specifici per l'agente che indicano al motore di punteggio come interpretare i campi dati di priorità di un agente. È un oggetto JSON con un array di livello superiore signals . Ogni segnale viene deserializzato in AgentSignalInstructionConfig con i seguenti campi:

Esempi di blocco dei segnali:

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

Configurazione API dello stato di esecuzione dell'azione di sincronizzazione

La configurazione dell'API config per lo stato di esecuzione dell'azione di sincronizzazione è un oggetto JSON che specifica il nome personalizzato dell'API che l'Agente delle Azioni Raccomandate chiama quando un venditore agisce su una carta (ad esempio, la segna come completa o irrilevante). Questa API imposta lo stato dell'azione nell'agente personalizzato di origine.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

Contratto di azione push

Gli agenti personalizzati spingono le azioni usando l'API msdyn_PushActionDataToRecommendedActionAgent personalizzata. L'API viene chiamata ogni volta che l'agente genera o aggiorna un'azione per un'entità target.

Parametri della richiesta

Esempio: chiamata del 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"];

Contratto di payload dell'interfaccia utente d'azione

Il msdyn_ActionUIPayload campo contiene un payload JSON che controlla come appare una carta azione nella giostra Recommended Actions Agent.

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

Contratto di dati di prioritizzazione

Il msdyn_prioritizationdata campo consente a un agente di trasmettere segnali specifici dell'agente che influenzano il modo in cui il motore di assegnazione del punteggio UICE stabilisce la priorità di un'azione.

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

Il motore di punteggio legge questi segnali insieme ai segnali a livello di entità (valore dell'accordo, stadio, concorrenti e così via). L’elemento msdyn_internalprioritizationinstruction nella configurazione dell’agente specifica al LLM come interpretare ciascun segnale, e il motore di punteggio combina tutti i segnali in un unico prompt di punteggio UICE.

Gestione delle versioni delle azioni e invalidazione

Quando un agente aggiorna i dati relativi a un'azione già inviata, crea un nuovo record con lo stesso msdyn_ActionId richiamando msdyn_PushActionDataToRecommendedActionAgent. Il sistema crea una nuova riga in msdyn_rawactioncatalogue con lo stesso msdyn_actionid ma con un nuovo msdyn_rawactioncatalogueid L'Agente delle Azioni Raccomandate continua a mostrare la versione vecchia finché non elabora quella nuova.

Per invalidare un'azione (ad esempio, quando un rischio viene risolto), l'agente chiama l'API msdyn_RAAgent_RemoveActionsV2 personalizzata con il actionId. Questa azione contrassegna come inattivi tutti i record msdyn_rawactioncatalogue relativi a tale azione e la scheda scompare dal carosello.

Sincronizzazione bidirezionale dello stato

Lo stato dell'azione si sincronizza sia nel carosello dell'Agente delle Azioni Raccomandate sia nel tuo agente personalizzato per garantire che i venditori vedano informazioni coerenti indipendentemente da dove agiscono su un'azione.
Azioni raccomandate Agente → agente doganale (il venditore agisce nella giostra): Quando un venditore segna un'azione come Compiuta o Rifiutata nel carosello:

1. L'agente Azioni consigliate aggiorna il msdyn_actionuistatus in msdyn_prioritizedactioncatalogue.
2. L'agente per le azioni consigliate legge il msdyn_syncactionexecutionstateapiconfig dalla configurazione dell'agente.
3. L'Agente Azioni Raccomandate chiama l'API personalizzata dell'agente con:

L'agente deve implementare un'API personalizzata che accetti questi due parametri e aggiorni lo stato dell'azione nel proprio archivio dati.

Agente personalizzato → Agente delle Azioni Raccomandate (il venditore agisce nell'interfaccia utente dell'agente): Quando un venditore agisce su un'azione nell'interfaccia utente dell'agente (ad esempio, la segna come mitigata su una pagina di un agente personalizzato), l'agente sincronizza quello stato con l'Agente delle Azioni Raccomandate chiamando msdyn_SyncActionExecutionStateFromAgent. Questa azione aggiorna lo stato nella tabella di output dell'agente Azioni consigliate, nascondendolo dal carosello.

Test e convalida

Dopo la configurazione e l'implementazione, validare il flusso end-to-end effettuando i seguenti controlli.

Verifica la configurazione dell'agente:

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

Esegui un'azione di test chiamando msdyn_PushActionDataToRecommendedActionAgent e verifica che msdyn_IsSuccess sia vera e che apparga un nuovo record in msdyn_rawactioncatalogue.

Attiva il calcolo del punteggio su richiesta richiamando msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration (invece di aspettare il timer di 4 ore).

Verifica l'output con punteggio:

    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

Valori previsti:

• msdyn_actionscore viene popolato con un valore nell'intervallo 0-10.
• msdyn_hascrossedfloor è falso (l'azione è sopra la soglia minima e viene visualizzata nel carosello).
• msdyn_actionuistatus è 1 (Attivo).
• msdyn_scoredetails contiene la spiegazione generata da LLM.

Verifica la visualizzazione della giostra aprendo un modulo Opportunità in Dynamics 365 Remote Assist e selezionando la sezione Azioni Suggerite. Verifica la sincronizzazione dello stato annullando un'azione nel carosello (l'API di sincronizzazione deve essere chiamata con state = "Dismissed") e segnando un'azione nell'interfaccia dell'agente (il record della tabella di output dovrebbe riflettere l'aggiornamento msdyn_actionuistatus).

Esempio: Agente di Opportunità di Vendita

Sales Opportunity Agent è il primo agente integrato nell'Agente delle Azioni Raccomandate, e la sua integrazione funge da riferimento per implementazione.

Valori di configurazione degli agenti:

Quando l'analisi di Sales Opportunity Agent è completata e identifica i rischi dell'affare, DealRiskToNBAService invia ogni rischio come azione separata:

Comportamento di sincronizzazione dello stato:

• Agente delle Opportunità di Vendita → Agente delle Azioni Raccomandate: Quando un venditore segna un rischio come fatto nella pagina di ricerca, l'agente chiama msdyn_SyncActionExecutionStateFromAgent.
• Agente Azioni consigliate → Agente Opportunità commerciale: Quando un venditore ignora una scheda nel carosello, l'Agente Azioni consigliate chiama ora_UpdatedActionStateFromRAAgent (come definito nella configurazione dell'agente).

Informazioni pertinenti

• Configura l'agente Azioni Raccomandate
• Panoramica delle azioni consigliate