ThunderPhone 2.0 متاح الآن.خدمة ذاتية، ابتداءً من 2 سنت/دقيقة.اقرأ الإعلان
ابدأ الآن

Developer cookbook

إنشاء تكامل أداة (API)

اسمح لوكيلك باستدعاء واجهات API الخاصة بك أثناء المحادثة — البحث في قاعدة بيانات، وإنشاء تذكرة، والبحث عن طلب.

تكامل أداة هو نقطة نهاية HTTP قابلة لإعادة الاستخدام يمكن للوكيل استدعاؤها أثناء مكالمة. تزوّد ThunderPhone بوصف مخطط JSON للأداة بالإضافة إلى عنوان URL لنقطة النهاية؛ ويقرر الوكيل متى يستدعيها بناءً على المحادثة، ثم تُجري ThunderPhone طلب HTTP صادرًا من خوادمها وتعيد الاستجابة إلى الوكيل.

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

بنية الأداة

جزآن:

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

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 تُعاد إلى نموذج اللغة الكبير:

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

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

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.

أخطاء شائعة

الوكيل لا يستدعي الأداة أبدًا

يقرر نموذج اللغة الكبير بناءً على وصف الأداة. إذا لم يتطابق سؤال المتصل مع الوصف، فلن يستدعي النموذج الأداة. حسّن الوصف (أضف المرادفات والصياغات الشائعة) أو اذكرها صراحةً في موجّه الوكيل ("عندما يسأل المتصل عن الطقس، استخدم get_weather.").

تعيد الأداة بيانات كثيرة جدًا

تُقتطع الاستجابات التي تتجاوز 6 كيلوبايت في معاينة النص المفرغ. أعد الحقول التي يحتاجها نموذج اللغة الكبير فقط — وليس الصف كاملًا.

انتهاء المهلة

تحتوي نقاط نهاية الأدوات على مهلة افتراضية مدتها 10 ثوانٍ. إذا احتجت إلى مدة أطول، عالج الأمر بشكل غير متزامن: أعد {"status": "pending", "request_id": "..."} واعرض النتيجة عبر استدعاء أداة منفصل.

إدارة الإصدارات

ينشئ كل PATCH للتكامل مراجعة جديدة. افحص GET /v1/integrations/{id}/versions لمعرفة من غيّر ماذا. إذا أفسدت مخطط أداة، يمكنك التراجع يدويًا بإرسال PATCH للقطات أقدم مرة أخرى.

الخطوات التالية

مرجع التكاملات

CRUD، النقل، سجل الإصدارات.

مواصفات أدوات الدوال

قواعد JSON Schema الكاملة وعقد نقطة النهاية الموقّعة.

التحقق من التوقيعات

طبّق نمط توقيع webhook على نقاط نهاية الأدوات.

واجهة برمجة تطبيقات النص المفرغ + السجل

افحص الدورة الكاملة ذهابًا وإيابًا لاستدعاء أداة.