Integrieren Sie benutzerdefinierte Agenten mit Recommended Actions Agent

Der Recommended Actions Agent in Dynamics 365 Sales Surfaces priorisiert Empfehlungen für Chancen. Es bietet eine gemeinsame Bewertungspipeline, Datenverträge und bidirektionale Zustandssynchronisation, sodass jeder kundenspezifische Agent Empfehlungen zusammen mit First-Party-Agenten vorlegen kann.

Dieser Artikel beschreibt die Architektur, Schlüsselkomponenten, Datenverträge und den Integrationsfluss, die verwendet werden, wenn ein benutzerdefinierter Agent mit dem Recommended Actions Agent integriert. Sie vermittelt das grundlegende Wissen, das für die Umsetzung einer Integration erforderlich ist.

Voraussetzungen

• NextBestActionAgent-Lösung an die Zielorganisation bereitgestellt. Weitere Informationen finden Sie unter Einen Agenten in eine Zielumgebung importieren.

• Der Verkäufer verfügt über entsprechende Dataverse-Sicherheitsrollen , wie sie in den Berechtigungen für benutzerdefinierte Sicherheitsrollen beschrieben sind.

• Ein stabiler, eindeutiger SourceAgentId-String für den benutzerdefinierten Agenten. Weitere Informationen finden Sie unter Benutzerdefinierte Agenten hinzufügen für empfohlene Maßnahmen.

• Folgende Berechtigungen sind erforderlich, um empfohlene Maßnahmen zu pushen:

  Tabelle	Erforderliche Berechtigungen	Geltungsbereich
  msdyn_rawactioncatalogue	Lesen, Schreiben, Anhängen und Anhängen	Global
  msdyn_prioritizedactioncatalogue	Lesen, Schreiben, Anhängen und Anhängen	Global
  msdyn_recommendedactionsourceagentconfig	Lesen	Global
  msdyn_salesagentprofile	Lesen	Global

Integrationsarchitektur

Die Integration der Recommended Actions Agents verwendet eine Verarbeitungspipeline, die rohe Aktionen von Quellagenten aufnimmt, diese mittels einer UICE-Bewertungs-Engine (Urgency, Impact, Confidence, Effort) bewertet und die priorisierten Ergebnisse im Verkäuferkarussell aufzeigt.

Die Verarbeitungspipeline funktioniert wie folgt:

1. Der Custom Agent erkennt eine umsetzbare Erkenntnis (zum Beispiel ein Deal-Risiko, ein gestopptes Geschäft oder einen fehlenden Stakeholder).
2. Der benutzerdefinierte Agent ruft die benutzerdefinierte msdyn_PushActionDataToRecommendedActionAgent API auf, um die Aktion zu pushen.
3. Die Aktion wird in msdyn_rawactioncatalogue (Eingabetabelle) gespeichert.
4. Für jede Aktion gilt die Scoring Engine:
   • Ruft Entitätssignale von Dataverse ab.
   • Ruft agentspezifische Priorisierungsdaten aus dem Aktionskatalog ab.
   • Ruft den LLM auf, die Aktion auf den Dimensionen UICE (Dringlichkeit, Wirkung, Zuversicht, Anstrengung) zu bewerten.
   • Gilt für Grund- und Deckenregeln.
   • Berechnet den endgültigen Prioritätswert mit GetRecommendedActionAgentResponse.
5. Die bewertete Aktion wird in msdyn_prioritizedactioncatalogue (Ausgabetabelle) eingefügt.
6. Der Empfohlene Aktions-Agent Carousel holt bewertete Aktionen und rendert Karten.

Wichtige Komponenten

Die Integration basiert auf den folgenden Dataverse-Tabellen und APIs.

Agent-Registrierung

Registrieren Sie benutzerdefinierte Agenten beim Recommended Actions Agent, damit die Plattform ihre Aktionen erkennt und abruft. Für weitere Informationen zur Registrierung von Agenten siehe Hinzufügen von benutzerdefinierten Agenten für empfohlene Maßnahmen.

Wenn Sie einen Agenten registrieren, erstellt er einen Eintrag in msdyn_recommendedactionsourceagentconfig. Das eindeutige SourceAgentId identifiziert den Eintrag für den benutzerdefinierten Agenten.

Agentkonfiguration

Die Tabelle msdyn_recommendedactionsourceagentconfig enthält die Konfiguration pro Agent, die bestimmt, wie der Empfohlene Aktionsagent die Aktionen eines Agenten interpretiert. Die beiden wichtigsten Felder, die bevölkert werden müssen, sind msdyn_internalprioritizationinstruction und msdyn_syncactionexecutionstateapiconfig.

Sie können die Konfiguration entweder durch manuelles Aktualisieren des Tabelleneintrags oder durch Aufruf der benutzerdefinierten API UpsertRecommendationAgentConfigRequestanwenden.

UpsertRecommendationAgentConfigRequest schema

Das folgende Beispiel zeigt die verfügbaren Konfigurationsfelder im 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"
}

Interne Priorisierungsanweisung

Die interne Priorisierungsanweisung enthält agentenspezifische Signalmetadaten, die der Bewertungs-Engine angeben, wie sie die Priorisierungsdaten eines Agenten interpretieren soll. Es handelt sich um ein JSON-Objekt mit einem Top-Level-Array signals . Jedes Signal wird mit AgentSignalInstructionConfig den folgenden Feldern deserialisiert:

Beispiel für einen 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 den Ausführungsstatus der Synchronisierungsaktion

Die API-Konfiguration der Sync Action Execution State ist ein JSON-Objekt, das den benutzerdefinierten API-Namen angibt, den der Recommended Actions Agent aufruft, wenn ein Verkäufer auf einer Karte handelt (zum Beispiel als vollständig oder irrelevant markiert). Diese API legt den Status der Aktion im benutzerdefinierten Quell-Agent fest.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

Aktions-Push-Vertrag

Benutzerdefinierte Agenten pushen Aktionen über die benutzerdefinierte msdyn_PushActionDataToRecommendedActionAgent API. Die API wird jedes Mal aufgerufen, wenn der Agent eine Aktion für eine Zielentität generiert oder aktualisiert.

Anforderungsparameter

Beispiel: C#-Plugin-Aufruf

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"];

Aktions-UI-Nutzlastvertrag

Das Feld msdyn_ActionUIPayload enthält eine JSON-Nutzlast, die steuert, wie eine Aktionskarte im Recommended Actions Agent-Karussell erscheint.

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

Priorisierungsdatenvertrag

Das Feld msdyn_prioritizationdata ermöglicht es einem Agenten, agentenspezifische Signale weiterzugeben, die beeinflussen, wie die UICE-Bewertungs-Engine eine Aktion priorisiert.

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

Die Wertungsmaschine liest diese Signale zusammen mit Signalen auf Entitätsebene (Deal-Wert, Stage, Konkurrenten usw.). Die Agent-Konfiguration msdyn_internalprioritizationinstruction zeigt dem LLM, wie jedes Signal interpretiert werden soll, und die Bewertungs-Engine kombiniert alle Signale in der UICE-Bewertungsaufforderung.

Aktionsversionierung und Nichtvalidierung

Wenn ein Agent Daten für eine zuvor gepushte Aktion aktualisiert, erstellt er einen neuen Datensatz mit derselben msdyn_ActionId Aktion, indem er erneut aufruft msdyn_PushActionDataToRecommendedActionAgent . Das System erstellt eine neue Zeile in msdyn_rawactioncatalogue mit demselben msdyn_actionid, aber einem neuen msdyn_rawactioncatalogueid. Der Recommended Actions Agent zeigt die alte Version immer wieder an, bis die neue bearbeitet wird.

Um eine Aktion ungültig zu machen (zum Beispiel wenn ein Risiko gelöst ist), ruft der Agent die msdyn_RAAgent_RemoveActionsV2 benutzerdefinierte API mit der actionIdauf. Diese Aktion markiert alle msdyn_rawactioncatalogue Aufzeichnungen dieser Aktion als inaktiv, und die Karte verschwindet aus dem Karussell.

Bidirektionale Zustandssynchronisation

Der Aktionszustand synchronisiert sich sowohl im Empfohlenen Aktions-Agenten-Karussell als auch in Ihrem Custom Agent, um sicherzustellen, dass Verkäufer konsistente Informationen erhalten, unabhängig davon, wo sie bei einer Aktion handeln.
Empfohlene Maßnahmen Agent → Custom Agent (Verkäufer handelt im Karussell): Wenn ein Verkäufer eine Handlung im Karussell als erledigt oder abgelehnt markiert:

1. Der Agent für empfohlene Aktionen aktualisiert das msdyn_actionuistatus in msdyn_prioritizedactioncatalogue.
2. Der Recommended Actions Agent liest die msdyn_syncactionexecutionstateapiconfig aus der Agent-Konfiguration.
3. Recommended Actions Agent ruft die benutzerdefinierte API des Agenten auf:

Der Agent muss eine benutzerdefinierte API implementieren, die diese beiden Parameter akzeptiert und den Aktionsstatus in seinem eigenen Datenspeicher aktualisiert.

Custom Agent → Recommended Actions Agent (Verkäufer handelt in der Benutzeroberfläche des Agenten): Wenn ein Verkäufer auf eine Aktion in der eigenen Benutzeroberfläche des Agenten handelt (zum Beispiel als gemildert auf einer benutzerdefinierten Agentenseite markiert), synchronisiert der Agent diesen Zustand mit dem Empfohlenen Aktionsagenten, indem er aufruft msdyn_SyncActionExecutionStateFromAgent. Diese Aktion aktualisiert den Zustand in der Ausgabetabelle des Agents für empfohlene Aktionen, um ihn vom Karussell auszublenden.

Tests und Prüfung

Nach Konfiguration und Implementierung validieren Sie den End-to-End-Fluss durch folgende Prüfungen.

Agentenkonfiguration überprüfen:

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

Schieben Sie eine Testaktion, indem Sie aufrufen msdyn_PushActionDataToRecommendedActionAgent und überprüfen, ob das msdyn_IsSuccess stimmt, und ein neuer Datensatz erscheint in msdyn_rawactioncatalogue.

Lösen Sie die Punktewertung auf Abruf durch Anruf msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration aus (anstatt auf den 4-Stunden-Timer zu warten).

Überprüfen Sie die bewertete Ausgabe:

    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

Erwartete Werte:

• msdyn_actionscore wird mit einem Wert im Bereich von 0 bis 10 aufgefüllt.
• msdyn_hascrossedfloor ist falsch (die Aktion ist über dem Boden und wird im Karussell angezeigt).
• msdyn_actionuistatus ist 1 (Aktiv).
• msdyn_scoredetails enthält die LLM-generierte Erklärung.

Verifizieren Sie die Karussell-Anzeige, indem Sie ein Opportunity-Formular in Dynamics 365 Sales öffnen und den Abschnitt Vorgeschlagene Aktionen anklicken. Überprüfen Sie die Zustandssynchronisation, indem Sie eine Aktion im Karussell schließen (die Sync-Back-API sollte mit aufgerufen state = "Dismissed"werden) und eine Aktion in der Agenten-UI markieren (der Ausgabetabelleneintrag sollte das aktualisierte msdyn_actionuistatusDatum widerspiegeln).

Beispiel: Sales Opportunity Agent

Sales Opportunity Agent ist der erste Agent, der in den Recommended Actions Agent aufgenommen wird, und seine Integration dient als Referenzimplementierung.

Agentenkonfigurationswerte:

Wenn der Agent für Verkaufschancen seine Recherche abgeschlossen hat und Risiken für den Abschluss identifiziert, DealRiskToNBAService übermittelt er jedes Risiko als separate Aktion:

Zustandssynchronisationsverhalten:

• Vertriebs-Opportunity-Agent → Empfohlene Aktions-Agentin: Wenn ein Verkäufer ein Risiko auf der Rechercheseite als erschöpft markiert, ruft der Makler an msdyn_SyncActionExecutionStateFromAgent.
• Empfohlene Maßnahmen Agent → Vertriebs-Opportunity-Agent: Wenn ein Verkäufer eine Karte im Karussell ablehnt, ruft der Recommended Actions Agent (konfiguriert in der Agentenkonfiguration) auf ora_UpdatedActionStateFromRAAgent .

Verwandte Informationen

• Der Agent für empfohlene Aktionen konfigurieren
• Übersicht über empfohlene Aktionen