> ## 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 של test-calls, כדי לאתר רגרסיות לפני שהלקוחות שומעים אותן.

<Note>
  מעדיפים את לוח הבקרה? אותה יכולת זמינה ב-**סימולציות**
  (`/dashboard/simulations`), כולל יצירת תרחישים באמצעות AI — ראו
  [סימולציית שיחה](/he/guides/simulate-a-call). דף זה עוסק
  בנתיב התכנותי.
</Note>

איטרציה על סוכן AI משמעה איטרציה על ההנחיה שלו, הכלים שלו
והאופן שבו הוא מטפל במקרי קצה. ה-API **test-calls** מפעיל שיחות אמיתיות
(בוט-לבוט או לולאת SIP) מול סוכן באמצעות הנחיית תרחיש שאתם מספקים — כל
הרצה מפיקה יומן שיחה אמיתי עם תמלול, דירוג וחיוב, כך שתוכלו לראות בדיוק
כיצד הסוכן מתנהג ומה עלותו.

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

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

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

```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`. שיחות בדיקה עולות פי 2 מהתעריף הרגיל |
| `target_number`     | string  | לא     | דריסה של מזהה המתקשר של הבוט (E.164)                    |

התגובה היא [אובייקט הרצת שיחת בדיקה](/api-reference/test-calls#test-call-run-object)
ב-`status="queued"`. בצעו polling עד ש-`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`) — בחרו את הסוכן, הוסיפו תרחישים ידנית או
לחצו על **יצירת תרחישים באמצעות AI** כדי לנסח אותם מתוך
הפרומפט של הסוכן (עם מעבר אופציונלי למקרי קצה), וקבצו אותם לחבילה.
חבילה מקבעת את התרחישים ואת הסוכן שלה, לצד שיעור הצלחה מינימלי וכלל
אופציונלי של אפס כשלים קריטיים. הרצות שעוברות הופכות לקו הבסיס המאושר;
מעברים מאוחרים יותר ממעבר לכישלון מוחזרים כרגרסיות.

השתמשו ב[מפתח API של הארגון](/api-reference/developer-api-keys) ב-CI.
סקריפט זה מפעיל את החבילה, מבצע polling עד שהדירוג וההשוואה
מושלמים, ויוצא עם קוד שאינו אפס אלא אם פסק הדין הוא `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}`.
בכל שינוי בפרומפט, הריצו את כל הקבוצה כאצווה; השוו את התמלילים והדירוגים
להרצה הקודמת.

### בדיקת smoke לכל שחרור

אצווה יחידה של חמישה תרחישים במסלול תקין שאתם מריצים לאחר כל
פריסה. רגישה לזמן אחזור, לכן השאירו את `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="דירוג 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="webhook של test-call.completed" icon="bolt" href="/he/webhooks/events">
    הזרימו תוצאות אל ה-CI / Slack / PagerDuty שלכם.
  </Card>
</CardGroup>