---
title: "ایجنٹ کو ابتدا سے انتہا تک ٹیسٹ کریں (API)"
description: "ThunderPhone API کے ذریعے یک مرحلہ سمولیشنز، متوازی منظرنامہ بیچز، اور ریلیز گیٹ سوئٹس چلائیں تاکہ صارفین کے سننے سے پہلے ایجنٹ کی ریگریشنز پکڑی جا سکیں۔"
---

<Note>
  ڈیش بورڈ کو ترجیح دیتے ہیں؟ یہی صلاحیت **Simulations**
  (`/dashboard/simulations`) میں موجود ہے، جس میں AI منظرنامہ تیار کرنا بھی شامل ہے — دیکھیں
  [کال کی نقل کریں](/ur/guides/simulate-a-call)۔ یہ صفحہ
  پروگراماتی طریقہ کار کا احاطہ کرتا ہے۔
</Note>

AI ایجنٹ کو بہتر بنانے کا مطلب اس کے prompt، اس کے ٹولز،
اور ایج کیسز کو سنبھالنے کے طریقے کو بہتر بنانا ہے۔ **simulations API** آپ کے فراہم کردہ
منظرنامہ prompt کے ذریعے ایجنٹ کے خلاف حقیقی کالز چلاتی ہے۔ کسی
ایجنٹ کو ہدف بنانے سے بوٹ سے بوٹ رن بنتا ہے؛ فون نمبر کو ہدف بنانے سے
SIP لوپ بیک رن بنتا ہے۔ ہر رن ٹرانسکرپٹ، گریڈنگ، اور بلنگ کے ساتھ ایک حقیقی
کال لاگ بناتا ہے، تاکہ آپ بالکل دیکھ سکیں کہ ایجنٹ
کیسا برتاؤ کرتا ہے اور اس کی لاگت کیا ہے۔

اسے ان کے لیے استعمال کریں:

- ہر prompt ترمیم کے بعد تعیناتی سے پہلے کے اسموک ٹیسٹس
- CI سے منسلک ریگریشن سوئٹس (`test-call.completed` ویب ہک
  → اگر اسکور کم ہو تو بلڈ ناکام کریں)
- کنکرنسی حدود کی اسٹریس ٹیسٹنگ

## ایک بار: واحد رن

```bash
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
  }'
```

فیلڈز:

| فیلڈ | قسم | ضروری | وضاحت |
|-------|------|----------|-------------|
| `target_type` | اسٹرنگ | ہاں | `agent` یا `phone_number` |
| `target_id` | انٹیجر | ہاں | ایجنٹ id (یا فون نمبر id) |
| `direction` | اسٹرنگ | نہیں | `outbound` (ڈیفالٹ؛ ٹیسٹ کالر کال کرتا ہے) یا `inbound` (ٹیسٹ کالر جواب دیتا ہے) |
| `scenario_prompt` | اسٹرنگ | نہیں | طے کرتا ہے کہ ٹیسٹ بوٹ کیا کہے گا |
| `language` / `primary_language` | اسٹرنگ | نہیں | ٹیسٹ کالر کی زبان؛ غیر معاون کوڈز مسترد کر دیے جاتے ہیں |
| `simulator_product` | اسٹرنگ | نہیں | `testing` (ڈیفالٹ) یا زیادہ انسانی انداز کے مصنوعی کالر کے لیے `spark`، مثلاً وارم ٹرانسفر مشاورتی ٹیسٹس |
| `consent_to_charge` | بولین | **ہاں** | لازماً `true` ہونا چاہیے۔ تخمینہ منتخب ایجنٹ اور مصنوعی کالر، نیز کسی بھی ٹیلی فونی لیگ، دونوں کے لیے بل کرتا ہے |
| `target_number` | اسٹرنگ | نہیں | ریموٹ سائیڈ کے لیے E.164 اووررائیڈ؛ بصورت دیگر پلیٹ فارم کا ٹیسٹ نمبر استعمال ہوتا ہے |

`mode` صرف پڑھنے کے لیے ہے اور `target_type` سے اخذ ہوتا ہے: `agent`
سے `mode="bot"` بنتا ہے، جبکہ `phone_number` سے `mode="sip"` بنتا ہے۔

جواب میں [simulation run object](/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
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
  }'
```

جواب میں چائلڈ رن ids کی `run_ids` فہرست شامل ہوتی ہے۔ بیچ
اسٹیٹس حاصل کریں:

```bash
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`) پر ریلیز گیٹ سوئٹ بنائیں — ایجنٹ منتخب کریں، منظرنامے
دستی طور پر شامل کریں یا ایجنٹ کے prompt سے ان کے مسودے بنانے کے لیے
**AI کے ذریعے منظرنامے بنائیں** پر کلک کریں (اختیاری ایج کیس جائزے کے ساتھ)،
اور انہیں ایک سوئٹ میں گروپ کریں۔ سوئٹ اپنے منظرناموں اور ایجنٹ کے ساتھ کم از کم
پاس ریٹ اور اختیاری صفر اہم ناکامیوں کے اصول کو مقرر کر دیتا ہے۔ کامیاب رنز
قبول شدہ بنیادی معیار بن جاتے ہیں؛ بعد میں کامیابی سے ناکامی کی منتقلیاں
ریگریشنز کے طور پر واپس کی جاتی ہیں۔

CI میں [تنظیمی API کلید](/api-reference/developer-api-keys) استعمال کریں۔
یہ اسکرپٹ سوئٹ کو ٹرگر کرتا ہے، گریڈنگ اور موازنہ مکمل ہونے تک پول کرتا ہے،
اور فیصلہ `pass` نہ ہونے کی صورت میں نان زیرو کے ساتھ خارج ہو جاتا ہے:

```bash
#!/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` رن ID کے ساتھ `202` واپس کرتا
ہے۔ `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` `status`،
`verdict`، `pass_rate`، `critical_failure_count`، اور بنیادی معیار کی
`regressions` فہرست واپس کرتا ہے۔ دونوں اینڈ پوائنٹس URL کی تنظیم کو API
کلید کی تنظیم کے ساتھ منسلک کرتے ہیں۔

## شیڈول کے مطابق سوئٹ چلائیں

ایجنٹ کا **Simulate** ٹیب کھولیں، **Release gate suites** منتخب کریں، اور
سوئٹ بنائیں یا اس میں ترمیم کریں۔ **شیڈول کے مطابق چلائیں** کو آن کریں،
**فریکوئنسی** اور **ٹائم زون** منتخب کریں، پھر دکھائے گئے مطابق
**گھنٹے کے بعد منٹ**، **مقامی وقت**، یا **دن** مقرر کریں۔
**سوئٹ محفوظ کریں** منتخب کریں۔ **شیڈول کے مطابق چلائیں** کو ان چیک کرنے سے
ڈیش بورڈ کا شیڈول ہٹ جاتا ہے۔

### API کے ذریعے

شیڈول شامل کرنے یا تبدیل کرنے کے لیے سوئٹ پر PATCH کریں۔ مکمل سوئٹ آبجیکٹ
اور اینڈ پوائنٹس کے لیے [سوئٹس (ریلیز
گیٹس)](/api-reference/test-scenarios#suites-release-gates) دیکھیں۔

```bash
curl -X PATCH https://api.thunderphone.com/v1/suites/{suite_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": {
      "enabled": true,
      "frequency": "daily",
      "timezone": "America/Chicago",
      "hour": 6,
      "minute": 30
    }
  }'
```

`frequency` `hourly`، `daily`، یا `weekly` ہو سکتی ہے۔ IANA ٹائم زون استعمال
کریں۔ گھنٹہ وار شیڈولز میں `minute` استعمال ہوتا ہے؛ روزانہ شیڈولز میں `hour`
اور `minute` استعمال ہوتے ہیں؛ ہفتہ وار شیڈولز میں `weekday` بھی استعمال ہوتا
ہے، جہاں پیر `0` اور اتوار `6` ہے۔ سوئٹ کے جواب میں `next_run_at` اور
`last_run_at` شامل ہوتے ہیں۔

اوقات منتخب کردہ ٹائم زون میں ڈے لائٹ سیونگ کی تبدیلیوں کے مطابق ہوتے ہیں۔
شیڈول شدہ رنز سوئٹ کی رن ہسٹری میں ظاہر ہوتے ہیں اور اس کے موجودہ ایجنٹ،
منظرنامے، معیار، اور قبول شدہ بنیادی معیار استعمال کرتے ہیں۔ ہر تیار کردہ
ٹیسٹ کال `test-call.completed` خارج کرتی ہے؛ سوئٹ کی سطح پر تکمیل کا کوئی
ویب ہک نہیں ہے۔ شیڈول شدہ کالز کی بلنگ دستی سوئٹ رنز جیسی ہی سمولیشن ریٹ پر
ہوتی ہے اور سوئٹ رن پر `trigger: "schedule"` ریکارڈ کرتی ہیں۔

ٹائمنگ تبدیل کیے بغیر شیڈول روکنے کے لیے، مکمل موجودہ شیڈول آبجیکٹ کے ساتھ
`"enabled": false` پر PATCH کریں۔ `frequency` لازمی ہے؛ چھوڑے گئے ٹائم زون
اور وقت کے فیلڈز اپنی ڈیفالٹ قدروں پر ری سیٹ ہو جاتے ہیں، اس لیے موجودہ قدریں
شامل کریں۔ شیڈول ہٹانے کے لیے `"schedule": null` بھیجیں۔

## پیٹرنز

### ہر prompt کے لیے ریگریشن کارپس

`{name, scenario_prompt, expected_outcome}`
ٹیوپلز کی ایک JSON فائل برقرار رکھیں۔ ہر prompt تبدیلی پر، مکمل سیٹ کو بیچ کے طور پر چلائیں؛
ٹرانسکرپٹس اور گریڈز کا پچھلی رن کے مقابلے میں فرق دیکھیں۔

### ہر ریلیز کے لیے اسموک ٹیسٹ

پانچ کامیاب-راستہ منظرناموں کا ایک بیچ، جسے آپ ہر
deploy کے بعد چلاتے ہیں۔ یہ لیٹنسی کے لحاظ سے حساس ہے، اس لیے `stagger_seconds: 0` رکھیں۔

### لیٹنسی بینچ مارکنگ

مختلف پروڈکٹ ٹیئرز (`spark`,
`bolt`، `storm-base`) کے خلاف یکساں منظرنامے چلائیں۔ ہر نتیجے میں آنے والے کال لاگ سے `call.graded` اسکورز اور
`duration_seconds` کا موازنہ کریں۔

---

## اگلے مراحل

<CardGroup cols={2}>
  <Card title="ٹیسٹ کالز کا حوالہ" icon="flask" href="/api-reference/test-calls">
    ہر query parameter، status code، اور بیچ کی ساخت۔
  </Card>
  <Card title="AI گریڈنگ" 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="/ur/webhooks/events">
    نتائج کو اپنی CI / Slack / PagerDuty میں اسٹریم کریں۔
  </Card>
</CardGroup>