> ## 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
للأداة بالإضافة إلى عنوان URL لنقطة النهاية؛ ويقرر الوكيل متى يستدعيها
بناءً على المحادثة، ثم تُجري ThunderPhone طلب HTTP صادرًا من خوادمها
وتعيد الاستجابة إلى الوكيل.

<Note>
  تغطي لوحة التحكم معظم احتياجات الأدوات دون واجهة برمجة التطبيقات هذه: يربط **الاتصالات
  → التطبيقات** Slack وHubSpot وSalesforce وGoogle Calendar
  وGoogle Sheets وCal.com ببضع نقرات OAuth؛ ويحوّل **الاتصالات →
  واجهات برمجة التطبيقات** أي واجهة برمجة تطبيقات HTTP إلى إجراء للوكيل (الصق أمر cURL
  وسيُعدّ معالج ذكاء اصطناعي مسودة الأداة، مع اختبار طلب مضمّن)؛ ويضيف **الاتصالات → MCP**
  خوادم MCP. راجع
  [الاتصالات](/ar/guides/concepts). هذا الدليل هو واجهة
  برمجة التطبيقات الأساسية الكامنة خلف واجهات برمجة التطبيقات.
</Note>

يشرح هذا الدليل إنشاء أداة للبحث عن الطقس من البداية إلى النهاية.

## بنية الأداة

جزآن:

1. **المخطط** — تعريف دالة بأسلوب OpenAI
   (`{type: "function", function: {name, description, parameters}}`)
   يوضح لنموذج اللغة الكبير ما الذي تفعله الأداة وما الوسيطات التي تقبلها.
2. **نقطة النهاية** — عنوان URL الذي تستدعيه خوادم ThunderPhone عندما
   يقرر نموذج اللغة الكبير استخدام الأداة. يكون الطلب JSON POST مع
   الوسيطات التي اختارها نموذج اللغة الكبير في النص.

## 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` للأداة ولكل
  مَعلمة. يستخدم نموذج اللغة الكبير هذه السلاسل وقت التشغيل ليقرر ما إذا
  كان سيستدعي الأداة وكيفية استدعائها. أوصاف غامضة ← استدعاءات أدوات غامضة.
</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 تُعاد إلى نموذج اللغة الكبير:

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

يستوعب نموذج اللغة الكبير تلك الاستجابة ويتحدث بملخص مفهوم إلى
المتصل.

<Warning>
  يُحتسب التوقيع على نص الطلب الخام باستخدام `secret` نفسه
  المستخدم لنقطة نهاية webhook الخاصة بك. **تحقق منه** — نقاط نهاية
  الأدوات مكشوفة للإنترنت وتخضع لمخاوف الانتحال نفسها الخاصة بـ
  webhooks. راجع
  [التحقق من توقيعات webhook](/ar/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="الوكيل لا يستدعي الأداة أبدًا">
    يقرر نموذج اللغة الكبير بناءً على وصف الأداة. إذا لم يتطابق سؤال
    المتصل مع الوصف، فلن يستدعي النموذج الأداة. حسّن الوصف (أضف
    المرادفات والصياغات الشائعة) أو اذكرها صراحةً في موجّه الوكيل
    ("عندما يسأل المتصل عن الطقس، استخدم `get_weather`.").
  </Accordion>

  <Accordion title="تعيد الأداة بيانات كثيرة جدًا">
    تُقتطع الاستجابات التي تتجاوز 6 كيلوبايت في معاينة النص المفرغ. أعد
    الحقول التي يحتاجها نموذج اللغة الكبير فقط — وليس الصف كاملًا.
  </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="/ar/tools/overview">
    قواعد JSON Schema الكاملة وعقد نقطة النهاية الموقّعة.
  </Card>

  <Card title="التحقق من التوقيعات" icon="shield-check" href="/ar/guides/verify-webhook-signatures">
    طبّق نمط توقيع webhook على نقاط نهاية الأدوات.
  </Card>

  <Card title="واجهة برمجة تطبيقات النص المفرغ + السجل" icon="phone" href="/api-reference/calls">
    افحص الدورة الكاملة ذهابًا وإيابًا لاستدعاء أداة.
  </Card>
</CardGroup>