> ## 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 لاستدعاءات الاختبار كي تُكتشف حالات التراجع قبل أن يسمعها العملاء.

<Note>
  هل تفضّل لوحة التحكم؟ تتوفر الإمكانية نفسها في **Simulations**
  (`/dashboard/simulations`)، بما في ذلك إنشاء السيناريوهات بالذكاء الاصطناعي — راجع
  [محاكاة مكالمة](/ar/guides/simulate-a-call). تغطي هذه الصفحة
  المسار البرمجي.
</Note>

يعني التكرار على وكيل ذكاء اصطناعي التكرار على موجّهه وأدواته
وطريقة تعامله مع الحالات الطرفية. تُجري **واجهة test-calls البرمجية** مكالمات فعلية
(من روبوت إلى روبوت أو عبر حلقة SIP) مع وكيل باستخدام موجّه سيناريو
توفره — ينتج عن كل تشغيل سجل مكالمة فعلي يتضمن
نصًا مفرغًا وتقييمًا وفوترة، لكي ترى بدقة كيف يتصرف الوكيل
وكم تبلغ تكلفته.

استخدمها من أجل:

* اختبارات تحقق سريعة قبل النشر بعد كل تعديل على الموجّه
* مجموعات اختبار الانحدار المرتبطة بالتكامل المستمر CI (اربط webhook `test-call.completed`
  ← وأفشل عملية البناء إذا انخفضت النتيجة)
* اختبار الضغط على حدود التزامن

## تشغيل واحد: تنفيذ منفرد

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/test-calls \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type":     "agent",
    "target_id":       12,
    "direction":       "outbound",
    "scenario_prompt": "You are a polite caller asking about refund policy for order 12345.",
    "consent_to_charge": true
  }'
```

الحقول:

| الحقل               | النوع   | مطلوب   | الوصف                                                             |
| ------------------- | ------- | ------- | ----------------------------------------------------------------- |
| `target_type`       | string  | نعم     | `agent` أو `phone_number`                                         |
| `target_id`         | integer | نعم     | معرّف الوكيل (أو معرّف رقم الهاتف)                                |
| `direction`         | string  | نعم     | `outbound` (الروبوت يجري المكالمة) أو `inbound` (الروبوت يجيب)    |
| `scenario_prompt`   | string  | لا      | يحدد ما يقوله روبوت الاختبار                                      |
| `mode`              | string  | لا      | `bot` (من روبوت إلى روبوت، الافتراضي) أو `sip` (حلقة SIP)         |
| `consent_to_charge` | boolean | **نعم** | يجب أن تكون `true`. تبلغ تكلفة مكالمات الاختبار ضعفي السعر العادي |
| `target_number`     | string  | لا      | تجاوز لمعرّف المتصل الخاص بالروبوت (E.164)                        |

تكون الاستجابة [كائن تشغيل مكالمة اختبار](/api-reference/test-calls#test-call-run-object)
بحالة `status="queued"`. استعلم دوريًا إلى أن تصبح `status` هي `completed` أو
`failed`؛ وبعد تعيين `call_id`، حمّل النص المفرغ عبر
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript).

## الدُفعات: سيناريوهات متوازية

شغّل N سيناريوهات بالتزامن — مفيد لمجموعات اختبار الانحدار التي
تغطي كل حالة طرفية معروفة بالتوازي:

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/test-call-batches \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "target_type":     "agent",
    "target_id":       12,
    "direction":       "outbound",
    "run_count":       5,
    "stagger_seconds": 2,
    "scenario_prompts": [
      "Ask about refund policy.",
      "Ask for hours of operation.",
      "Complain about a delayed shipment.",
      "Ask to speak with a human.",
      "Ask an unrelated trivia question."
    ],
    "consent_to_charge": true
  }'
```

تحمل الاستجابة قائمة `run_ids` لمعرّفات عمليات التشغيل الفرعية. اجلب
حالة الدفعة:

```bash theme={null}
curl https://api.thunderphone.com/v1/test-call-batches/{batch_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

يقتصر `run_count` على 20؛ وتفصل `stagger_seconds` بين عمليات الإنشاء
لتجنب إرهاق الوكيل (0–60 ثانية).

## وصّلها بـ CI

أنشئ مجموعة بوابة إصدار في صفحة **المحاكاة**
(`/dashboard/simulations`) — اختر الوكيل، وأضف السيناريوهات يدويًا أو
انقر **إنشاء سيناريوهات باستخدام الذكاء الاصطناعي** لصياغتها استنادًا إلى
موجّه الوكيل (مع تمرير اختياري للحالات الطرفية)، ثم جمّعها في مجموعة.
تثبّت المجموعة سيناريوهاتها ووكيلها، إضافةً إلى حد أدنى لمعدل النجاح وقاعدة
اختيارية لعدم وجود أي إخفاقات حرجة. تصبح عمليات التشغيل الناجحة خط الأساس
المعتمد؛ وتُعاد انتقالات النجاح→الإخفاق اللاحقة باعتبارها حالات تراجع.

استخدم [مفتاح API للمؤسسة](/api-reference/developer-api-keys) في CI.
يشغّل هذا البرنامج النصي المجموعة، ويستعلم دوريًا حتى يكتمل التقييم والمقارنة،
ويخرج برمز غير صفري ما لم يكن الحكم `pass`:

```bash theme={null}
#!/usr/bin/env bash
set -euo pipefail

: "${THUNDERPHONE_API_KEY:?Set THUNDERPHONE_API_KEY}"
: "${THUNDERPHONE_ORG_ID:?Set THUNDERPHONE_ORG_ID}"
: "${THUNDERPHONE_SUITE_ID:?Set THUNDERPHONE_SUITE_ID}"

base="https://api.thunderphone.com/v1/orgs/${THUNDERPHONE_ORG_ID}/suites/${THUNDERPHONE_SUITE_ID}"
auth="Authorization: Bearer ${THUNDERPHONE_API_KEY}"

run_id="$(curl --fail --silent --show-error -X POST "${base}/run" \
  -H "$auth" -H "Content-Type: application/json" -d '{}' | jq -r '.id')"

deadline=$((SECONDS + 1800))
while (( SECONDS < deadline )); do
  result="$(curl --fail --silent --show-error \
    "${base}/runs/${run_id}" -H "$auth")"
  status="$(jq -r '.status' <<<"$result")"
  if [[ "$status" == "completed" ]]; then
    jq . <<<"$result"
    [[ "$(jq -r '.verdict' <<<"$result")" == "pass" ]]
    exit
  fi
  sleep 10
done

echo "ThunderPhone suite timed out" >&2
exit 1
```

يعيد `POST /v1/orgs/{org_id}/suites/{suite_id}/run` الرمز `202` مع
معرّف التشغيل. ويعيد `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}`
القيم `status` و`verdict` و`pass_rate` و`critical_failure_count` وقائمة
`regressions` لخط الأساس. تربط كلتا نقطتي النهاية مؤسسة عنوان URL
بمؤسسة مفتاح API.

## الأنماط

### سجل تراجع لكل موجّه

احتفظ بملف JSON من صفوف `{name, scenario_prompt, expected_outcome}`.
مع كل تغيير في الموجّه، شغّل المجموعة الكاملة كدفعة؛ وقارن النصوص المفرغة
والدرجات بعملية التشغيل السابقة.

### اختبار دخاني لكل إصدار

دفعة واحدة تضم خمسة سيناريوهات للمسار السليم تشغّلها بعد كل نشر.
حساسة لزمن الاستجابة، لذا أبقِ `stagger_seconds: 0`.

### قياس الأداء المرجعي لزمن الاستجابة

شغّل سيناريوهات متطابقة مقابل مستويات منتجات مختلفة (`spark`،
`bolt`، `storm-base`). قارن درجات `call.graded` وقيمة
`duration_seconds` من سجل كل مكالمة ناتجة.

***

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

<CardGroup cols={2}>
  <Card title="مرجع مكالمات الاختبار" icon="flask" href="/api-reference/test-calls">
    كل معلمة استعلام، ورمز حالة، وبنية دفعة.
  </Card>

  <Card title="التقييم بالذكاء الاصطناعي" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    قيّم تلقائيًا كل تشغيل اختبار لتتبّع الجودة بمرور الوقت.
  </Card>

  <Card title="تقارير المشكلات" icon="triangle-exclamation" href="/api-reference/issue-reports">
    علّم اختبارات محددة للمراجعة البشرية.
  </Card>

  <Card title="خطاف الويب test-call.completed" icon="bolt" href="/ar/webhooks/events">
    بث النتائج إلى CI / Slack / PagerDuty.
  </Card>
</CardGroup>