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

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.

Komponente Location Description
Eingabetabelle msdyn_rawactioncatalogue (Dataverse) Rohaktionen, die benutzerdefinierte Agenten pushen
Ausgabetabelle msdyn_prioritizedactioncatalogue (Dataverse) Bewertete und rangierte Aktionen für die Benutzeroberfläche
Agentkonfiguration msdyn_recommendedactionsourceagentconfig (Dataverse) Registrierung und Konfiguration pro Agent
Push-API msdyn_PushActionDataToRecommendedActionAgent (benutzerdefinierte API) Agent → Empfohlene Aktionen Push für Agent-Aktionen

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"
}
JSON-Feld Typ Description
Name des Agenten. string Maps zu msdyn_agentname (maximal 850 Zeichen). Erforderlich für neue Datensätze.
Agententyp string Agent-Kategorie. Verwenden Sie "CustomAgent" für Agenten, die keine Sales Opportunity Agents sind, um automatisch ein Profil zu erstellen.
isRecommendedActionAgentEnabled boolean Karten zu msdyn_isrecommendedactionagentenabled. Null = unverändert lassen.
salesAgentProfileId Guid? Links zu msdyn_salesagentprofile. Wird für die Datensatzsuche beim Upsert verwendet.
agentImpactMapping string Flaches JSON-Array der Hauptnamen. Karten zu msdyn_agentimpactmapping.
internalPrioritizationInstruction string JSON mit Signalarray. Karten zu msdyn_internalprioritizationinstruction.
syncActionExecutionStateApiConfig string JSON-Objekt {"syncactionuistatusapiname":"..."}. Karten zu msdyn_syncactionexecutionstateapiconfig.
sourceAgentUniqueId string Karten zu msdyn_sourceagentuniqueid.
description string Maps auf msdyn_sourcedescription (maximal 1000 Zeichen).

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:

Feld Typ Description
Name string Signalkennung – wird als Schlüssel im Abschnitt Signalreferenz der Wertungsaufforderung verwendet
type string Datentyp: "String", "number", "boolean"
source string Beschreibende Beschriftung für den Ort, von dem das Signal stammt. Wird nicht für Routing verwendet – fetch_info.fetch_type steuert den eigentlichen Abrufmechanismus. Typischerweise "action_data" für von Agenten vermittelte Signale.
dimension_influence {Dimension: Stärke} Welche UICE-Dimensionen dieses Signal beeinflussen und wie stark. Schlüssel: "Dringlichkeit", "Wirkung", "Selbstvertrauen", "Anstrengung". Stärken: "stark", "mäßig", "schwach"
Auslegung string Natürlichsprachliche Beschreibung dessen, was das Signal für die Bewertung bedeutet – in die LLM-Eingabeaufforderung eingeschleust
Zuverlässigkeit string Wie zuverlässig dieses Signal ist: "hoch", "mittler", "niedrig"
erforderlich boolean Gibt an, ob das Signal für die Bewertung vorhanden sein muss.
fetch_info object Steuert, wo und wie der Signalwert zur Bewertungszeit abgerufen wird.

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

Parameter Typ Required Description
msdyn_ActionId string Yes Die eindeutige Kennung des Agenten für diese Aktion. Wird für die Deduplizierung und Zustandssynchronisierung verwendet. Muss deterministisch sein (gleiche Aktion = gleiche ID). Beispielformat: DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId string Yes Agenten-Identifikator. Muss mit dem msdyn_agentname im Agenten-Konfigurationsrecord übereinstimmen. Beispiel: "DealClosingAgent"
msdyn_TargetEntityId eindeutiger Bezeichner (GUID) Yes GUID des Zieldatensatzes (Opportunity, Lead), auf das sich diese Aktion bezieht
msdyn_TargetEntityTypeName string Yes Logischer Name der Zielentität. Beispiel: "Chance", "Lead"
msdyn_ActionReason string Yes Grund, warum die Aktion generiert wurde. Wird von der Scoring-Engine für die Zuordnung von Prinzipien verwendet.
msdyn_ActionUIPayload string No JSON-Payload für das Rendern der Karte. Wenn sie weggelassen wird, kann der Recommended Actions Agent die Karte nicht anzeigen.
msdyn_ActionPrioritizationData string No JSON mit agentenspezifischen Daten zur Bewertungswertung
msdyn_ActionCTA string No Zeichenfolge vom Typ CTA. Beispiel: "E-Mail", "Bewertung", "Anruf"
msdyn_PrioritizationPrinciples string No JSON-Array von Priorisierungsprinzipien, zu der diese spezifische Aktion zugeordnet ist (kann die Zuordnung auf Agentebene außer Kraft setzen)

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:
Parameter Typ Description
actionid GUID Die Aktionskennung
state string "Erledigt" oder "Entlassen"

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.

Parameter Typ Required Description
msdyn_ActionId string Yes Der Aktionsbezeichner (derselbe wie der gepushte)
msdyn_ActionState integer Yes Neuer Zustand — Werte (auf MarkAsDone/Dismissed abgebildet)
msdyn_TargetEntityId eindeutiger Bezeichner Yes Zielentitäts-GUID
TargetEntityTypeName string Yes Logischer Name der Zielentität
msdyn_TrackingId string No Optionale Nachverfolgungs-/Korrelations-ID

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:

Konfigurationsfeld Wert von Sales Opportunity Agents (aus OraDefaults.cs)
msdyn_agentname "SalesOpportunityAgent"
msdyn_agentimpactmapping ["DealRisk", "Deal Velocity"]
msdyn_syncactionexecutionstateapiconfig {"syncactionuistatusapiname":"msdyn_SyncDealRiskActionFromNba"}
msdyn_internalprioritizationinstruction Sehen Sie sich den Produktionswert des Sales Opportunity Agents an

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:

Push-Parameter Wert von Sales Opportunity Agents
msdyn_ActionId DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId "DealRiskAgent"
msdyn_TargetEntityTypeName "Gelegenheit"
msdyn_ActionReason Risikobeschreibung aus Forschung
msdyn_ActionUIPayload Karte mit Risikokopf + Beschreibung
msdyn_ActionPrioritizationData {"riskType":"8","risk":"Missing BANT Info"} (Beispiel)

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 .
  • Last updated on