דילוג לתוכן הראשי
חזרה למדריכים
Implementation9 דק׳ קריאה

כתיבת Tools לסוכנים: סכימות, שגיאות ו-Retries

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

הכלי הוא לא פונקציה — הוא ממשק למודל

המודל רואה רק את שם הכלי, התיאור והסכימה. אם הם לא ברורים, הוא לא "יבין לב" — הוא ימציא. כל הגדרת כלי צריכה ארבעה חלקים: name, description, parameters (JSON Schema מלא), required array.

סכימה שעובדת

{
  "name": "get_appointments",
  "description": "מחזיר את התורים של לקוח בטווח תאריכים. תאריכים בפורמט ISO 8601 (YYYY-MM-DD).",
  "parameters": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "מזהה הלקוח ב-CRM, מתחיל ב-CU-"
      },
      "start_date": { "type": "string", "format": "date" },
      "end_date": { "type": "string", "format": "date" }
    },
    "required": ["customer_id", "start_date", "end_date"],
    "additionalProperties": false
  }
}

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

  • additionalProperties: false על כל אובייקט — בלי זה המודל ממציא שדות.
  • Enums לכל ערך מבוקר. המודל לא צריך לנחש אם זה "yes", "true" או "1".
  • יחידות ופורמטים בשמות השדות או בתיאור — price_usd, date_iso. "price" לבד זו הזמנה לבאג.
  • טיפוסים קפדניים, בלי unions רופפים.
  • Description שאומר מתי להשתמש בכלי ומתי לא — לא סיכום שיווקי.

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

שכבת הוולידציה — לפני ואחרי

שתי נקודות בדיקה על כל קריאת כלי:

  1. לפני הביצוע: ולידציה של הארגומנטים מול הסכימה (טיפוסים, שדות חובה) ואחר כך ולידציה עסקית (התאריך קיים? המזהה בפורמט הנכון? הסכום חיובי?). פלט שעבר סכימה אבל לא הגיון עסקי — עדיין שגיאה.
  2. אחרי הביצוע: ולידציה של הפלט לפני שהוא נכנס ל-context של המודל. תגובת API גולמית לא נכנסת ישר לשיחה — זה גם בזבוז טוקנים וגם חור הזרקה: תוכן חיצוני יכול להכיל הוראות זדוניות (prompt injection), ולכן הוא מסומן כ-data לא מהימן ולא כהוראות.

שגיאות שהמודל יודע לעבוד איתן

החזרת שגיאה למודל היא לא כישלון — היא ערוץ תקשורת. שגיאה טובה מכילה: קוד, הודעה קריאה, האם הבעיה recoverable, ורמז לתיקון. "Error: invalid input" לא יעזור לאף מודל. "customer_id must start with CU-, got: 12345" תגרום לו לתקן בניסיון הבא.

מדיניות Retries

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

סוג כשלRetry?אסטרטגיה
Rate limit (429)כןExponential backoff עם jitter, לפי Retry-After
שגיאת שרת (5xx)כןBackoff, 3–5 ניסיונות
Timeoutכןניסיון אחד נוסף ואז fallback
שגיאת לקוח (4xx)לאהארגומנטים שגויים — מחזירים למודל שגיאה מובנית
פלט לא תקין מהכלי עצמולאהכלי שבור — תיקון בקוד, לא retry

כלל ברזל: פעולות שאינן idempotent (שליחת תשלום, מייל, יצירת רשומה) מקבלות idempotency key ולא מריצות retry עיוור. ארגומנטים שגויים מהמודל לא מקבלים retry עם אותם ארגומנטים — זה רק שורף טוקנים — אלא re-prompt עם השגיאה.

כמה כלים זה יותר מדי

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

רוצה להעמיק את הנושא אצלך בצוות?

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

בואו נדבר