שילוב סוכנים מותאמים אישית עם סוכן הפעולות המומלצות

סוכן הפעולות המומלצות ב-Dynamics 365 Sales מציג המלצות עם עדיפות להזדמנויות, לידים, חשבונות ואנשי קשר. הוא מספק צינור ניקוד משותף, חוזי נתונים וסנכרון מצב דו-כיווני כך שכל סוכן מותאם אישית יוכל להציג המלצות לצד סוכני צד ראשון.

מאמר זה מתאר את הארכיטקטורה, הרכיבים המרכזיים, חוזי הנתונים וזרימת האינטגרציה שבה משתמשים כאשר סוכן מותאם אישית משתלב עם סוכן הפעולות המומלצות. הוא מספק את הידע הבסיסי הנדרש ליישום אינטגרציה.

דרישות מוקדמות

• הפתרון NextBestActionAgent הופעל לארגון היעד. למידע נוסף, ראו ייבוא סוכן לסביבת יעד.

• מחרוזת SourceAgentId יציבה וייחודית עבור הסוכן המותאם אישית. למידע נוסף, ראו הוספת סוכנים מותאמים אישית לפעולות מומלצות.

• נדרשות ההרשאות הבאות כדי לדחוף את הפעולות המומלצות:

  טבלה	ההרשאות הנדרשות	היקף
  msdyn_rawactioncatalogue	לקרוא, לכתוב, להוסיף ולנספח	כללי
  msdyn_prioritizedactioncatalogue	לקרוא, לכתוב, להוסיף ולנספח	כללי
  msdyn_recommendedactionsourceagentconfig	קרא	כללי
  msdyn_salesagentprofile	קרא	כללי

ארכיטקטורת אינטגרציה

אינטגרציית סוכן הפעולות המומלצות משתמשת בצינור עיבוד שסופג פעולות גולמיות מסוכני מקור, מדרג אותן באמצעות מנוע ניקוד UICE (דחיפות, השפעה, ביטחון, מאמץ), ומציג את התוצאות המועדפות בקרוסלת המוכר.

צינור העיבוד פועל כך:

1. הסוכן המותאם מזהה תובנה מעשית (למשל, סיכון עסקה, עסקה תקועה, או בעל עניין חסר).
2. הסוכן המותאם קורא ל-API msdyn_PushActionDataToRecommendedActionAgent המותאם אישית כדי לדחוף את הפעולה.
3. הפעולה נשמרת ב msdyn_rawactioncatalogue (טבלת הקלט).
4. עבור כל פעולה, מנוע הניקוד:
   • מביא אותות ישות מ- Dataverse.
   • מביא נתוני סדר עדיפויות ספציפיים לסוכן מקטלוג הפעולה.
   • קורא ל-LLM לדרג את הפעולה על ממדי UICE (דחיפות, השפעה, ביטחון, מאמץ).
   • מיישם כללי רצפה ותקרה.
   • מחשב את ציון העדיפות הסופי באמצעות GetRecommendedActionAgentResponse.
5. הפעולה המדורגת מוכנסת לתוך msdyn_prioritizedactioncatalogue (טבלת הפלט).
6. קרוסלת הפעולות המומלצות מביאה פעולות עם ניקוד ומרנדרת כרטיסים בתצוגת הרשימה של הישות, בתנאי שהקרוסלה מופעלת עבור אותה ישות.

רכיבים מרכזיים

האינטגרציה מתבססת על טבלאות וממשקי API של Dataverse הבאים.

רכיב	מיקום	תיאור
טבלת קלט	msdyn_rawactioncatalogue (Dataverse)	פעולות גולמיות שסוכנים מותאמים אישית שולחים
טבלת פלט	msdyn_prioritizedactioncatalogue (Dataverse)	פעולות עם ניקוד ופעולות מדורגות עבור ממשק המשתמש
תצורת סוכן	msdyn_recommendedactionsourceagentconfig (Dataverse)	רישום ותצורה עבור כל סוכן
API לדחיפה	msdyn_PushActionDataToRecommendedActionAgent (API מותאם אישית)	סוכן → פעולות מומלצות דחיפת פעולת סוכן

רישום סוכן

רשמו סוכנים מותאמים אישית עם סוכן הפעולות המומלצות כדי שהפלטפורמה תזהה ותמשוך את הפעולות שלהם. למידע נוסף על רישום סוכנים, ראו הוספת סוכנים מותאמים אישית לפעולות מומלצות.

כשאתה רושם סוכן, נוצר ערך ב- msdyn_recommendedactionsourceagentconfig. SourceAgentId הייחודי מזהה את הערך עבור הסוכן המותאם אישית.

תצורת סוכן

הטבלה msdyn_recommendedactionsourceagentconfig מחזיקה תצורה לכל סוכן שמכתיבה כיצד סוכן הפעולות המומלצות מפרש את פעולות הסוכן. שני השדות החשובים ביותר לאכלוס הם msdyn_internalprioritizationinstruction ו- msdyn_syncactionexecutionstateapiconfig.

ניתן להחיל קונפיגורציה על ידי עדכון ידני של רשומת הטבלה או על ידי קריאה ל-API UpsertRecommendationAgentConfigRequestהמותאם אישית .

סכימת UpsertRecommendationAgentConfigRequest

הדוגמה הבאה מציגה את שדות הקונפיגורציה הזמינים בסכימה.

{
  "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	סוג	תיאור
שם סוכן	מחרוזת	מפות ל-msdyn_agentname (מקסימום 850 תווים). נדרש עבור רשומות חדשות.
סוג סוכן	מחרוזת	קטגוריית סוכן. השתמש ב"CustomAgent" כדי ליצור פרופיל אוטומטית.
isRecommendedActionAgentEnabled	בוליאני	ממופה אל msdyn_isrecommendedactionagentenabled. Null = השאר ללא שינוי.
salesAgentProfileId	guid?	קישורים ל-msdyn_salesagentprofile. משמש לאיתור רשומות בעת Upsert.
AgentImpactMapping	מחרוזת	מערך JSON שטוח של שמות עקרונות. ממפה אל msdyn_agentimpactmapping.
הוראתתעדוףפנימית	מחרוזת	JSON עם מערך אותות. ממופה אל msdyn_internalprioritizationinstruction.
syncActionExecutionStateApiConfig	מחרוזת	אובייקט JSON {"syncactionuistatusapiname":"..."}. מפות msdyn_syncactionexecutionstateapiconfig.
sourceAgentUniqueId	מחרוזת	ממפה אל msdyn_sourceagentuniqueid.
תיאור	מחרוזת	מפות ל-msdyn_sourcedescription (מקסימום 1000 דמויות).

הוראת קביעת סדרי עדיפויות פנימיים

הוראת העדיפות הפנימית מכילה מטא-דאטה של אות ספציפי לסוכן שמסביר למנוע הניקוד כיצד לפרש את שדות נתוני התעדוף של סוכן. זה אובייקט JSON עם מערך ברמה signals עליונה. כל אות מפוענח ל- AgentSignalInstructionConfig עם השדות הבאים:

שדה	סוג	תיאור
שם	מחרוזת	מזהה אות — משמש כמפתח בסעיף ההתייחסות לאות בהנחיות הניקוד
סוג נתונים	מחרוזת	סוג נתונים: "מחרוזת", "מספר", "בוליאני"
מקור	מחרוזת	תווית תיאורית עבור המקור של האות. לא משמש לניתוב — fetch_info.fetch_type שולט במנגנון השליפה עצמו. בדרך כלל "action_data" עבור אותות שהסוכן דוחף.
השפעת_ממד	{ממד: כוח}	על אילו ממדי UICE אות זה משפיע ועל החוזק שלו. מפתחות: "דחיפות", "השפעה", "ביטחון", "מאמץ". חוזקות: "חזק", "בינוני", "חלש"
פרשנות	מחרוזת	תיאור בשפה טבעית של משמעות האות לצורך ניקוד — שמוזן אל הנחיית ה-LLM
מהימנות	מחרוזת	כמה אמין האות הזה: "גבוה", "בינוני", "נמוך"
נדרש	בוליאני	אם האות חייב להיות קיים עבור ניקוד
fetch_info	אובייקט	קובע היכן וכיצד ערך האות מאוחזר בזמן ניקוד.

דוגמה לבלוק אותות:

{
  "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 של מצב ביצוע פעולת סינכרון

קונפיגורציית API למצב ביצוע פעולות סינכרון היא אובייקט JSON שמגדיר את שם ה-API המותאם אישית שסוכן הפעולות המומלצות קורא לו כאשר מוכר פועל על כרטיס (למשל, מסמן אותו כמלא או לא רלוונטי). API זה מגדיר את מצב הפעולה בסוכן המותאם אישית של המקור.

{
  "syncactionuistatusapiname": "your_SyncBackCustomApiName"
}

חוזה דחיפת פעולה

סוכנים מותאמים אישית דוחפים פעולות באמצעות ה-API המותאם msdyn_PushActionDataToRecommendedActionAgent אישית. ה-API נקרא בכל פעם שהסוכן מייצר או מעדכן פעולה עבור ישות יעד.

בקש פרמטרים

פרמטר	סוג	חובה	תיאור
msdyn_ActionId	מחרוזת	‏‏כן‬	המזהה הייחודי של הסוכן עבור פעולה זו. משמש לצורך שכפול וסינכרון מצב. חייב להיות דטרמיניסטי (אותה פעולה = אותו מזהה). תבנית לדוגמה: DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId	מחרוזת	‏‏כן‬	מזהה של סוכן. חייב להתאים את msdyn_agentname ברשומת הקונפיגורציה של הסוכן. דוגמה: "סוכן סגירת עסקה"
msdyn_TargetEntityId	מזהה ייחודי (GUID)	‏‏כן‬	GUID של רשומת היעד (הזדמנות, ליד) שאליה מתייחסת פעולה זו
msdyn_TargetEntityTypeName	מחרוזת	‏‏כן‬	השם הלוגי של ישות היעד. דוגמה: "הזדמנות", "מוביל"
msdyn_ActionReason	מחרוזת	‏‏כן‬	הסיבה לכך שהפעולה נוצרה. משמש את מנגנון הניקוד עבור מיפוי עקרונות.
msdyn_ActionUIPayload	מחרוזת	לא	מטען JSON להצגת כרטיס. אם זה מושמט, סוכן הפעולות המומלצות לא יכול להציג את הכרטיס.
msdyn_ActionPrioritizationData	מחרוזת	לא	JSON עם נתונים ספציפיים לסוכן עבור ניקוד
msdyn_ActionCTA	מחרוזת	לא	מחרוזת מסוג CTA. דוגמה: "אימייל", "ביקורת", "שיחה"
msdyn_PrioritizationPrinciples	מחרוזת	לא	מערך JSON של עקרונות קביעת סדרי עדיפויות שפעולה ספציפית זו ממופה לה (יכולה לעקוף מיפוי ברמת הסוכן)

דוגמה: קריאת פלאגין 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"];

חוזה תוכן מנה בממשק משתמש של פעולה

השדה msdyn_ActionUIPayload מכיל מטען JSON ששולט כיצד קלף פעולה מופיע בקרוסלת סוכן הפעולות המומלץ.

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

חוזה נתוני תעדוף

השדה msdyn_prioritizationdata מאפשר לסוכן להעביר אותות ספציפיים לסוכן שמשפיעים על האופן שבו מנוע הניקוד של UICE מעדיף פעולה.

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

מנוע הניקוד קורא אותות אלה לצד אותות ברמת ישות (ערך עסקה, שלב, מתחרים וכדומה). ה־msdyn_internalprioritizationinstruction בתצורת הסוכן מנחה את מודל השפה כיצד לפרש כל סיגנל, ומנוע הניקוד משלב את כל הסיגנלים בפרומפט הניקוד של UICE.

הפעלת קרוסלת פעולות מומלצות

הפעל את קרוסלת הפעולות המומלצות כדי שתופיע בתצוגת רשימת הישות. הישות aiinsightcard שולטת במצב ההפעלה של הקרוסלה עבור כל ישות. ודא שהרשומה המתאימה aiinsightcard לישות מוגדרת לפעילה.

הטבלה הבאה מציגה את הערכים שיש להגדיר להפעלה או כיבוי הקרוסלה עבור ישות:

מצב הקלף	statecode	statuscode
פעילות	0	1
לא פעילים	1	2

הגרסאות של פעולות וביטול הפעולה

כאשר סוכן מעדכן נתונים עבור פעולה שנדחפה קודם, הוא יוצר רשומה חדשה עם אותה msdyn_ActionId פעולה על ידי קריאה msdyn_PushActionDataToRecommendedActionAgent חוזרת. המערכת יוצרת שורה חדשה ב-msdyn_rawactioncatalogue עם אותו msdyn_actionid אבל עם msdyn_rawactioncatalogueid חדש. סוכן הפעולות המומלצות ממשיך להציג את הגרסה הישנה עד שהוא מעבד את הגרסה החדשה.

כדי לבטל פעולה (למשל, כאשר סיכון נפתר), הסוכן קורא ל-API msdyn_RAAgent_RemoveActionsV2 המותאם אישית עם ה- actionId. פעולה זו מסמנת את כל msdyn_rawactioncatalogue הרשומות של אותה פעולה כלא פעילות, והכרטיס נעלם מהקרוסלה.

סנכרון מצב דו-כיווני

מצב הפעולה מסונכרן הן בקרוסלת סוכן הפעולות המומלצות והן בסוכן המותאם אישית שלך, כדי להבטיח שהמוכרים רואים מידע עקבי ללא קשר למקום שבו הם פועלים בפעולה.
פעולות מומלצות לסוכן → סוכן מותאם אישית (המוכר פועל בקרוסלה): כאשר מוכר מסמן פעולה כ'בוצעה או נדחתה ' בקרוסלה:

1. הסוכן 'פעולות מומלצות' מעדכן את msdyn_actionuistatus ב-msdyn_prioritizedactioncatalogue.
2. סוכן הפעולות המומלצות קורא את ה-msdyn_syncactionexecutionstateapiconfig מתצורת הסוכן.
3. הסוכן לפעולות מומלצות קורא ל-API המותאם אישית של הסוכן עם:

פרמטר	סוג	תיאור
actionid	GUID	מזהה הפעולה
המדינה	מחרוזת	"סומן כהושלם" או "נסגר"

הסוכן חייב ליישם API מותאם אישית שמקבל את שני הפרמטרים הללו ומעדכן את מצב הפעולה במאגר הנתונים שלו.

סוכן מותאם אישית → סוכן הפעולות המומלצות (המוכר פועל בממשק המשתמש של הסוכן): כאשר מוכר פועל על פעולה בממשק המשתמש של הסוכן עצמו (למשל, מסמן אותה כמתוקנת בדף סוכן מותאם אישית), הסוכן מסנכרן את המצב הזה לסוכן הפעולות המומלצות על ידי קריאה msdyn_SyncActionExecutionStateFromAgentל-. פעולה זו מעדכנת את המצב בטבלת הפלט של סוכן הפעולות המומלצות, ומסתירה אותו מהקרוסלה.

פרמטר	סוג	חובה	תיאור
msdyn_ActionId	מחרוזת	‏‏כן‬	מזהה הפעולה (זהה לזה שנשלח)
msdyn_ActionState	מספר שלם	‏‏כן‬	מצב חדש — ערכים (ממופים ל-MarkAsDone/Dismissed)
msdyn_TargetEntityId	uniqueidentifier	‏‏כן‬	GUID של ישות יעד
TargetEntityTypeName	מחרוזת	‏‏כן‬	שם לוגי של ישות יעד
msdyn_TrackingId	מחרוזת	לא	מזהה מעקב/קורלציה אופציונלי

בדיקות וולידציה

לאחר ההגדרה והיישום, יש לאמת את זרימת הקצה לקצה על ידי ביצוע הבדיקות הבאות.

אימות תצורת הסוכן:

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

בצע פעולת בדיקה על ידי קריאה ל-msdyn_PushActionDataToRecommendedActionAgent וודא כי msdyn_IsSuccess הוא true וכי רשומה חדשה מופיעה ב-msdyn_rawactioncatalogue.

הפעל ניקוד לפי דרישה על ידי שיחות msdyn_RAAgent_TriggerRecommendedActionsAgentOrchestration (במקום להמתין לטיימר של 4 שעות).

אימות התוצאה המדורגת:

    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

ערכים צפויים:

• msdyn_actionscore מאוכלס בערך בטווח 0-10.
• msdyn_hascrossedfloor שקרית (הפעולה מעל הרצפה ומופיעה בקרוסלה).
• msdyn_actionuistatus הוא 1 (פעיל).
• msdyn_scoredetails מכיל את ההסבר שנוצר על-ידי LLM.

אמת את תצוגת הקרוסלה על ידי פתיחת טופס Opportunity ב-Dynamics 365 Sales ובדיקת סעיף הפעולות המוצעות. אימות סנכרון מצב על ידי ביטול פעולה בקרוסלה (יש לקרוא ל-API של הסינכרון חזרה עם state = "Dismissed") ועל ידי סימון פעולה בממשק הסוכן (רשומת טבלת הפלט צריכה לשקף את העדכון msdyn_actionuistatus).

דוגמה: סוכן הזדמנויות מכירה

סוכן הזדמנויות מכירה הוא הסוכן הראשון שמצטרף לסוכן הפעולות המומלצות, ואינטגרציה שלו משמשת כמימוש ייחוס.

ערכי קונפיגורציה של סוכן:

שדה Config	ערך סוכן הזדמנויות מכירה (מ-OraDefaults.cs)
msdyn_agentname	"סוכן הזדמנויות מכירות"
msdyn_agentimpactmapping	["סיכון עסקה", "מהירות עסקה"]
msdyn_syncactionexecutionstateapiconfig	{"syncactionuistatusapiname":"msdyn_SyncDealRiskActionFromNba"}
msdyn_internalprioritizationinstruction	ראו את ערך הייצור של סוכן הזדמנויות המכירה

כאשר מחקר של סוכן הזדמנויות מכירות משלים ומזהה סיכוני עסקה, DealRiskToNBAService דוחס כל סיכון כפעולה נפרדת:

פרמטר דחיפה	ערך סוכן הזדמנויות מכירה
msdyn_ActionId	DealRisk_{opportunityId}_{riskType}
msdyn_SourceAgentId	"DealRiskAgent"
msdyn_TargetEntityTypeName	"הזדמנות"
msdyn_ActionReason	תיאור סיכון ממחקר
msdyn_ActionUIPayload	כרטיס עם כותרת הסיכון + תיאור
msdyn_ActionPrioritizationData	{"riskType":"8","risk":"Missing BANT Info"} (דוגמה)

התנהגות סנכרון מצבים:

• סוכן הזדמנויות מכירה → הפעולות המומלצות לסוכן: כאשר מוכר מסמן סיכון כמבוצע בדף המחקר, הסוכן מתקשר msdyn_SyncActionExecutionStateFromAgentל-.
• סוכן הפעולות המומלצות → סוכן הזדמנויות המכירה: כאשר מוכר סוגר כרטיס בקרוסלה, סוכן הפעולות המומלצות קורא ל-ora_UpdatedActionStateFromRAAgent (כפי שמוגדר בתצורת הסוכן).

מידע קשור

• הגדרת סוכן הפעולות המומלצות
• מבט כולל על פעולות מומלצות