לוח הבקרה מכסה את רוב צורכי הכלים ללא API זה: חיבורים
→ אפליקציות מחבר את Slack, HubSpot, Salesforce, Google Calendar,
Google Sheets ו-Cal.com בכמה לחיצות OAuth; חיבורים →
ממשקי API הופך כל API מסוג HTTP לפעולה של סוכן (הדביקו פקודת cURL
ואשף AI יכין טיוטה של הכלי, עם בדיקת בקשה מובנית); ו-חיבורים → MCP
מוסיף שרתי MCP. ראו
חיבורים. מדריך זה עוסק ב-API הבסיסי
שמתחת לממשק ממשקי ה-API.
אנטומיה של כלי
שני חלקים:- הסכמה — הגדרת פונקציה בסגנון OpenAI
(
{type: "function", function: {name, description, parameters}}) שמסבירה ל-LLM מה הכלי עושה ואילו ארגומנטים הוא מקבל. - נקודת הקצה — כתובת ה-URL שאליה השרתים של ThunderPhone קוראים כאשר ה-LLM מחליט להשתמש בכלי. הבקשה היא JSON POST עם הארגומנטים שבחר ה-LLM כגוף הבקשה.
1. בחרו אסטרטגיית אחסון
מוטמע בסוכן
צרפו כלי חד-פעמי למערך
tools של הסוכן. פשוט, אך
אינו ניתן לשימוש חוזר.שילוב שמור
אחסנו את הכלי כ-שילוב לשימוש חוזר
וקשרו אותו מסוכנים רבים. מומלץ לכל דבר שנעשה בו שימוש יותר
מפעם אחת.
2. צרו את השילוב
id שהוחזר (UUID).
3. בדקו את נקודת הקצה בארגז חול
לפני שתקשרו את השילוב לסוכן, שלחו בקשה חתומה מהשרתים של ThunderPhone כדי לאשר קישוריות:Response
400 code=url_not_allowed.
4. קשרו את האינטגרציה לסוכן
צרפו באמצעותintegration_ids בעת יצירה או עדכון של סוכן:
get_weather כשהמתקשר שואל
על תנאי מזג האוויר” — או לגלות אותן במרומז מתיאורי
הסכמה.
5. ממשו את נקודת הקצה
כאשר הסוכן מפעיל את הכלי, ThunderPhone שולחת בקשת POST חתומה אלendpoint_url שלכם:
6. בדקו את הלולאה
הפעילו סשן מיקרופון מול הסוכן ושאלו את השאלה שהכלי שלכם מטפל בה (“מה מזג האוויר ב-94110?”). תמליל השיחה מציג את כל התהליך מקצה לקצה:GET /v1/calls/{call_id}/transcript;
זרם האירועים הגולמי (עם תזמון לכל רשומה והיסטי אודיו) זמין ב-
GET /v1/calls/{call_id}/history.
תקלות נפוצות
הסוכן אף פעם לא מפעיל את הכלי
הסוכן אף פעם לא מפעיל את הכלי
ה-LLM מחליט על סמך תיאור הכלי. אם שאלת המתקשר
אינה תואמת לתיאור, המודל לא יפעיל
את הכלי. דייקו את התיאור (הוסיפו מילים נרדפות וניסוחים
נפוצים) או ציינו זאת במפורש בפרומפט של הסוכן (“כאשר
המתקשר שואל על מזג האוויר, השתמשו ב-
get_weather.”).הכלי מחזיר יותר מדי נתונים
הכלי מחזיר יותר מדי נתונים
תגובות בגודל העולה על 6 kB נחתכות בתצוגה המקדימה של התמליל. החזירו
רק את השדות שה-LLM זקוק להם — לא את כל הרשומה שלכם.
חריגות זמן
חריגות זמן
לנקודות קצה של כלים יש פסק זמן ברירת מחדל של 10 שניות. אם אתם זקוקים ליותר זמן,
טפלו בכך באופן אסינכרוני: החזירו
{"status": "pending", "request_id": "..."}
והציגו את התוצאה באמצעות קריאה נפרדת לכלי.ניהול גרסאות
ניהול גרסאות
כל
PATCH של אינטגרציה יוצר מהדורה חדשה. בדקו את
GET /v1/integrations/{id}/versions
כדי לראות מי שינה מה. אם שברתם את הסכמה של כלי, תוכלו
לחזור לאחור ידנית באמצעות PATCH של תמונת מצב ישנה יותר בחזרה.השלבים הבאים
מדריך העזר לשילובים
CRUD, העברה, היסטוריית גרסאות.
מפרט כלי פונקציות
דקדוק מלא של סכמת JSON וחוזה נקודת הקצה החתומה.
אימות חתימות
החילו את תבנית חתימת ה-webhook על נקודות קצה של כלים.
API לתמלול ולהיסטוריה
בדקו את כל המסלול הלוך ושוב של קריאה לכלי.