Developer cookbook

בדיקת סוכן מקצה לקצה (API)

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

איטרציה על סוכן AI משמעה איטרציה על ההנחיה שלו, על הכלים שלו ועל האופן שבו הוא מטפל במקרי קצה. ה-API של הסימולציות מריץ שיחות אמיתיות מול סוכן באמצעות הנחיית תרחיש שאתם מספקים. מיקוד בסוכן יוצר הרצה מבוט לבוט; מיקוד במספר טלפון יוצר הרצת לולאת SIP. כל הרצה מפיקה יומן שיחה אמיתי עם תמלול, דירוג וחיוב, כך שתוכלו לראות בדיוק כיצד הסוכן מתנהג ומה העלות שלו.

השתמשו בו עבור:

• בדיקות עשן לפני פריסה לאחר כל עריכת הנחיה
• מערכי בדיקות רגרסיה המחוברים ל-CI (חברו את ה-webhook test-call.completed → הכשילו את ה-build אם הציון יורד)
• בדיקות עומס של מגבלות מקביליות

הרצה חד-פעמית: הרצה בודדת#

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". בצעו polling עד ש-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) — בחרו את הסוכן, הוסיפו תרחישים ידנית או לחצו על יצירת תרחישים באמצעות AI כדי לנסח אותם מתוך הנחיית הסוכן (עם מעבר אופציונלי למקרי קצה), וקבצו אותם לחבילה. חבילה מקבעת את התרחישים והסוכן שלה, וכן שיעור הצלחה מינימלי וכלל אופציונלי של אפס כשלים קריטיים. הרצות שעוברות הופכות לקו הבסיס המאושר; מעברים עתידיים ממעבר לכישלון מוחזרים כרגרסיות.

השתמשו במפתח 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 מכל יומן שיחה שהתקבל.

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