Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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:
- Der Custom Agent erkennt eine umsetzbare Erkenntnis (zum Beispiel ein Deal-Risiko, ein gestopptes Geschäft oder einen fehlenden Stakeholder).
-
Der benutzerdefinierte Agent ruft die benutzerdefinierte
msdyn_PushActionDataToRecommendedActionAgentAPI auf, um die Aktion zu pushen. - Die Aktion wird in
msdyn_rawactioncatalogue(Eingabetabelle) gespeichert. - 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.
- Die bewertete Aktion wird in
msdyn_prioritizedactioncatalogue(Ausgabetabelle) eingefügt. - 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.
| Komponente | Location | Description |
|---|---|---|
| Eingabetabelle | msdyn_rawactioncatalogue (Dataverse) | Unverarbeitete Aktionen, die benutzerdefinierte Agenten übermitteln |
| 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 → Push-Aktionen im Agent für empfohlene Aktionen |
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"
}
| JSON-Feld | Typ | Description |
|---|---|---|
| Agentenname | string | Wird msdyn_agentname zugeordnet (max. 850 Zeichen). Erforderlich für neue Datensätze. |
| Agententyp | string | Agent-Kategorie. Verwenden Sie "CustomAgent", um ein Profil automatisch zu erstellen. |
| isRecommendedActionAgentEnabled | boolean | Zugeordnet 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 Prinzipnamen. 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 | Wird msdyn_sourcedescription zugeordnet (max. 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 in AgentSignalInstructionConfig mit den folgenden Feldern deserialisiert:
| Feld | Typ | Description |
|---|---|---|
| Name | string | Signalbezeichner – wird als Schlüssel im Abschnitt „Signalreferenz“ der Bewertungsaufforderung 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 gesendete Signale. |
| Dimensionseinfluss | {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 | Beschreibung in natürlicher Sprache, was das Signal für die Bewertung bedeutet – in den LLM-Prompt eingefügt |
| 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 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
| 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 den 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 für die Bewertung |
| 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
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:
| Kartenzustand | statecode |
statuscode |
|---|---|---|
| Aktiv | 0 |
1 |
| Inaktiv | 1 |
2 |
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:
- Der Agent für empfohlene Aktionen aktualisiert das
msdyn_actionuistatusinmsdyn_prioritizedactioncatalogue. - Der Recommended Actions Agent liest die
msdyn_syncactionexecutionstateapiconfigaus der Agent-Konfiguration. - Recommended Actions Agent ruft die benutzerdefinierte API des Agenten auf:
| Parameter | Typ | Description |
|---|---|---|
| actionid | GUID | Die Aktionskennung |
| state | string | "Als erledigt markiert" oder "Verworfen" |
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.
| Parameter | Typ | Required | Description |
|---|---|---|---|
| msdyn_ActionId | string | Yes | Der Aktionsbezeichner (derselbe wie der gepushte) |
| msdyn_ActionState | integer | Yes | Neuer Status — 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
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_actionscorewird mit einem Wert im Bereich von 0 bis 10 aufgefüllt. -
msdyn_hascrossedfloorist falsch (die Aktion ist über der Untergrenze und wird im Karussell angezeigt). -
msdyn_actionuistatusist 1 (Aktiv). -
msdyn_scoredetailsenthä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:
| Konfigurationsfeld | Wert von Sales Opportunity Agent (aus OraDefaults.cs) |
|---|---|
| msdyn_agentname | SalesOpportunityAgent |
| msdyn_agentimpactmapping | ["DealRisk", "Deal-Geschwindigkeit"] |
| msdyn_syncactionexecutionstateapiconfig | {"syncactionuistatusapiname":"msdyn_SyncDealRiskActionFromNba"} |
| msdyn_internalprioritizationinstruction | Sehen Sie sich den Produktionswert des Sales Opportunity Agents an |
Wenn die Recherche des Verkaufschancen-Agent abgeschlossen ist und Geschäftsrisiken identifiziert wurden, übermittelt DealRiskToNBAService jedes Risiko als separate Aktion:
| Push-Parameter | Verkaufschancen-Agent – Wert |
|---|---|
| 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:
-
Verkaufschancen-Agent → Agent für empfohlene Aktionen: Wenn ein Verkäufer auf der Rechercheseite ein Risiko als erledigt markiert, ruft der Agent
msdyn_SyncActionExecutionStateFromAgentauf. -
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_UpdatedActionStateFromRAAgentauf (wie in der Agentenkonfiguration festgelegt).