דלג לתוכן הראשי

AI Agents (סוכני AI)

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

מוצאים אותם תחת Settings → AI Agents. בנייה ועריכה של סוכנים דורשות את ה־scope settings:write (או מפתח API עם ai_agents:write); צפייה דורשת settings:read / ai_agents:read.

Generate-only: מחליט, לא פועל​

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

  1. קורא רק את ההקשר שבחרתם לחשוף לו (מאפיינים נבחרים, סגמנטים, שדות קטלוג, קול המותג ומעורבות אחרונה).
  2. מבקש מהמודל להפיק פלט התואם לסכמת פלט קשיחה שהגדרתם.
  3. מאמת את הפלט ומחזיר אותו - יחד עם explanation אופציונלי של נימוק המודל.

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

יצירת סוכן​

Instructions (הנחיות)​

ה־Instructions הן מטרת הסוכן - הנחיית המערכת שלו. הן עוברות תבנוּת Liquid עם אוצר המילים של סביבת העבודה וההקשר הנבחר בזמן ההרצה, כך שאפשר להתייחס לשמות אמיתיים של מאפיינים ואירועים. תארו מה תרצו שייווצר ואת הכללים שעליו לקיים (טון, אורך וערכים מותרים).

התייחסו לשדות שחשפתם בפועל

המודל רואה רק את שדות ההקשר שציינתם תחת Context selectors. אם ההנחיות מזכירות שם שדה (למשל "בדוק את המחיר") אבל השדה הזה לא נמצא בהקשר, המודל לא יכול לפעול לפיו. ציינו את שם השדה המדויק שחשפתם - למשל "אם series_id גדול מ־1200…". היסטוריית ההרצות מציגה את הקלט המדויק שהמודל ראה, מה שמקל לזהות זאת.

Tags (תגיות)​

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

מודל: managed מול BYO​

כל סוכן רץ על מודל אחד, המוגדר בשתי דרכים:

  • Managed - Joryio Auto. אפשרות אחת: Joryio בוחרת אוטומטית את המודל המתארח הטוב ביותר (ואת רמת החשיבה שלו) לכל הרצה. אין מה לכוונן - אין מזהה מודל ואין רמת חשיבה. אתם משלמים את עלות הטוקנים בתוספת המרווח שלנו, בחיוב של קרדיט אחד להרצה מהארנק. אין צורך להגדיר מפתח; זה פשוט עובד.
  • BYO (bring your own) - מפתח הספק שלכם. הספקים הנתמכים הם Anthropic, OpenAI, Google (Gemini), Azure OpenAI ו־AWS Bedrock. כאן אתם מציינים את ה־model id המדויק להרצה (למשל claude-opus-4-8, gpt-4o, gemini-1.5-pro). אתם משלמים ישירות לספק ה־LLM על הטוקנים; Joryio גובה עמלת פלטפורמה קטנה וקבועה להרצה. הוסיפו את המפתח תחת Provider Keys (ראו למטה) לפני בחירת BYO.

Context selectors (מה הסוכן רשאי לקרוא)​

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

  • Attribute keys - מאפייני איש הקשר שיש לכלול.
  • Segment memberships - דגלים לסגמנטים שתציינו.
  • Catalog fields - שדות מרשומת הקטלוג או הישות שמועשרת.
  • Required fields (שדות חובה) - תת־קבוצה של שדות קטלוג שחייבים להיות קיימים כדי שהסוכן ירוץ. במהלך ההעשרה, כל שורה שחסר בה אחד מהם מדולגת ואינה מחויבת (סיבת הדילוג נרשמת). העשרת שורה חסרה מבזבזת הרצה ובדרך כלל מפיקה תשובה גרועה יותר, אז דרשו את השדות שהסוכן באמת צריך.
  • Brand voice - הכללת קול המותג של סביבת העבודה כדי שהפלט יתאים לו.
  • Recent engagement - סיכום קצר של הפעילות האחרונה של איש הקשר.
  • PII masking - PII מנוהל באופן גלובלי: סמנו מאפיין כ־PII תחת Custom Attributes והוא ימוסך אוטומטית לפני שהמודל יראה אותו, בכל סוכן.

Output schema​

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

  • Type - string, number, boolean או json.
  • עבור json, רשימת שדות בעלי שם, שלכל אחד מהם טיפוס בסיסי (string, number, boolean) ותיאור אופציונלי.
  • Include explanation - שמירת נימוק המודל בשדה explanation (תיעוד זול שניתן לבדוק).

פלט שאינו תואם לסכמה נדחה ומטופל ככשל (ראו חוזה השגיאות למטה).

Fallback value (ערך גיבוי)​

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

Daily cap (מכסה יומית)​

לכל סוכן יש מגבלת הרצות יומית משלו (ברירת מחדל 250,000; 0 = ללא הגבלה) - מספר הפעמים המרבי שאותו סוכן רץ ביום. כשמגיעים למגבלה, הרצות נוספות נכשלות באופן סגור (fail-closed) עם התוצאה budget_exceeded (ועוברות לקצה הגיבוי או השגיאה), וכך מגינות על ההוצאה שלכם ממסע שיצא משליטה. לחשבון שלכם יש גם מכסה יומית לכל סביבת העבודה על כל הסוכנים יחד, המנוהלת על ידי Joryio - צרו איתנו קשר כדי להעלות אותה.

Guardrails (מנגנוני הגנה)​

מנגנוני ההגנה לכל הרצה כוללים timeout קשיח (ברירת מחדל 20 שניות), מגבלה אופציונלית של מספר הטוקנים המרבי בפלט ואפשרות לנסות שוב בשגיאות חולפות (מגבלות קצב ושגיאות 5xx בלבד - לעולם לא בגלל מפתח שגוי או פלט לא תקין).

יצירת סוכן מתוך עוזר ה־AI​

אפשר גם לבקש מעוזר Joryio לבנות עבורכם סוכן: תארו מה אתם רוצים (למשל, "סוכן שקורא את מחיר המוצר וכותב high או low") והוא יציע סוכן מוכן להחלה. מוצג כרטיס Apply המסכם את הסוכן; שום דבר לא נוצר עד שתלחצו על Apply. לאחר הלחיצה, הסוכן נוצר כטיוטה ואתם מקבלים קישור לפתיחתו בעורך - כך שתמיד תסקרו, תבדקו ותפעילו אותו בעצמכם לפני שהוא רץ. סוכנים שנוצרו על ידי העוזר הם תמיד Managed (Joryio Auto); העוזר לעולם אינו בוחר ספק מסוג BYO ואינו מטפל במפתחות.

שימוש בסוכן בתוך מסע​

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

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

  • success - המודל החזיר פלט תקין; אותו פלט זמין במורד הזרם.
  • fallback - הרצה נכשלה אך לא חיברתם קצה שגיאה ייעודי; נעשה שימוש בערך הגיבוי והמסע ממשיך.
  • תוצאות error - timeout, rate_limited, invalid_config ו־budget_exceeded. לכל אחת יש קצה הסתעפות נפרד בצומת, כך שאפשר לחבר כל תוצאת שגיאה לנתיב ייחודי משלה במסע (או לא לחבר אותה, ואז היא תעבור ל־fallback).

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

העשרת קטלוג​

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

עבודת ההעשרה רצה באופן אסינכרוני ברקע: שולחים משימה ומקבלים מיד מזהה של משימה בתור (queued), כך שקטלוג גדול (עד 100 אלף שורות) מעובד מחוץ לנתיב הבקשה במקום לחסום אותה. לאחר מכן בודקים את המשימה באופן מחזורי כדי לקבל את הסטטוס והספירות שלה - הסטטוס עובר queued → running → completed (או failed), והספירות (total, processed, succeeded, failed, skipped) מתמלאות תוך כדי. המשימה אידמפוטנטית לכל רשומה, כך שהרצה חוזרת לעולם אינה מחייבת מחדש שורה שכבר הועשרה. אפשר להפעיל אותה ולעקוב אחר ההתקדמות מלוח הבקרה או דרך נקודות הקצה להעשרה.

רק הרצות מוצלחות כותבות את השדה. שורה מדולגת (הערך הקיים שלה נשאר ללא שינוי) בכל פעם שהסוכן מחזיר תוצאה שאינה הצלחה - שדה חובה חסר, ארנק ריק (budget_exceeded), מפתח BYO שגוי (invalid_config) וכדומה. כאשר שורות מדולגות, המשימה מציגה סיבה (למשל "2 מתוך 2 שורות לא נכתבו - invalid_config: …") כדי שתדעו מדוע דבר לא נכתב, ולא תראו רק ספירה ללא הסבר. העשרת קטלוג מחויבת לכל הרצה; Test ותצוגה מקדימה הם חינם (ראו למטה).

בדיקה ותצוגה מקדימה​

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

  • outcome - success, fallback או אחת מתוצאות השגיאה.
  • output - הפלט המובנה המאומת (או הגיבוי בכשל).
  • explanation - נימוק המודל, כאשר הסכמה כוללת אותו.

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

חוזה השגיאות​

כל הרצה מסתיימת בתוצאה אחת בדיוק:

Outcomeמשמעותניסיון חוזר?
successפלט תקין התואם לסכמה.-
fallbackהרצה נכשלה ולא חובר קצה שגיאה ייעודי; נעשה שימוש בערך הגיבוי.-
timeoutההרצה חרגה מה־timeout.חולף - ניסיון חוזר אם מופעל.
rate_limitedהספק הגביל את הקצב.חולף - ניסיון חוזר אם מופעל.
invalid_configכשל דטרמיניסטי: מפתח שגוי או שפג תוקפו, שגיאת תצורת תמחור או חיוב, או פלט שנכשל באימות הסכמה.לא - לעולם לא.
budget_exceededהושגה מגבלת הוצאה: מגבלת ההרצות היומית של הסוכן, המכסה היומית לכל סביבת העבודה של החשבון, או יתרת ארנק לא מספקת להרצה מחויבת.לא.

ניסיונות חוזרים משתמשים בהשהיה מעריכית מוגבלת וחלים רק על כשלים חולפים.

מדידה ועלות​

הרצות נמדדות לכל קריאה:

  • Managed - קרדיט אחד להרצה, המנוכה מהארנק. הקרדיט מתומחר עם מרווח לטוקנים בתוספת המרווח שלנו.
  • BYO - עמלת פלטפורמה קטנה וקבועה להרצה; אתם משלמים לספק שלכם ישירות על הטוקנים.

קרדיט AI חינם. כל חשבון מקבל מאגר חודשי של קרדיט AI חינם (ברירת מחדל $5 לחודש) שרק הרצות של סוכני AI יכולות לנצל - הוא נפרד מארנק ההודעות, כך ש־SMS, WhatsApp ואימייל לעולם אינם משתמשים בו. כל הרצה מנצלת קודם את הקרדיט החינמי, ורק לאחר שהוא נגמר עוברת לארנק בתשלום. הקרדיט מתאפס בתחילת כל חודש (לא ניתן לצבור אותו) והיתרה מוצגת ב־Settings → Usage. הרצות Test ותצוגה מקדימה תמיד חינם, ללא קשר לקרדיט.

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

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

היסטוריית הרצות​

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

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

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

ממשל נתונים​

  • PII הוא opt-in. סוכן רואה רק את המאפיינים, הסגמנטים והשדות שבחרתם במפורש. שום מידע על איש קשר אינו מגיע למודל כברירת מחדל.
  • מיסוך PII גלובלי. סמנו מאפיין כ־PII פעם אחת תחת Custom Attributes והוא ימוסך אוטומטית לפני שההקשר מגיע למודל, בכל סוכן - אין צורך לבחור אותו מחדש לכל סוכן.
  • הקלט נשמר ממוסך לצורך בדיקה. כדי שתוכלו לאבחן ולשפר סוכנים, כל הרצה שומרת את ההנחיה שהמודל ראה (הנחיות המערכת וההקשר) - לאחר מיסוך PII ובגודל מוגבל. היא לעולם אינה כוללת ערכים שסימנתם כ־PII. נתונים אלה מופיעים בהיסטוריית ההרצות שלמעלה.
  • בידוד סביבת העבודה. סוכן יכול לקרוא רק את סביבת העבודה שבה הוא רץ, ומפתחות BYO נשמרים בכספת מוצפנת נפרדת לכל סביבת עבודה - הערכים הסודיים שלהם לעולם אינם מוחזרים על ידי ה־API.

הצעדים הבאים​