function calling agent: איך כותבים Function Schemas שמפחיתים טעויות ולא מאבדים את הראש

יש רגע כזה, מי שעובד עם מודלי שפה מכיר אותו טוב מדי: אתה משקיע, מלטש, בונה agent חכם, מחבר פונקציות, מגדיר פרמטרים – ואז ה-ai agent מחליט לקרוא לפונקציה הלא נכונה, עם פרמטרים חצי-חסרים, או בפורמט שמזכיר טופס ישן של ביטוח לאומי. לא כי הוא "טיפש". כי ה-Function Schema שלך השאיר לו יותר מדי מקום לניחושים.

במילים אחרות: היום לא מספיק "שיהיה agent". צריך לדעת לעצב את ה־Function Schemas בצורה שמכבדת גם את המודל וגם את המפתחים. וזה קצת אומנות, קצת הנדסה, וקצת הבנה פסיכולוגית של איך מודל שפה "חושב" על קריאה לפונקציה.

למה בכלל אכפת לנו מ-Function Schemas? ומה זה אומר על ai agent מודרני

אם היינו מדברים לפני שנתיים, רוב השיחה על בינה מלאכותית הייתה סביב טקסט חופשי: שאלות–תשובות, כתיבה, סיכום. היום, הדיון זז לכיוון אחר: איך לגרום ל-ai agent לא רק לדבר, אלא גם לפעול – לקרוא APIs, להפעיל מערכות, לתאם פגישות, להזמין טיסות, להרים קמפיין פרסום או לשאוב נתונים ממערכות BI.

כאן נכנס המשחק של function calling. במקום שהמודל רק "יציע" מה לעשות, הוא קורא לפונקציות אמיתיות בקוד שלך. כל פונקציה כזו עטופה ב-Schema – תיאור רשמי של מה היא עושה, אילו פרמטרים יש לה, איזה טיפוס כל פרמטר, מה חובה ומה אופציונלי. על הנייר זה נשמע פשוט. בפועל, זה המקום שהרבה ai agent־ים נופלים בו.

ראיתי לא מעט מערכות שבהן ה-agent "ידע" מה צריך לעשות, אפילו ניסח את זה נכון בטקסט, אבל ה-Schema היה מעורפל מספיק כדי לגרום לו לבחור בפונקציה הלא מתאימה, או לשלוח מחרוזת איפה שמצופה מערך, או פשוט לשכוח שדה חובה. ואז מתחיל סבב הניחושים: תיקון ב-code, עוד prompt, עוד patch, עוד הוספת דוגמאות. בעצם, הרבה פעמים הבעיה נמצאת שלב אחד קודם – בעיצוב ה-Function Schemas עצמם.

הטעות הנפוצה: להתייחס ל-Function Schema כמו לדוקומנטציה יבשה

בפיתוח "קלאסי", אנחנו כותבים חתימת פונקציה, אולי מוסיפים הערה, וממשיכים הלאה. הקומפיילר, הטייפסיסטם, או לפחות ה-IDE – שומרים עלינו. כשאנחנו עובדים עם ai agent, ה-Schema צריך לשמש גם כדוקומנטציה למכונה. הוא לא רק "הגדרה". הוא השפה שבה אתם מדברים עם המודל על איך לקרוא לפונקציה.

וכאן מגיעה הנקודה שאנשים נוטים לפספס: המודל קורא את ה-Schema כמו טקסט. כן, הוא מבין JSON, הוא מבין טיפוסים, אבל הוא מבין גם מילים. אם ה-Schema יבש מדי, קצר מדי, או לא ברור – הוא משאיר מקום לפרשנות. ואיפה שיש פרשנות, ai agent יעקוב אחרי ההסתברות הסטטיסטית, לא אחרי "כוונת המפתח". ההבדל קטן, אבל ב-production הוא כואב.

Function Schema כאפיון מוצר, לא רק כחתימת פונקציה

אפשר לחשוב על Function Schema טוב כאפיון UX, אבל ל-agent. אתם לא כותבים רק: get_user(id: string). אתם מסבירים למודל: "זו פונקציה שמביאה את פרטי המשתמש לפי מזהה פנימי במערכת, ולא לפי מייל או טלפון. אל תשתמש בה אם יש לך רק שם פרטי". זה לא נראה כמו קוד, זה נשמע כמו אפיון. וזה intentional.

ברגע שמבינים שה-Function Schema הוא שכבת תקשורת בין האדם למודל, ולא בסך הכל formal spec לקומפיילר, משתנה כל הדרך שבה מתכננים ai agent.

אז איך בעצם בונים Schemas טובים? כמה עקרונות שצמחו מהשטח

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

1. שמות פונקציות שמספרים סיפור, לא רק תועלת

ai agent לא רואה את הקוד, הוא רואה רק את שם הפונקציה ואת התיאור. כשיש לכם פונקציות בשם get_data או update, אל תתפלאו אם המודל מתבלבל. שם הפונקציה הוא האיתות הראשון למודל: "מתי מותר להשתמש בזה?".

במקום get_user, עדיף:

get_user_by_internal_id

או אפילו:

get_crm_user_by_internal_id

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

2. תיאור מילולי מדויק – מודל קורא גם שורות קטנות

מתוך עצלות או לחץ זמנים, הרבה מפתחים כותבים description לקוני: "Get user". "Update task". "Search items". לכאורה מספיק. בפועל, זה מתכון לחוסר דיוק.

תיאור טוב ל-Schema צריך לענות על כמה שאלות בסיסיות:

• באיזה הקשר משתמשים בפונקציה הזו?
• מה היא לא עושה?
• האם יש פונקציות אחרות דומות, ומה ההבדל ביניהן?
• מה נחשב "קלט טוב"?

ה-ai agent קורא את הטקסט הזה, ממש כמו דוקומנטציה. בפועל, כמה שורות טקסט טובות לתיאור פונקציה מצמצמות כמות אדירה של ניסוי וטעייה.

3. פרמטרים: פחות "אולי", יותר "כן/לא" ברמת החובה

הנטייה הטבעית כשמגדירים Schemas היא להוסיף פרמטרים אופציונליים "ליתר ביטחון". אולי נצטרך בעתיד. אולי לפעמים יהיה נוח שיהיה גם זה. הבעיה: ai agent רואה שדה אופציונלי ואומר לעצמו (אם נ anthropomorphize אותו רגע): "אם אופציונלי – אז אני יכול לוותר". במיוחד כאשר המידע לא מופיע במפורש בשאלה של המשתמש.

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

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

4. אל תתביישו לכתוב דוגמאות בשדות ה-description

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

{
  "name": "create_support_ticket",
  "description": "יוצר פנייה חדשה במערכת התמיכה. השתמש בפונקציה זו רק כאשר המשתמש מבקש לפתוח קריאה חדשה, ולא לעדכון קריאה קיימת. דוגמה: 'תפתח לי קריאה על בעיית התחברות'.",
  ...
}

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

מה קורה כשלהיט ה-ai agent פוגש את הבירוקרטיה הישראלית

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

בארגונים גדולים, שדות כמו mispar_eshkol או kod_misrad הם חלק מהחיים. הם חשובים מאוד למערכת, אבל בלתי-קריאים לחלוטין גם לבני אדם, לא רק למודל. כאן ה-Function Schemas הופכים להיות אולי עוד יותר קריטיים: הם למעשה שכבת התרגום בין שפת הארגון לבין שפת ה-agent.

לדבר עם ai agent בשפה של אדם, לא בשפה של מערכת ירושה

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

{
  "name": "kod_misrad",
  "description": "קוד פנימי של המשרד כפי שהוא מופיע במערכת המורשת. אם למשתמש אין את הקוד, אל תנחש – השתמש בפונקציה 'search_office_by_name' כדי למצוא אותו.",
  "type": "string"
}

שימו לב למשפט: "אל תנחש – השתמש בפונקציה 'search_office_by_name'". זה בדיוק המקום שבו שיחה נכונה בין פונקציות, דרך Schemas טובים, מונעת בלגן. ה-ai agent מקבל "רמז התנהגותי" – מה לעשות במקום להמציא ערך.

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

טעויות קלאסיות ב-Function Schemas שגורמות ל-agent להסתבך

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

שדה אחד שעושה שני תפקידים

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

עדיף לפצל: free_text, user_id, date_range. המודל חזק בהסקה, אבל לא צריך להכריח אותו לנחש כל פעם באיזה mode אתם. פיצול פרמטרים כזה גם מעלה את הסיכוי שתראו טעויות עוד בשלב הפיתוח, ולא כשה-agent כבר מדבר עם לקוחות.

תיאורים סותרים בין הפונקציה לשדות שלה

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

הקפדה על קוהרנטיות בין התיאור הכללי לתיאורי השדות היא לא "אסתטיקה". היא מנגנון הכוונה. ai agent נוטה לסמוך על הטקסט העדכני ביותר והמפורט ביותר שהוא רואה.

פונקציות רבות מדי שעושות בערך אותו הדבר

עוד תופעה: דרישה מוצרית שמשתנה כל שבוע, וכל פעם נוצרת פונקציה חדשה: search_users, advanced_search_users, search_users_by_segment, search_users_new… מבחינת פיתוח – זה לפעמים נוח. מבחינת ai agent – זה סיוט.

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

איך לשלב בין Prompting ל-Schemas כדי לצמצם טעויות

אי אפשר לדבר על function calling agent בלי לדבר קצת על מערכת היחסים בין ה-prompt הכללי לבין ה-Schemas. הם לא שני עולמות נפרדים. להפך: prompt טוב יודע "לספר" ל-agent איך להתייחס לפונקציות, וה-Schemas משמשים בתור הסבר מפורט לפי הצורך.

להגיד במפורש: "אם אתה לא בטוח – אל תזייף"

ב-Prompt הראשי שמגדיר את אופי ה-ai agent, יש מקום להנחיות ברורות, מסוג:

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

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

דוגמה של שיחה מלאה – לא רק Schema בודד

ארגונים שמצליחים לבנות ai agent יציב עובדים הרבה עם דוגמאות end-to-end. לא רק "איך נראית הפונקציה", אלא "איך נראה דיאלוג שבו ה-agent מחליט לקרוא לפונקציה הזו, עם אילו פרמטרים, ומה הוא עושה עם התשובה".

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

טבלה: עיקרי הטיפים ל-Function Schemas עבור ai agent

נושא	בעיה נפוצה	גישה מומלצת ל-Function Schema	השפעה על ai agent
שמות פונקציות	שמות גנריים כמו get_data, update	שמות ספציפיים ומבדילים, למשל get_crm_user_by_internal_id	מקטין בלבול בין פונקציות דומות ומשפר התאמת שימוש
תיאורי פונקציה	Descriptions קצרים ולא ברורים	הסבר מתי להשתמש, מתי לא, והבדלים מול פונקציות אחרות	מקטין קריאות שגויות ומעלה דיוק בבחירת פונקציה
פרמטרים חובה/אופציונליים	שימוש יתר ב-optional משיקולי "אולי נצטרך"	הגדרת חובה רק למה שבאמת קריטי; הסבר איך להשלים מידע חסר	פחות ניחושים מצד המודל, יותר התנהגות צפויה
שמות שדות	שמות פנימיים ובלתי-קריאים	שימור השם הטכני עם תיאור עשיר וברור בעברית	ה-agent "מבין" טוב יותר את משמעות השדה, גם במערכות מורשת
דוגמאות שימוש	Schemas בלי דוגמאות	הוספת משפטי דוגמה לטריגר שימוש, פורמטים וערכים	מודל מחקה דפוסים נכונים ומפחית וריאציות בעייתיות
כמות פונקציות	הרבה פונקציות דומות עם שמות קרובים	איחוד לפונקציה גמישה אחת עם פרמטרים ברורים	מפשט החלטות ומקטין טעויות בבחירת פונקציה
קוהרנטיות תיאורים	סתירות בין תיאור הפונקציה לתיאור הפרמטרים	בדיקת התאמה מלאה בין כל חלקי ה-Schema	מונע "בלבול טקסטואלי" למודל בעת הקריאה לפונקציה
שילוב עם Prompt	Prompt כללי שלא מתייחס להתנהגות בקריאה לפונקציות	הנחיות מפורשות על שימוש זהיר, שאלות הבהרה ובלי ניחושים	ai agent זהיר יותר, פחות "ממציא" נתונים חסרים

שאלות ותשובות נפוצות על function calling agent ו-Function Schemas

האם באמת חייבים תיאורים ארוכים לכל פונקציה?

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

כמה פונקציות זה יותר מדי עבור ai agent אחד?

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

מה עדיף – להגן בצד השרת או לסמוך על ה-agent?

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

מה עושים כשיש שדה חשוב שהמשתמש כמעט אף פעם לא מספק?

כאן נכנס תכנון תהליך. במקום להפוך את השדה לאופציונלי ולסמוך על ai agent ש"יסתדר", עדיף לתת לו דרך להשלים את המידע: פונקציה שממירה אימייל ל-ID, או פונקציה שמקבלת שם חברה, ומחזירה מזהה פנימי. ב-Schema של הפונקציה המרכזית, אפשר לכתוב במפורש: "אם אין לך את השדה הזה, השתמש קודם בפונקציה X כדי להשלים אותו".

איך אפשר לבדוק אם ה-Schemas שלנו טובים בלי לעלות ישר ל-production?

טכנית, הכי פשוט – לבנות סביבת sandbox, להריץ תרחישים אמיתיים, ולבדוק לא רק אם ה-agent מגיע לפתרון, אלא באילו פונקציות הוא משתמש בדרך. אם אתם רואים דפוסים כמו "קריאה לפונקציה הלא נכונה ואז תיקון", או "ניסיון לשלוח ערכים מיותרים", זה סימן שה-Schemas שלכם עוד לא "מדברים" ברור מספיק עם ה-agent. מומלץ גם לעבור ידנית על כמה שיחות ולשאול את עצמכם: "אם הייתי מפתח חדש בצוות, האם הייתי מבין מה הפונקציה הזו עושה רק מה-Schema?" אם התשובה היא "לא באמת" – גם למודל זה קשה.

איפה כל זה פוגש את היום־יום של צוותי פיתוח בישראל

ברמה הכי פרקטית, Function Schemas הופכים להיות חלק מאפיון המוצר. זה כבר לא מסמך נפרד, טכני בלבד. צוותים שנכנסים ל־ai agent ברצינות מתחילים לכלול ב-PRD לא רק "פיצ׳ר" ו"אפיון UX" למשתמש, אלא גם "אפיון ל-agent": אילו פונקציות יהיו, מה ההבדל ביניהן, איך הן יתוארו, ואיך המודל אמור לבחור ביניהן.

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

מבט קדימה: Schemas כנדבך זהותי של כל ai agent

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

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

סיכום קטן, והזמנה לדבר

כשאנחנו מדברים היום על function calling agent, אנחנו בעצם מדברים על מודל שפה שמנסה להשתלב בעולם אמיתי: מערכות, APIs, נתונים מלפני עשר שנים, משתמשים חסרי סבלנות, מנהלי מוצר שמחליפים דרישות. Function Schemas טובים הם מה שמאפשר לכול זה לעבוד בלי להישבר.

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

אם אתם שוקלים להכניס ai agent לתוך המוצר שלכם, או שכבר התחלתם וכואב לכם במקום הזה של פונקציות ו-Schemas – נשמח לסייע בייעוץ ראשוני ללא עלות, לנתח ביחד את הארכיטקטורה, ולמצוא איפה תכנון נכון של Function Schemas יכול לצמצם לכם טעויות ולחסוך חודשים של ניסוי וטעייה.