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

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

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

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

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

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

```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` | מספר שלם | כן | מזהה הסוכן (או מזהה מספר הטלפון) |
| `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"`.

התגובה היא [אובייקט הרצת סימולציה](/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
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` של מזהי הרצות צאצא. אחזרו את
סטטוס האצווה:

```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

צרו חבילת בקרת שחרור בדף **סימולציות**
(`/dashboard/simulations`) — בחרו את הסוכן, הוסיפו תרחישים ידנית או
לחצו על **יצירת תרחישים באמצעות AI** כדי לנסח אותם מתוך
ההנחיה של הסוכן (עם מעבר אופציונלי למקרי קצה), וקבצו אותם לחבילה.
חבילה מקבעת את התרחישים ואת הסוכן שלה, וכן שיעור מעבר מינימלי וכלל אופציונלי של אפס כשלים קריטיים. הרצות שעוברות הופכות לקו הבסיס המאושר; מעברים מאוחרים יותר ממעבר לכישלון מוחזרים כרגרסיות.

השתמשו ב[מפתח API ארגוני](/api-reference/developer-api-keys) ב-CI.
סקריפט זה מפעיל את החבילה, מבצע תשאול עד להשלמת הדירוג וההשוואה,
ויוצא עם קוד שאינו אפס אלא אם פסק הדין הוא `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` מחזיר `202` עם מזהה
ההרצה. `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` מחזיר
`status`, `verdict`, `pass_rate`, `critical_failure_count` ואת רשימת
`regressions` של קו הבסיס. שני הקצוות מקשרים את הארגון בכתובת ה-URL
לארגון של מפתח ה-API.

## הריצו חבילה לפי לוח זמנים

פתחו את הכרטיסייה **סימולציה** של הסוכן, בחרו **חבילות בקרת שחרור**, וצרו או
ערכו חבילה. הפעילו את **הפעלה לפי לוח זמנים**, בחרו **תדירות** ו**אזור זמן**,
ולאחר מכן הגדירו **דקה לאחר תחילת השעה**, **זמן מקומי** או **יום** כפי
שמוצג. בחרו **שמרו חבילה**. ביטול הסימון של **הפעלה לפי לוח זמנים** מסיר את
לוח הזמנים מלוח הבקרה.

### באמצעות 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`; אין webhook להשלמה ברמת החבילה. שיחות מתוזמנות
מחויבות באותו תעריף סימולציה כמו הרצות חבילה ידניות ומתעדות את
`trigger: "schedule"` בהרצת החבילה.

כדי להשהות לוח זמנים בלי לשנות את התזמון שלו, עדכנו באמצעות PATCH את אובייקט
לוח הזמנים הקיים המלא עם `"enabled": false`. השדה `frequency` נדרש; שדות אזור
זמן ושעה שהושמטו מתאפסים לערכי ברירת המחדל שלהם, לכן כללו את הערכים הקיימים.
שלחו `"schedule": null` כדי להסיר את לוח הזמנים.

## דפוסים

### קורפוס רגרסיה לכל הנחיה

תחזקו קובץ JSON של טאפלות `{name, scenario_prompt, expected_outcome}`.
בכל שינוי בהנחיה, הריצו את המערך המלא כאצווה; השוו את
התמלילים והציונים להרצה הקודמת.

### בדיקת עשן לכל הפצה

אצווה יחידה של חמישה תרחישים במסלול תקין שתריצו לאחר כל
פריסה. רגישה לזמן השהיה, לכן השאירו את `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>