בנו אינטגרציית כלים (API)

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

שילוב כלי הוא נקודת קצה לשימוש חוזר מסוג HTTP שסוכן יכול להפעיל במהלך שיחה. אתם מספקים ל-ThunderPhone תיאור מסוג JSON Schema של הכלי לצד כתובת URL של נקודת קצה; הסוכן מחליט מתי לקרוא לה על סמך השיחה, ו-ThunderPhone שולחת את בקשת ה-HTTP היוצאת מהשרתים שלה ומחזירה את התגובה לסוכן.

מדריך זה מסביר כיצד לבנות כלי לחיפוש מזג אוויר מקצה לקצה.

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

שני חלקים:

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

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

מוטמע בסוכן

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

שילוב שמור

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

מדריך זה משתמש בנתיב של שילוב שמור.

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

curl -X POST https://api.thunderphone.com/v1/integrations \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Weather API",
    "spec": {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Return the current weather for a zip code.",
        "parameters": {
          "type": "object",
          "properties": {
            "zip": { "type": "string", "description": "5-digit US ZIP code" }
          },
          "required": ["zip"]
        }
      }
    },
    "endpoint_url":    "https://api.example.com/weather",
    "endpoint_method": "GET",
    "headers": [
      { "key": "X-Api-Key", "value": "your-provider-key" }
    ]
  }'

שמרו את ה-id שהוחזר (UUID).

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

לפני שתקשרו את השילוב לסוכן, שלחו בקשה חתומה מהשרתים של ThunderPhone כדי לאשר קישוריות:

curl -X POST https://api.thunderphone.com/v1/integrations/test-request \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url":    "https://api.example.com/weather?zip=94110",
    "method": "GET",
    "headers": { "X-Api-Key": "your-provider-key" }
  }'

Response

{
  "ok": true,
  "status": 200,
  "elapsed_ms": 187,
  "response_headers": { "content-type": "application/json" },
  "response_preview": "{\"temperature_f\": 64, ...}"
}

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

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

צרפו באמצעות integration_ids בעת יצירה או עדכון של סוכן:

curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_ids": ["f9b5a1a4-..."]
  }'

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

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

כאשר הסוכן מפעיל את הכלי, ThunderPhone שולחת בקשת POST חתומה אל endpoint_url שלכם:

POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature: <HMAC-SHA256 hex>
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json

{"zip": "94110"}

השרת שלכם מחזיר JSON שמועבר בחזרה אל ה-LLM:

{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}

ה-LLM מעבד את התגובה ומציג למתקשר סיכום בשפה טבעית.

6. בדקו את הלולאה

הפעילו סשן מיקרופון מול הסוכן ושאלו את השאלה שהכלי שלכם מטפל בה ("מה מזג האוויר ב-94110?"). תמליל השיחה מציג את כל התהליך מקצה לקצה:

{
  "call_id": 987654321,
  "transcripts": [
    { "role": "user",
      "content": "What's the weather in 94110?" },
    { "role": "tool_call",
      "content": "{\"tool_call\": \"get_weather\", \"arguments\": {\"zip\": \"94110\"}}" },
    { "role": "tool_response",
      "content": "{\"tool_name\": \"get_weather\", \"response\": {\"temperature_f\": 64, \"condition\": \"Partly cloudy\"}}" },
    { "role": "agent",
      "content": "It's 64 degrees and partly cloudy." }
  ]
}

ניתן לשלוף זאת באמצעות 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 לתמלול ולהיסטוריה

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