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.

Componente	Posizione	Description
Tabella di input	msdyn_rawactioncatalogue (Dataverse)	Azioni non elaborate che gli agenti personalizzati inviano
Tabella dei risultati	msdyn_prioritizedactioncatalogue (Dataverse)	Azioni con punteggio e classificazione per l'interfaccia utente
Configurazione dell'agente	msdyn_recommendedactionsourceagentconfig (Dataverse)	Registrazione e configurazione per agente
Push API	msdyn_PushActionDataToRecommendedActionAgent (API personalizzata)	Agente → Azioni consigliate Invio dell'azione dell'agente

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

Campo JSON	Tipo	Description
nome agente	string	Viene mappato a msdyn_agentname (max 850 caratteri). Obbligatorio per i nuovi record.
agentType	string	Categoria agente. Usa "CustomAgent" per gli agenti non di vendita per creare automaticamente un profilo.
isRecommendedActionAgentEnabled	boolean	Mappe per msdyn_isrecommendedactionagentenabled. Null = lasciare invariato.
salesAgentProfileId	Guid?	Collegamenti a msdyn_salesagentprofile. Utilizzato per la ricerca di record su upsert.
agentImpactMapping	string	Array JSON semplice di nomi di principi. Mappe per msdyn_agentimpactmapping.
Istruzioni per la prioritizzazione interna	string	JSON con array di segnali. Mappe per msdyn_internalprioritizationinstruction.
syncActionExecutionStateApiConfig	string	Oggetto JSON {"syncactionuistatusapiname":"..."}. Mappe per msdyn_syncactionexecutionstateapiconfig.
sourceAgentUniqueId	string	Mappe per msdyn_sourceagentuniqueid.
description	string	Viene mappato a msdyn_sourcedescription (massimo 1000 caratteri).

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:

Campo	Tipo	Description
nome	string	Identificatore del segnale — usato come chiave nella sezione Riferimento del segnale del prompt di valutazione
type	string	Tipo di dato: "stringa", "numero", "booleano"
source	string	Etichetta descrittiva per la provenienza del segnale. Non usato per il routing — fetch_info.fetch_type controlla il meccanismo effettivo di recupero. In genere, "action_data" per i segnali inviati dagli agenti.
dimension_influence	{dimensione: forza}	Su quali dimensioni UICE influisce questo segnale e con quale intensità. Chiavi: "urgenza", "impatto", "fiducia", "impegno". Punti di forza: "forte", "moderato", "debole"
interpretazione	string	Descrizione in linguaggio naturale di ciò che il segnale significa per il punteggio — inserita nel prompt dell’LLM
affidabilità	string	Quanto è affidabile questo segnale: "alto", "medio", "basso"
required	boolean	Indica se il segnale deve essere presente per l'assegnazione dei punteggi
fetch_info	object	Controlla dove e come viene recuperato il valore del segnale in fase di assegnazione dei punteggi.

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

Parametro	Tipo	Obbligatorio	Description
msdyn_ActionId	string	Yes	Identificatore unico dell'agente per questa azione. Usato per la deduplicazione e la sincronizzazione dello stato. Deve essere deterministico (stessa azione = stesso ID). Formato di esempio: DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId	string	Yes	Identificatore dell'agente. Deve corrispondere al msdyn_agentname nel record di configurazione dell'agente. Esempio: "DealClosingAgent"
msdyn_TargetEntityId	identificatore univoco (GUID)	Yes	GUID del record di destinazione (Opportunità, Lead) a cui si riferisce questa azione
msdyn_TargetEntityTypeName	string	Yes	Nome logico dell'entità di destinazione. Esempio: "opportunità", "lead"
msdyn_ActionReason	string	Yes	Motivo per cui l'azione è stata generata. Usato dal motore di assegnazione dei punteggi per la mappatura dei principi.
msdyn_ActionUIPayload	string	No	Payload JSON per il rendering delle carte. Se omesso, l'Agente delle Azioni Raccomandate non può mostrare la carta.
msdyn_ActionPrioritizationData	string	No	JSON con dati specifici per l'agente per il punteggio
msdyn_ActionCTA	string	No	Stringa di tipo CTA. Esempio: "Email", "Recensione", "Chiamata"
msdyn_PrioritizationPrinciples	string	No	Array JSON dei principi di prioritizzazione a cui questa specifica azione è associata (può sovrascrivere la mappatura a livello di agente)

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:

Parametro	Tipo	Description
actionid	GUID	Identificatore dell'azione
state	string	"Contrassegnato come completato" o "Ignorato"

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.

Parametro	Tipo	Obbligatorio	Description
msdyn_ActionId	string	Yes	L'identificatore dell'azione (lo stesso che è stato inserito)
msdyn_ActionState	integer	Yes	Nuovo stato — valori (associati a MarkAsDone/Dismissed)
msdyn_TargetEntityId	uniqueidentifier	Yes	GUID dell'entità di destinazione
TargetEntityTypeName	string	Yes	Nome logico dell'entità di destinazione
msdyn_TrackingId	string	No	ID di tracciamento/correlazione facoltativo

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:

Campo di configurazione	Valore per l'Agente di Opportunità di Vendita (da OraDefaults.cs)
msdyn_agentname	"AgenteOpportunitàVendita"
msdyn_agentimpactmapping	["DealRisk", "Velocità dell'Accordo"]
msdyn_syncactionexecutionstateapiconfig	{"syncactionuistatusapiname":"msdyn_SyncDealRiskActionFromNba"}
msdyn_internalprioritizationinstruction	Vedi il valore di produzione dell'Agente di Opportunità di Vendita

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

Parametro di push	Valore dell'agente dell'opportunità di vendita
msdyn_ActionId	DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId	DealRiskAgent
msdyn_TargetEntityTypeName	"opportunità"
msdyn_ActionReason	Descrizione dei rischi dalla ricerca
msdyn_ActionUIPayload	Scheda con intestazione di rischio e descrizione
msdyn_ActionPrioritizationData	{"riskType":"8","risk":"Missing BANT Info"} (esempio)

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