מדריכיםכלים מותאמים ב-JSON

כלים מותאמים ב-JSON

schema מדויק עוזר לסוכן לשלוח רק את הנתונים שה-endpoint מצפה להם.

המודל המנטלי

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

  • name יציב
  • description שמגדיר גם מתי לא להשתמש
  • inputSchema צר
  • endpoint קבוע
  • responseTemplate קצר

מסלול של חמש דקות

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

{
  "name": "lookup_availability",
  "description": "Read open appointment slots; never create a booking",
  "method": "POST",
  "url": "https://api.example.com/availability"
}

הפעלת כלים מובנים

built-in tool מופעל או מכובה במפורש. שינוי חל לאחר טעינת ההגדרה מחדש; כלי כבוי צריך להיכשל באופן ברור ולא להיעלם בשקט מהאבחון.

  • שמרו default שמרני
  • תעדו סיבת הפעלה
  • בדקו מצב פרטי לפני ציבורי

ה-schema המלא

שדות חובה מגדירים זהות, תיאור, method, URL וקלט. שדות אופציונליים מוסיפים headers, auth, bodyTemplate, responseTemplate ו-timeout.

  • required לכל פרט שחייב להיאמר
  • enum לערכים סגורים
  • maxLength לטקסט
  • additionalProperties=false כשאפשר

תבניות URL, body ותשובה

ערך בתוך URL חייב לעבור URL encoding; ערך בתוך JSON חייב לעבור JSON encoding. responseTemplate קורא שדה ידוע ואינו מקריא payload שלם.

URL: /services/{{serviceId}}/slots?date={{date}}
Body: { "customerPhone": "{{phone}}" }
Response: נמצאו {{slots.length}} מועדים

אימות

Bearer token, API key או header מותאם מגיעים מ-secret בצד השרת. כלי ללא auth מתאים רק ל-API ציבורי שאינו חושף נתוני לקוח ואינו מבצע כתיבה.

  • לעולם לא secret בתוך Git
  • rotation מתועד
  • scope מצומצם
  • כשל auth נכשל סגור

דוגמאות עבודה

Lookup ללקוח Stripe הוא קריאה לאחר אימות; יצירת ticket ב-CRM היא כתיבה עם idempotency; מזג אוויר הוא דוגמה לכלי ציבורי ללא מידע אישי.

  • הפרידו read ו-write לשני כלים
  • אל תאפשרו למודל לבחור endpoint
  • החזירו מזהה פעולה

מודל אבטחה ותפעול

ה-gateway מגביל protocol, host, זמן וקלט, אך השרת עדיין חייב לאמת tenant והרשאה. validate בודק מבנה, לא הרשאה עסקית.

  • בדקו configuration לפני restart
  • בדקו שגיאת schema
  • בדקו timeout
  • בדקו payload זדוני
  • נטרו שיעור כשל

פתרון תקלות

  • הסוכן לא קורא לכלי: שפרו description ודוגמאות
  • tool not configured: בדקו name וטעינה
  • service unreachable: בדקו DNS, TLS ו-allowlist
  • JSON מוקרא: הגדירו responseTemplate
  • body נדחה: בדקו encoding וסוגים

בדיקת בטיחות

JSON תקין אינו הוכחה שהבקשה בטוחה; אמתו tenant והרשאה בצד השרת.