פעולות

הגדירו מה סוכן ה-AI יכול לעשות במהלך שיחה: ממענה לשאלות באמצעות נתוני API בזמן אמת ואיסוף לידים ונתוני מחקר שוק ועד ביצוע משימות מותאמות אישית.

סוכני Quickchat AI תומכים בשני סוגי פעולות.

פעולות Quickchat AI מובנות במוצר, ולכן צריך רק להפעיל ולהגדיר אותן:

• העברה לנציג מעבירה את השיחה לאדם.
• איסוף נתונים חכם אוסף לידים ונתונים אחרים במהלך הצ’אט.

פעולות מותאמות אישית פונות למערכות מחוץ ל-Quickchat AI:

• פעולות API קוראות לכל נקודת קצה של HTTP. הן מתוארות בדף הזה.
• פעולות MCP מחברות שרת MCP שלם בבת אחת.
• Google Sheets הוא קיצור דרך שמגדיר עבורכם פעולת רישום בלחיצה אחת.

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

כלי הגדרה אופציונליים

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

• בדיקת חיבור MCP לדוגמה. אתחלו חיבור וקבלו רשימת כלים בנקודת הקצה של תיעוד Cloudflare או Microsoft Learn בלבד. הכלי אינו מבצע כניסה לחשבון או הפעלת כלים.

פעולות מותאמות אישית

פעולות מותאמות אישית מאפשרות ל-AI לקרוא לכלים חיצוניים במהלך שיחה: לחפש במערכות פנימיות, ליצור פניות, לשלוח התראות או להביא נתונים עדכניים שאינם במאגר הידע. הן נמצאות בפעולות ו־MCP, תחת פעולות מותאמות אישית.

לחצו על + הוספת פעולה כדי ליצור פעולה. התפריט מציע:

• פעולת API: קריאה לכל נקודת קצה של REST באמצעות HTTP. זו האפשרות הכללית ביותר; השתמשו בה לכל שירות שיש לו כתובת URL ומקבל JSON.
• MCP: חברו שרת MCP חיצוני בלחיצה אחת ואפשרו ל-AI להשתמש בכלים שהוא חושף. ראו פעולות MCP.
• פעולת HubSpot: חיבור מוכן ל-CRM של HubSpot. השתמשו בו לעבודה עם אנשי קשר, עסקאות ופניות, כולל הוספת הערות פרטיות לפניות, בלי לנהל בעצמכם אסימוני API.
• פעולת Discord: התקנת תבניות פעולת API ניתנות לעריכה לתמיכה ולניהול תוכן. נדרשת אפליקציית Discord משלכם. ראו פעולות Discord.
• Google Sheets: קריאה וכתיבה בגיליון אלקטרוני שאתם מחברים.
• Shopify MCP: חברו חנות Shopify באמצעות שרת Shopify Storefront MCP כדי לאפשר ל-AI לחפש בקטלוג ובמדיניות החנות, לקרוא פרטי מוצרים ולבנות עגלת קניות. אפשר ליצור רק פעולת Shopify MCP אחת לכל תרחיש. היא אינה כוללת חיפוש הזמנות; ראו את ההערה בהמשך.

Note

המונה נותרו: N לצד הכפתור + הוספת פעולה מציג כמה פעולות התוכנית שלכם מאפשרת להשאיר פעילות. בנפרד מכך, כל סוכן יכול להכיל לכל היותר 15 פעולות בסך הכול, ללא קשר לתוכנית. שדרגו את התוכנית אם דרושות לכם פעולות פעילות נוספות, או פנו אלינו.

סטטוס הזמנה דורש פעולה נפרדת

Shopify Storefront MCP מיועד ללקוחות ואינו חושף נתוני הזמנות, ולכן סוכן AI שמחובר רק באמצעותו אינו יכול לחפש הזמנה של לקוח. סטטוס הזמנה מתקבל מפעולת API נפרדת בשם בדיקת סטטוס הזמנה, שקוראת ל-Shopify Admin API ומוגדרת אוטומטית כשמתקינים את אפליקציית Quickchat מתוך Shopify App Store. לחנויות שחוברו בהדבקת כתובת URL אין גישת Admin ולכן אין חיפוש הזמנות. התקינו מחדש דרך ה-App Store אם אתם זקוקים לכך.

איך פעולות מותאמות אישית פועלות

1. בחרו סוג פעולה: פעולת API, ‏MCP, פעולת HubSpot, פעולת Discord, ‏Google Sheets או Shopify MCP. הגדירו את החיבור ואת ההוראות הדרושות ל-AI.
2. במהלך צ’אט, ה-AI משתמש בדרך כלל בתיאור הפעולה ובפרטי הכלים או הפרמטרים הזמינים כדי להחליט מתי להפעיל אותה. לחלופין, פעולת API יכולה לרוץ אוטומטית לפני התשובה הראשונה או כאשר תנאי מטא־נתונים מתקיימים לראשונה.
3. Quickchat מבצעת את הקריאה. בפעולה שנבחרה על ידי ה-AI או שמופעלת לפני התשובה הראשונה, ה-AI יכול להשתמש בתגובה. פעולה שמופעלת על ידי מטא־נתונים רצה בשקט והפלט שלה אינו מתווסף לצ’אט.
4. בדקו או חברו את הפעולה מתוך העורך שלה לפני השימוש בה בשיחות.

Tip

כתבו את התיאור כהוראה ל-AI. ציינו מתי להשתמש בפעולה, מה היא מחזירה ואילו מגבלות חלות עליה (למשל, “יש לקרוא לפעולה רק כשהמשתמש מספק מספר הזמנה”).

יצירת טיוטות של פעולות מתוך תיאור

1. בפעולות ו־MCP, בחרו + הוספת פעולה > פעולת API.
2. תארו את התהליך, מתי הסוכן צריך לפעול, באילו ממשקי API להשתמש (או צרפו קישור לתיעוד שלהם) ואיזה מידע דרוש לכל שלב. לחצו על יצירה.
3. Quickchat מכינה עד ארבע טיוטות חדשות של פעולות API, כולן לא פעילות. התוצאה עשויה להמליץ על פעולות קיימות במקום ליצור כפילויות, או לבקש פרטים נוספים. יצירת טיוטות אינה מפעילה את הפעולות.
4. קראו את פעולות קיימות בשימוש, את דרישות הקדם ואת השלבים הבאים. השלימו את ההגדרה, החליפו ערכי מצייני מקום ובדקו את הבקשה, ההוראות ותנאי ההפעלה של כל פעולה. בדקו כל פעולה לפני הפעלת הטיוטות או פעולה קיימת ולא פעילה שנדרשת לתהליך.

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

יצירת פעולת API

1. עברו אל פעולות ו־MCP.
2. לחצו על + הוספת פעולה בתוך פעולות מותאמות אישית, בחרו פעולת API ואז לחצו על יצירה ידנית.
3. מלאו את פרטים:
   • שם: ברור ותיאורי.
   • תיאור: מתי להשתמש בפעולה ומה לכלול בפרמטרים.
4. תחת מתי להפעיל, בחרו ה־AI מחליט, לפני התשובה הראשונה או כאשר המטא־נתונים תואמים.
5. הגדירו את חיבור:
   • סוג פעולה: שיטת HTTP, כגון GET או POST.
   • כתובת URL של נקודת הקצה של הפעולה: כתובת ה-API המלאה.
   • כותרות: הוסיפו כותרות נדרשות כגון Authorization או content-type: application/json.
6. הגדירו פרמטרים: תנו לכל פרמטר שם, מיקום (query, ‏body או header) ותיאור שמסביר ל-AI איך להרכיב את הערך. ערכי נתיב אינם מיקום של פרמטר; הכניסו אותם ישירות לכתובת נקודת הקצה באמצעות תבניות {{placeholder}}.
7. בצעו בדיקת בקשה ובדקו את התגובה. לאחר מכן לחצו על סיום.

Tip

כל שדה ערך (URL, כותרת, גוף או שאילתה) מקבל מצייני מקום דינמיים דרך הכפתור + הוספת נתוני AI. אפשר להכניס פרמטרי AI, משתני שיחה מובנים ({{scenario_id}}, ‏{{language}}, ‏{{country}}, …) ומטא־נתונים של השיחה ({{metadata_*}}). ראו את התיעוד המלא במשתני פעולות AI.

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

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

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

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

הסעיף מכווץ כברירת מחדל ומציג לצד הכותרת את המצב הפעיל כעת. הרחיבו אותו כדי לשנות מצב.

• ה־AI מחליט: ברירת המחדל. ה-AI קורא את תיאור הפעולה ומחליט אם בקשת המבקר דורשת אותה. השתמשו במצב זה כשהפעולה אמורה לרוץ רק עבור שאלות מסוימות או לאחר שה-AI אוסף מידע מהמבקר.
• לפני התשובה הראשונה: Quickchat מפעילה את הפעולה פעם אחת אחרי שהמבקר שולח את ההודעה הראשונה ולפני שה-AI כותב את התשובה הראשונה. התשובה הרגילה של ה-AI מקבלת את תגובת הפעולה ואת הערכים שנשמרו באמצעות שמירה בזיכרון. ה-AI אינו יכול עוד לבחור בפעולה ככלי, ולכן היא רצה רק בסבב הראשון ולא שוב בהמשך השיחה. השתמשו בה לזיהוי לקוח, לקבלת מידע על החשבון, לבדיקת זכאות או להכנות אחרות שנדרשות בכל שיחה ממשית.
• כאשר המטא־נתונים תואמים: Quickchat בודקת את תנאי להפעיל כאשר של הפעולה אחרי כל סבב של ה-AI, ומפעילה אותה בפעם הראשונה שכל התנאים מתקיימים. ערכים שפעולה אחרת שומרת בזיכרון במהלך הסבב זמינים מיד. ה-AI אינו יכול לבחור בפעולה ככלי, והתגובה שלה אינה מתווספת לצ’אט. השתמשו בה להתראות פנימיות, לעדכוני CRM או לבקשות המשך שצריכות להתרחש אוטומטית כשנתוני שיחה הופכים לזמינים.

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

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

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

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

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

זיהוי באמצעות אימייל או טלפון

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

פעולות HubSpot

פעולת HubSpot פותחת גלריה של פעולות API מוכנות וניתנות לעריכה, שמשתמשות בחשבון HubSpot המחובר שלכם.

התבנית הוספת הערה לפנייה יוצרת הערה פרטית בפניית HubSpot המקושרת לשיחה. שמרו את תוכן ההערה בזיכרון השיחה בתור hubspot_note_body, ואז הוסיפו את התבנית והפעילו אותה. היא מוגדרת מראש עם כאשר המטא־נתונים תואמים וממתינה עד ש-hubspot_note_body וגם hubspot_ticket_id, שמסופק על ידי שרת Quickchat, זמינים. אפשר לערוך את ערך ברירת המחדל של הפרמטר note_body כדי להוסיף טקסט קבוע סביב {{metadata_hubspot_note_body}}.

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

פעולות Discord

פעולת Discord פותחת גלריה של פעולות API מוכנות וניתנות לעריכה:

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

Quickchat יוצרת בצד השרת את שיטת ה-HTTP, ה-URL, הכותרות, הגוף, הפרמטרים, התיאור, הגדרות התגובה ותנאי ההפעלה. הכרטיסים שמתקבלים הם פעולות רגילות של בקשת HTTP. אפשר לבדוק ולערוך כל שדה.

כל שבע תבניות ניהול התוכן כוללות author_is_admin is true תחת להפעיל רק כאשר. Discord מחשבת את הרשאת Administrator של כותב ההודעה הנוכחי, שער Discord מספק את הערך ו-Quickchat בודקת אותו לפני שליחת הבקשה. מטא־נתונים מצ’אט ציבורי או מ-API אינם יכולים להגדיר מפתח זה. בדקו פעולות ניהול תוכן ב-Discord גם עם חשבון מנהל וגם עם חשבון שאינו מנהל; תצוגת ה-AI המקדימה אינה מספקת שולח Discord מורשה.

Caution

אפשר לערוך את פעולות ניהול התוכן. הסרה או החלשה של התנאי author_is_admin is true מסירה את גבול ההרשאה שסופק איתן. פעולות הוצאה וחסימה אינן מבקשות אישור לפני ביצוע.

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

הבוט עצמו עדיין זקוק להרשאת Discord הדרושה לכל בקשה:

פעולה	הרשאה או גישה של הבוט
השתקת חבר לזמן קצוב	Moderate Members
הוצאת חבר	Kick Members
חסימת חבר, ביטול חסימת חבר	Ban Members
הקצאת תפקיד	Manage Roles
הגדרת מצב איטי	Manage Channels
שליחת הכרזה	View Channels ו-Send Messages

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

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

התקנת פניית התמיכה משתמשת ביכולות קיימות של פעולות להעברת נתונים:

1. open_support_ticket יוצרת שרשור פרטי בערוץ שנבחר, לוכדת את $.id ושומרת אותו בזיכרון השיחה בתור discord_ticket_thread_id. היא דורשת discord_message is true, רצה רק בשרת שנבחר ורק כל עוד מפתח הזיכרון הזה אינו קיים.
2. add_ticket_requester קוראת את {{metadata_discord_ticket_thread_id}} ואת {{metadata_discord_author_id}} שסופק על ידי Discord. היא דורשת discord_message is true ורצה רק בשרת שנבחר, לאחר שמזהה השרשור קיים.
3. post_in_ticket קוראת את אותו מזהה שרשור שנשמר, מפרסמת את סיכום הבעיה בן השורה של הסוכן ומאזכרת את המבקש. אם בחרתם תפקיד תמיכה, היא מאזכרת גם אותו. חלים עליה אותם תנאי הודעת Discord, שרת ושרשור שמור. גוף allowed_mentions שלה ב-Discord מוגבל למבקש ולתפקיד, אם הוגדר.

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

discord_ticket_thread_id אינו נמחק אוטומטית. לכן התבנית הבסיסית תומכת בפנייה אחת לכל שיחת Quickchat. פתחו שיחה או שרשור חדשים ב-Discord עבור פנייה נוספת, או ערכו את הפעולות כדי להוסיף את מחזור החיים של הזיכרון הדרוש לכם.

עבור פניית תמיכה, העניקו לבוט את ההרשאות View Channels, ‏Send Messages, ‏Read Message History, ‏Create Private Threads, ‏Send Messages in Threads ו-Manage Threads בערוץ הפניות שנבחר. השאירו את שליחת הודעה לתפקיד (אופציונלי) מוגדר לללא הודעה לתפקיד אם אין צורך לאזכר תפקיד. אם תבחרו תפקיד, עליו להיות ניתן לאזכור ולחבריו צריכה להיות גישה לשרשורים הפרטיים. כשאין תפקידים זמינים שניתן לאזכר, פניות עדיין נפתחות כרגיל ללא התראה לתפקיד. הגלריה מציגה ערוצי טקסט ותפקידים שניתן לאזכר, אך אינה מאמתת את כל שינויי ההרשאות של הערוץ.

Caution

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

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

שמירה בזיכרון

שמרו ערך מקלט של פעולה או מתגובת API בזיכרון השיחה תחת מפתח שתבחרו. פעולות מאוחרות יותר יכולות להשתמש בו שוב בתור {{metadata_<key>}}, והוא מופיע בפרטי השיחה (בתיבת הדואר הנכנס, ב-API ובייצוא).

השתמשו בכך כשפעולה אחת מפיקה מידע שפעולה מאוחרת יותר צריכה. פעולת חיפוש יכולה לשמור customer_id מהתגובה שלה; פעולת המשך שולחת לאחר מכן {{metadata_customer_id}} בלי שה-AI יצטרך להעתיק את הערך.

בעורך פעולת ה-API, פתחו את שמירה בזיכרון והוסיפו שורה:

1. בחרו מקור. תגובת API קוראת את תגובת ה-JSON של ה-API והיא ברירת המחדל לשורות חדשות. קלט הפעולה קוראת את ערכי פרמטרי הקלט שהוגדרו לפעולה.
2. תחת ערך לשמירה, בחרו את הפרמטר מהתפריט עבור קלט הפעולה. עבור תגובת API, הזינו ביטוי JSONPath כגון $.customer_id.
3. בחרו מפתח זיכרון. שמות קלט נפוצים באנגלית לשם, טלפון ואימייל מציעים את מפתח המבקר המתאים. אפשר להשאיר את ההצעה או להזין מפתח משלכם.

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

פרמטר הפעולה	מפתח זיכרון
Name או Full name	visitor_name
Phone number או Phone	visitor_phone_number
Email או Email address	visitor_email

הקלט חייב להיות מוגדר בפעולה. שמירתו באמצעות כלל זיכרון של קלט הפעולה נחשבת לשימוש בפרמטר, כך שאפשר לאסוף אותו לזיכרון בלי לשלוח אותו בבקשת ה-HTTP. מפתחות המבקר האלה ממלאים שדות קשר שלא הוגדרו בתיבת הדואר הנכנס ואת מטא־נתוני השיחה, תוך שימוש באותו אימות כמו איסוף נתונים חכם. פרטי קשר קיימים ושדות שנוקו במפורש על ידי מפעיל נשמרים. כללי תגובת API אינם יכולים לכתוב למפתחות המבקר האלה; השתמשו במפתח מותאם אישית, כגון customer_id, עבור ערכים מתגובת CRM.

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

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

Tip

השתמשו במפתחות snake_case (אותיות, ספרות וקווים תחתונים). אפשר להפנות למפתח כמו customer_id באמצעות {{metadata_customer_id}}; מפתחות הכוללים רווחים או סימני פיסוק אחרים אינם ניתנים לשימוש במצייני מקום. ראו מטא־נתונים של השיחה להסבר על פעולת משתני מטא־נתונים.

להפעיל רק כאשר

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

זה הכלי המתאים לפעולות שדורשות הרשאות או שאינן הפיכות (חסימת חבר, ביצוע החזר כספי, מחיקת רשומה). שורה בפרומפט שאומרת “רק מנהלים יכולים לעשות זאת” היא הוראה מועילה, אך אינה גבול אבטחה: משתמש נחוש יכול להתווכח עם המודל או לנסות הזרקת פרומפט. תנאי הפעלה הוא דטרמיניסטי ונמצא מחוץ לפרומפט, ולכן הוא תקף ללא תלות בתוכן השיחה.

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

הוסיפו תנאים בסעיף להפעיל רק כאשר בעורך הפעולה. בפעולת כאשר המטא־נתונים תואמים, הסעיף נקרא להפעיל כאשר. לחצו על הוספת תנאי, בחרו מפתח מטא־נתונים (למשל telegram_sender_is_admin) ובחרו איך להשוות אותו:

תנאי	מתקיים כאשר ערך המטא־נתונים…
הוא true	נחשב לאמת (truthy)
הוא false	נחשב לשקר (falsy)
קיים	נמצא בשיחה
לא קיים	חסר
שווה ל־	תואם לערך שציינתם
אינו שווה ל־	שונה מהערך שציינתם
הוא אחד מ־	תואם בדיוק לאחד הערכים שברשימה, כולל רישיות ורווחים
מכיל טקסט	הוא טקסט שמכיל את הטקסט המילולי שצוין, עם הבחנה בין אותיות גדולות לקטנות

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

השתמשו בהוא אחד מ־ לחלופות עבור אותו מפתח, והזינו כל חלופה כתגית ערך נפרדת. למשל, modelName is one of [K-65XR95M2, K-75XR95M2, K-85XR95M2] יכול להופיע לצד country equals UK; שתי השורות חייבות להתקיים. אפשר להוסיף עד 50 חלופות, כל אחת באורך של עד 500 תווים. פסיקים הם חלק מילולי מהערך. שורות שווה ל־ נפרדות עם ערכים שונים לאותו מפתח אינן יכולות להתקיים כולן יחד.

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

כשתנאי אינו מתקיים, לא נשלחת בקשה וה-AI אומר למשתמש שאינו יכול לבצע זאת. להלן אותה בקשת חסימה שנחסמת עבור מי שאינו מנהל ומותרת למנהל, כשההבדל היחיד הוא זהות המבקש:

Caution

התנו הפעלה רק במטא־נתונים שQuickchat מגדירה (כגון דגל telegram_sender_is_admin שאומת בערוץ), ולא בערכים שהמבקר יכול להשפיע עליהם. ראו מטא־נתונים של השיחה למקור של כל מפתח.

מסנן תגובה

כברירת מחדל ה-AI רואה את תגובת ה-API המלאה. הוסיפו ביטויי JSONPath בסעיף מסנן תגובה כדי להגביל את ה-AI לחלקים מסוימים ממנה.

שתי סיבות נפוצות לסינון:

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

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

• $.customer.name
• $.orders[*].id

בהינתן תגובת ה-API הבאה:

{
  "customer": {"name": "Ada", "email": "ada@example.com"},
  "orders": [{"id": 101, "total": 25}, {"id": 102, "total": 40}]
}

ה-AI מקבל את התגובה המסוננת הבאה, שבה customer עדיין אובייקט ו-orders עדיין מערך אובייקטים:

{
  "customer": {"name": "Ada"},
  "orders": [{"id": 101}, {"id": 102}]
}

Tip

השתמשו בלוח בדיקת תגובה כדי לראות בדיוק מה ה-AI יקבל אחרי הסינון לפני שתסתמכו עליו. ראו בדיקת הפעולה.

Caution

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

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

בדיקת תקינות הפעולות והיומנים

אזהרה לצד פעולות ו־MCP בסרגל הצד פירושה שפעולה דורשת טיפול. פתחו את הדף ורחפו מעל התג בכרטיס שלה או העבירו אליו את המיקוד כדי לראות מדוע:

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

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

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

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

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

• ה־AI מחליט: הפעולה מוצעת ל-AI רק בשיחות שבהן הערכים הנדרשים כבר קיימים.
• לפני התשובה הראשונה: הערכים חייבים להיות קיימים כשהמבקר שולח את ההודעה הראשונה.
• כאשר המטא־נתונים תואמים: הוסיפו תנאי קיים לכל ערך נדרש כדי שהפעולה תמתין לו.

ראו משתני פעולות AI למקורות של ערכי השיחה.

הודעות סיכום הפעילות באימייל כוללות גם סעיף פעולות AI דורשות טיפול כשפעולת HTTP או Remote MCP דורשת טיפול. הוא מציג עד חמש פעולות, עם סיבה וקישור אל פעולות ו־MCP; מונה נוסף מציג כמה פעולות נוספות דורשות טיפול. הסעיף מושמט כשכולן תקינות.

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

שיטות עבודה מומלצות

• נסחו תיאורים מפורשים. הסבירו ל-AI מתי להשתמש בפעולה ומה כל פרמטר צריך להכיל.
• צמצמו את ההרשאות לנדרש. כללו רק את הכותרות והאסימונים שנקודת הקצה צריכה. עבור Jira, השתמשו בכותרת Basic שמופקת מכתובת האימייל שלכם ב-Atlassian ומאסימון ה-API.
• בדקו לפני הפצה באמצעות לוח בדיקת הבקשה. ודאו שקודי הסטטוס ומטעני הדוגמה נראים תקינים בכלי היעד.

מדריכים

• חיבור סוכן AI לפניות Jira (התיעוד הראשי) או מדריך הבלוג עם קריינות
• שליחת התראת Slack באמצעות פעולת AI