פרמטרים של Playbook

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

הצהרה על פרמטר

אפשר להגדיר פרמטרים של קלט (קריאה) ופרמטרים של פלט (כתיבה).

לפרמטרים יש שם, תיאור ואחד מהסוגים הבאים:

• מחרוזת
• מספר
• בוליאני
• סוג פרמטר שספציפי לכלי

אפשר גם לציין אם פרמטר הוא רשימה.

פרמטרים של קלט (קריאה)

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

פרמטרים של קלט מוגדרים לכל playbook, ובאופן כברירת מחדל, ל-playbooks אין גישה לסוגים אחרים של פרמטרים במסוף Dialogflow CX. כשמעבירים זרימת עבודה ל-Playbook, פרמטרים של דף וסשן מועברים ל-Playbook אם ל-Playbook היעד יש פרמטר קלט באותו שם. כדי להעביר מידע מזרימה ל-Playbook במהלך מעבר, צריך להגדיר פרמטרים של קלט ל-Playbook עם אותו שם כמו של פרמטר של סשן או של דף שקיים לפני המעבר.

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

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

פרמטרים של פלט (כתיבה, החזרה)

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

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

העברת פרמטרים

הערה: אי אפשר להפעיל תרחיש של העברת פרמטרים מתוך תוכנית פעולה למשימה, ולכן הוא לא מתואר בהמשך.

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

חוברת הדרכה לתרחישים

כדי להעביר פרמטרים מ-Playbook שגרתי לזרימת עבודה:

• הגדרת פרמטרים של כתיבה ל-playbook השגרתי. הפרמטרים האלה יהפכו לפרמטרים של סשן.
• רצפי פעולות יכולים להשתמש בפרמטרים של הסשן.
• הכללת שימוש בפרמטרים בהוראות ובדוגמאות.

מדריך ליצירת תרחישים

כדי להעביר פרמטרים מזרימת עבודה ל-Playbook של שגרה:

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

פלייבוק של משימות לזרימה

כדי להעביר פרמטרים מ-playbook של משימה לזרימה:

• בהגדרות של התהליך, מגדירים פרמטרים של קלט עם אותם שמות.
• הכללת שימוש בפרמטרים בהוראות ובדוגמאות.

רשימת השלבים למשימות

כדי להעביר פרמטרים מזרימה ל-playbook של משימת אב:

• בהגדרות הפיד, מגדירים פרמטרים של החזרת מוצרים.
• הכללת שימוש בפרמטרים בהוראות ובדוגמאות.

כדי להעביר פרמטרים מזרימת עבודה ל-playbook של משימת צאצא:

• מגדירים ב-Flow פרמטרים של קלט למשימה ששמם זהה לשם של פרמטרים של סשן.
• הכללת שימוש בפרמטרים בהוראות ובדוגמאות.

העברה מפלייבוק של תרחיש לפלייבוק של משימה

כדי להעביר פרמטרים מ-playbook שגרתי ל-playbook של משימה:

• מגדירים פרמטרים של קלט ל-playbook של המשימה עם אותם שמות.
• הכללת שימוש בפרמטרים בהוראות ובדוגמאות.

דוגמה לשימוש בכלים

כדאי להשתמש בסוכן שנועד למכירת כרטיסים לאירועים עם תוכניות הפעולה הבאות:

1. ספר הפעלה בשם Ticket ordering שמבצע הזמנות באמצעות כלי בשם Ticket sales API.
   1. ה-playbook הזה מקבל פרמטר קלט עם הסוג number והשם event_id.
   2. הכלי Ticket sales API מצפה לקבל בקשה שכוללת event_id.
2. מדריך הפעלה בשם Event selection שעוזר למשתמשים לבחור אירוע ואז מעביר אותם אל Ticket ordering עם הפרמטר event_id כדי לרכוש כרטיסים.

בדוגמה הזו, כדי לוודא שהערך event_id מועבר בצורה מהימנה מ-Event selection אל Ticket ordering ומ-Ticket ordering אל Ticket sales API, צריך כמה דוגמאות.

המדריך Ticket ordering צריך לכלול כמה דוגמאות שבהן:

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

המדריך Event selection צריך לכלול כמה דוגמאות שבהן:

• כוללים אמירה של משתמש שבה הוא בוחר אירוע עם פרמטרים מציאותיים event_id, שונים בכל דוגמה.
• כוללים קריאה ל-playbook של Ticket ordering שבה מוגדר הפרמטר event_id לערך זהה לערך הריאליסטי של event_id שנבחר על ידי המשתמש.

בנוסף להוספת דוגמאות, כדאי להוסיף הוראות ספציפיות לפרמטרים instructions,‏ goal או tool details כדי להסביר איך להשתמש בהם. לדוגמה, מחברת ההפעלה Ticket ordering כוללת את ההוראה הבאה:

- Use parameter event_id to send a buy_tickets request with ${TOOL: Ticket sales API}

בדוגמאות ובהוראות שצוינו, Event selection playbook מחליט בצורה נכונה על event_id על סמך הבחירה של המשתמש, ומעביר אותו כפרמטר קלט בשם event_id אל Ticket ordering playbook. לאחר מכן, Ticket ordering מעביר את אותו event_id בגוף הבקשה אל Ticket sales API. המדריכים האלה מסתמכים על דוגמאות עם ערכי פרמטרים שונים כדי להסיק איך צריך להשתמש בפרמטרים.