Developer cookbook

اختبر وكيلاً من البداية إلى النهاية (API)

شغّل محاكاة منفردة، ودفعات سيناريوهات متوازية، وأجنحة بوابة الإصدار عبر واجهة ThunderPhone البرمجية لاكتشاف تراجعات أداء الوكيل قبل أن يسمعها العملاء.

يعني التكرار على وكيل ذكاء اصطناعي التكرار على موجّهه وأدواته وطريقة تعامله مع الحالات الطرفية. تُجري واجهة API للمحاكاة مكالمات حقيقية مع وكيل باستخدام موجّه سيناريو تقدمه أنت. يؤدي استهداف وكيل إلى تشغيل بين روبوتين؛ بينما يؤدي استهداف رقم هاتف إلى تشغيل استرجاع حلقي عبر SIP. ينتج عن كل تشغيل سجل مكالمة حقيقي يتضمن نصًا مفرغًا وتقييمًا وفوترة، لتعرف بدقة كيف يتصرف الوكيل وكم تبلغ تكلفته.

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

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

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

curl -X POST https://api.thunderphone.com/v1/simulations \
  -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
  }'

الحقول:

mode للقراءة فقط ويُشتق من target_type: ينتج agent mode="bot"، بينما ينتج phone_number ‏mode="sip".

الاستجابة هي كائن تشغيل محاكاة بحالة status="queued". استعلم دوريًا حتى تصبح status completed أو failed؛ وبعد تعيين call_id، حمّل النص المفرغ عبر GET /v1/calls/{call_id}/transcript.

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

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

curl -X POST https://api.thunderphone.com/v1/simulations/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 لمعرّفات التشغيلات الفرعية. اجلب حالة الدفعة:

curl https://api.thunderphone.com/v1/simulations/batches/{batch_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

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

اربطه بـ CI#

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

استخدم مفتاح API لمؤسسة في CI. يُشغّل هذا النص البرمجي المجموعة، ويستطلع الحالة حتى يكتمل التقييم والمقارنة، ويخرج برمز غير صفري ما لم يكن الحكم pass:

#!/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 من كل سجل مكالمة ناتج.

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