Integrieren Sie benutzerdefinierte Agenten mit Recommended Actions Agent

Der Agent für empfohlene Aktionen in Dynamics 365 Sales zeigt priorisierte Empfehlungen für Opportunities, Leads, Kundenkonten und Kontakte an. 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.

• 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 AppendTo	Global
  msdyn_prioritizedactioncatalogue	Lesen, Schreiben, Anhängen und AppendTo	Global
  msdyn_recommendedactionsourceagentconfig	Lesen	Global
  msdyn_salesagentprofile	Lesen	Global

Integrationsarchitektur

Die Integration des Agent für empfohlene Aktionen nutzt eine Verarbeitungspipeline, die Rohdaten zu Aktionen von Quell-Agenten erfasst, diese mithilfe einer UICE-Bewertungs-Engine (Urgency, Impact, Confidence, Effort) bewertet und die priorisierten Ergebnisse im Verkäufer-Karussell anzeigt.

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 führt die Scoring Engine Folgendes aus:
   • Ruft Entitätssignale von Dataverse ab.
   • Ruft agentspezifische Priorisierungsdaten aus dem Aktionskatalog ab.
   • Ruft das LLM auf, die Maßnahme anhand der UICE-Dimensionen (Dringlichkeit, Wirkung, Sicherheit, Aufwand) 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. Das Empfohlene Aktionen-Karussell ruft bewertete Aktionen ab und rendert Karten in der Listenansicht der Entität, vorausgesetzt, das Karussell ist für diese Entität aktiviert.

Wichtige Komponenten

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

Agent-Registrierung

Registrieren Sie benutzerdefinierte Agenten beim Agent für empfohlene Aktionen, damit die Plattform diese erkennt und ihre Aktionen 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 in AgentSignalInstructionConfig mit 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 für den Ausführungsstatus der Synchronisierungsaktion ist ein JSON-Objekt, das den benutzerdefinierten API-Namen angibt, den der Recommended Actions Agent aufruft, wenn ein Verkäufer eine Aktion für eine Karte ausführt (sie beispielsweise als abgeschlossen 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

Das folgende Beispiel erstellt und führt eine Anfrage aus, um eine Deal-Risk-Aktion an den Recommended Actions Agent zu senden. Die Anfrage identifiziert den Quellagenten und die Zielchance, übermittelt den Grund und die Nutzdaten für die Karten-UI, enthält Risikosignale zur Priorisierung und prüft, ob der Vorgang erfolgreich war.

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.

Aktivieren Sie das Empfohlene Aktions-Karussell

Aktivieren Sie das Karussell für empfohlene Aktionen, damit es in der Listenansicht einer Entität erscheint. Die Entität aiinsightcard steuert den Aktivierungszustand des Karussells für jede Entität. Stellen Sie sicher, dass der entsprechende aiinsightcard Datensatz für die Entität auf aktiv gesetzt ist.

Die folgende Tabelle zeigt die Werte, die für das Aktivieren oder Deaktivieren des Karussells für eine Entität festgelegt werden sollten:

Versionierung von Aktionen und Ungültigmachung

Wenn ein Agent Daten für eine zuvor gepushte Aktion aktualisiert, erstellt er durch erneuten Aufruf von msdyn_PushActionDataToRecommendedActionAgent einen neuen Datensatz mit demselben msdyn_ActionId. 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 Status einer Aktion wird sowohl im Karussell des Agents für empfohlene Aktionen als auch in Ihrem benutzerdefinierten Agent synchronisiert, um sicherzustellen, dass Verkäufer konsistente Informationen sehen, unabhängig davon, wo sie mit einer Aktion interagieren.
Agent für empfohlene Aktionen → benutzerdefinierter Agent (Verkäufer agiert im Karussell): Wenn ein Verkäufer eine Aktion 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.

Benutzerdefinierter Agent → Agent für empfohlene Aktionen (der Verkäufer führt die Aktion in der Benutzeroberfläche des Agenten aus): Wenn ein Verkäufer eine Aktion in der eigenen Benutzeroberfläche des Agenten ausführt (zum Beispiel sie auf der Seite eines benutzerdefinierten Agenten als behoben markiert), synchronisiert der Agent diesen Status durch Aufruf von msdyn_SyncActionExecutionStateFromAgent mit dem Agenten für empfohlene Aktionen. Diese Aktion aktualisiert den Status in der Ausgabetabelle des Agent für empfohlene Aktionen und blendet ihn im Karussell aus.

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

Lösen Sie eine Testaktion aus, indem Sie msdyn_PushActionDataToRecommendedActionAgent aufrufen, und überprüfen Sie, ob msdyn_IsSuccess wahr ist und ob ein neuer Datensatz in msdyn_rawactioncatalogue erscheint.

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 der Untergrenze 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 Statussynchronisierung, indem Sie eine Aktion im Karussell verwerfen (die Sync-Back-API sollte mit state = "Dismissed" aufgerufen werden) und indem Sie eine Aktion in der Agenten-UI markieren (der Eintrag in der Ausgabetabelle sollte den aktualisierten msdyn_actionuistatus-Wert widerspiegeln).

Beispiel: Vertriebschancen-Agent

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

Agentenkonfigurationswerte:

Wenn die Recherche des Verkaufschancen-Agent abgeschlossen ist und Geschäftsrisiken identifiziert wurden, übermittelt DealRiskToNBAService jedes Risiko als separate Aktion:

Zustandssynchronisationsverhalten:

• Verkaufschancen-Agent → Agent für empfohlene Aktionen: Wenn ein Verkäufer auf der Rechercheseite ein Risiko als erledigt markiert, ruft der Agent msdyn_SyncActionExecutionStateFromAgent auf.
• Agent für empfohlene Aktionen → Agent für Verkaufschancen: Wenn ein Verkäufer eine Karte im Karussell schließt, ruft der Agent für empfohlene Aktionen ora_UpdatedActionStateFromRAAgent auf (wie in der Agentenkonfiguration festgelegt).

Verwandte Informationen

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