Developer cookbook

किसी एजेंट का एंड-टू-एंड परीक्षण करें (API)

ThunderPhone API के माध्यम से वन-शॉट सिमुलेशन, समानांतर सिनेरियो बैच और रिलीज़-गेट सूट चलाएं, ताकि ग्राहकों के सुनने से पहले एजेंट रिग्रेशन पकड़े जा सकें।

AI एजेंट पर इटरेट करने का मतलब उसके प्रॉम्प्ट, टूल्स, और एज केस हैंडल करने के तरीके पर इटरेट करना है। सिमुलेशंस 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 के माध्यम से ट्रांसक्रिप्ट लोड करें।

बैच: समानांतर सिनेरियो#

कई सिनेरियो एक साथ चलाएँ — उन रिग्रेशन सूट के लिए उपयोगी जो हर ज्ञात एज केस को समानांतर रूप से टेस्ट करते हैं:

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 में जोड़ें#

Simulations पेज (/dashboard/simulations) पर एक रिलीज़ गेट सुइट बनाएं — एजेंट चुनें, हाथ से सिनेरियो जोड़ें या एजेंट के प्रॉम्प्ट से उन्हें ड्राफ्ट करने के लिए AI से सिनेरियो जनरेट करें पर क्लिक करें (वैकल्पिक एज-केस पास के साथ), और उन्हें एक सुइट में ग्रुप करें। एक सुइट अपने सिनेरियो और एजेंट के साथ-साथ न्यूनतम पास रेट और वैकल्पिक शून्य-क्रिटिकल-फेल्योर नियम को पिन करता है। पास होने वाले रन स्वीकृत बेसलाइन बन जाते हैं; बाद के पास→फेल ट्रांज़िशन रिग्रेशन के रूप में लौटाए जाते हैं।

CI में संगठन API key का उपयोग करें। यह स्क्रिप्ट सुइट को ट्रिगर करती है, ग्रेडिंग और तुलना पूरी होने तक पोल करती है, और वर्डिक्ट 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 key के संगठन से बाइंड करते हैं।

पैटर्न#

प्रति-प्रॉम्प्ट रिग्रेशन कॉर्पस#

{name, scenario_prompt, expected_outcome} ट्यूपल की एक JSON फ़ाइल बनाए रखें। हर प्रॉम्प्ट बदलाव पर, पूरे सेट को बैच के रूप में चलाएं; ट्रांसक्रिप्ट और ग्रेड को पिछले रन के मुकाबले डिफ करें।

प्रति-रिलीज़ स्मोक टेस्ट#

पांच हैप्पी-पाथ सिनेरियो का एक बैच, जिसे आप हर डिप्लॉय के बाद चलाते हैं। लेटेंसी-सेंसिटिव है, इसलिए stagger_seconds: 0 रखें।

लेटेंसी बेंचमार्किंग#

अलग-अलग प्रोडक्ट टियर (spark, bolt, storm-base) के विरुद्ध समान सिनेरियो चलाएं। call.graded स्कोर और हर परिणामी कॉल लॉग के duration_seconds की तुलना करें।

अगले चरण#