Skip to main content
שילוב כלי הוא נקודת קצה לשימוש חוזר מסוג HTTP שסוכן יכול להפעיל במהלך שיחה. אתם מספקים ל-ThunderPhone תיאור מסוג JSON Schema של הכלי לצד כתובת URL של נקודת קצה; הסוכן מחליט מתי לקרוא לה על סמך השיחה, ו-ThunderPhone שולחת את בקשת ה-HTTP היוצאת מהשרתים שלה ומחזירה את התגובה לסוכן.
לוח הבקרה מכסה את רוב צורכי הכלים ללא API זה: חיבורים → אפליקציות מחבר את Slack, HubSpot, Salesforce, Google Calendar, Google Sheets ו-Cal.com בכמה לחיצות OAuth; חיבורים → ממשקי API הופך כל API מסוג HTTP לפעולה של סוכן (הדביקו פקודת cURL ואשף AI יכין טיוטה של הכלי, עם בדיקת בקשה מובנית); ו-חיבורים → MCP מוסיף שרתי MCP. ראו חיבורים. מדריך זה עוסק ב-API הבסיסי שמתחת לממשק ממשקי ה-API.
מדריך זה מסביר כיצד לבנות כלי לחיפוש מזג אוויר מקצה לקצה.

אנטומיה של כלי

שני חלקים:
  1. הסכמה — הגדרת פונקציה בסגנון OpenAI ({type: "function", function: {name, description, parameters}}) שמסבירה ל-LLM מה הכלי עושה ואילו ארגומנטים הוא מקבל.
  2. נקודת הקצה — כתובת ה-URL שאליה השרתים של ThunderPhone קוראים כאשר ה-LLM מחליט להשתמש בכלי. הבקשה היא JSON POST עם הארגומנטים שבחר ה-LLM כגוף הבקשה.

1. בחרו אסטרטגיית אחסון

מוטמע בסוכן

צרפו כלי חד-פעמי למערך tools של הסוכן. פשוט, אך אינו ניתן לשימוש חוזר.

שילוב שמור

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

2. צרו את השילוב

שמרו את ה-id שהוחזר (UUID).
השקיעו מאמץ ממשי ב-description של הכלי ושל כל פרמטר. ה-LLM משתמש במחרוזות אלה בזמן הריצה כדי להחליט אם וכיצד לקרוא לכלי. תיאורים מעורפלים → קריאות כלי מעורפלות.

3. בדקו את נקודת הקצה בארגז חול

לפני שתקשרו את השילוב לסוכן, שלחו בקשה חתומה מהשרתים של ThunderPhone כדי לאשר קישוריות:
Response
בדיקה זו גם מחזקת את הגנות ה-SSRF של ThunderPhone — בקשות אל localhost או אל טווחי IP פרטיים מחזירות 400 code=url_not_allowed.

4. קשרו את האינטגרציה לסוכן

צרפו באמצעות integration_ids בעת יצירה או עדכון של סוכן:
ניתן לקשר אינטגרציות רבות לסוכן אחד. הפרומפט של הסוכן יכול להפנות אליהן לפי שם — “השתמשו ב-get_weather כשהמתקשר שואל על תנאי מזג האוויר” — או לגלות אותן במרומז מתיאורי הסכמה.

5. ממשו את נקודת הקצה

כאשר הסוכן מפעיל את הכלי, ThunderPhone שולחת בקשת POST חתומה אל endpoint_url שלכם:
השרת שלכם מחזיר JSON שמועבר בחזרה אל ה-LLM:
ה-LLM מעבד את התגובה ומציג למתקשר סיכום בשפה טבעית.
החתימה מחושבת על גוף הבקשה הגולמי באמצעות אותו secret של נקודת הקצה שלכם ל-webhook. אמתו אותה — נקודות קצה של כלים חשופות לאינטרנט ונתונות לאותם חששות זיוף כמו webhooks. ראו אימות חתימות webhook.

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 לתמלול ולהיסטוריה

בדקו את כל המסלול הלוך ושוב של קריאה לכלי.