> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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

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

<Note>
  לוח הבקרה מכסה את רוב צורכי הכלים ללא API זה: **חיבורים
  → אפליקציות** מחבר את Slack, HubSpot, Salesforce, Google Calendar,
  Google Sheets ו-Cal.com בכמה לחיצות OAuth; **חיבורים →
  ממשקי API** הופך כל API מסוג HTTP לפעולה של סוכן (הדביקו פקודת cURL
  ואשף AI יכין טיוטה של הכלי, עם בדיקת בקשה מובנית); ו-**חיבורים → MCP**
  מוסיף שרתי MCP. ראו
  [חיבורים](/he/guides/concepts). מדריך זה עוסק ב-API הבסיסי
  שמתחת לממשק ממשקי ה-API.
</Note>

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

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

שני חלקים:

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

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

<CardGroup cols={2}>
  <Card title="מוטמע בסוכן" icon="paperclip">
    צרפו כלי חד-פעמי למערך `tools` של הסוכן. פשוט, אך
    אינו ניתן לשימוש חוזר.
  </Card>

  <Card title="שילוב שמור" icon="plug">
    אחסנו את הכלי כ-[שילוב](/api-reference/integrations) לשימוש חוזר
    וקשרו אותו מסוכנים רבים. מומלץ לכל דבר שנעשה בו שימוש יותר
    מפעם אחת.
  </Card>
</CardGroup>

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

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

```bash theme={null}
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).

<Tip>
  השקיעו מאמץ ממשי ב-`description` של הכלי ושל כל
  פרמטר. ה-LLM משתמש במחרוזות אלה בזמן הריצה כדי להחליט אם
  וכיצד לקרוא לכלי. תיאורים מעורפלים → קריאות כלי מעורפלות.
</Tip>

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

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

```bash theme={null}
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" }
  }'
```

```json Response theme={null}
{
  "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` בעת יצירה או עדכון של סוכן:

```bash theme={null}
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:

```json theme={null}
{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}
```

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

<Warning>
  החתימה מחושבת על גוף הבקשה הגולמי באמצעות אותו
  `secret` של נקודת הקצה שלכם ל-webhook. **אמתו אותה** — נקודות קצה
  של כלים חשופות לאינטרנט ונתונות לאותם חששות זיוף כמו
  webhooks. ראו
  [אימות חתימות webhook](/he/guides/verify-webhook-signatures).
</Warning>

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

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

```json theme={null}
{
  "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`](/api-reference/calls#get-transcript);
זרם האירועים הגולמי (עם תזמון לכל רשומה והיסטי אודיו) זמין ב-
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history).

## תקלות נפוצות

<AccordionGroup>
  <Accordion title="הסוכן אף פעם לא מפעיל את הכלי">
    ה-LLM מחליט על סמך תיאור הכלי. אם שאלת המתקשר
    אינה תואמת לתיאור, המודל לא יפעיל
    את הכלי. דייקו את התיאור (הוסיפו מילים נרדפות וניסוחים
    נפוצים) או ציינו זאת במפורש בפרומפט של הסוכן ("כאשר
    המתקשר שואל על מזג האוויר, השתמשו ב-`get_weather`.").
  </Accordion>

  <Accordion title="הכלי מחזיר יותר מדי נתונים">
    תגובות בגודל העולה על 6 kB נחתכות בתצוגה המקדימה של התמליל. החזירו
    רק את השדות שה-LLM זקוק להם — לא את כל הרשומה שלכם.
  </Accordion>

  <Accordion title="חריגות זמן">
    לנקודות קצה של כלים יש פסק זמן ברירת מחדל של 10 שניות. אם אתם זקוקים ליותר זמן,
    טפלו בכך באופן אסינכרוני: החזירו `{"status": "pending", "request_id": "..."}`
    והציגו את התוצאה באמצעות קריאה נפרדת לכלי.
  </Accordion>

  <Accordion title="ניהול גרסאות">
    כל `PATCH` של אינטגרציה יוצר מהדורה חדשה. בדקו את
    [`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history)
    כדי לראות מי שינה מה. אם שברתם את הסכמה של כלי, תוכלו
    לחזור לאחור ידנית באמצעות PATCH של תמונת מצב ישנה יותר בחזרה.
  </Accordion>
</AccordionGroup>

***

## השלבים הבאים

<CardGroup cols={2}>
  <Card title="מדריך העזר לשילובים" icon="plug" href="/api-reference/integrations">
    CRUD, העברה, היסטוריית גרסאות.
  </Card>

  <Card title="מפרט כלי פונקציות" icon="screwdriver-wrench" href="/he/tools/overview">
    דקדוק מלא של סכמת JSON וחוזה נקודת הקצה החתומה.
  </Card>

  <Card title="אימות חתימות" icon="shield-check" href="/he/guides/verify-webhook-signatures">
    החילו את תבנית חתימת ה-webhook על נקודות קצה של כלים.
  </Card>

  <Card title="API לתמלול ולהיסטוריה" icon="phone" href="/api-reference/calls">
    בדקו את כל המסלול הלוך ושוב של קריאה לכלי.
  </Card>
</CardGroup>