---
title: "Jaribu ejenti kutoka mwanzo hadi mwisho (API)"
description: "Endesha simulizi za mara moja, makundi sambamba ya matukio, na seti za vigezo vya utoaji kupitia API ya ThunderPhone ili hitilafu za ejenti zibainike kabla wateja hawajazisikia."
---

<Note>
  Unapendelea dashibodi? Uwezo huu unapatikana pia katika **Uigaji**
  (`/dashboard/simulations`), ikijumuisha uundaji wa matukio kwa AI — tazama
  [Igiza simu](/sw/guides/simulate-a-call). Ukurasa huu unaelezea
  njia ya kiprogramu.
</Note>

Kuboresha ejenti ya AI kunamaanisha kuboresha prompt yake, zana zake,
na jinsi inavyoshughulikia hali za kipekee. **API ya uigaji** huendesha simu
halisi dhidi ya ejenti kwa kutumia prompt ya tukio unayotoa. Kulenga
ejenti huunda uendeshaji wa boti-kwa-boti; kulenga nambari ya simu huunda
uendeshaji wa SIP wa loopback. Kila uendeshaji huzalisha kumbukumbu halisi ya simu yenye
nakala ya mazungumzo, upimaji, na utozaji, ili uone jinsi ejenti
inavyofanya kazi na gharama yake.

Itumie kwa:

- Majaribio ya haraka kabla ya kusambaza baada ya kila uhariri wa prompt
- Mkusanyiko wa majaribio ya regresha yaliyounganishwa kwenye CI (unganisha webhook ya `test-call.completed`
  → feli uundaji ikiwa alama itashuka)
- Kupima mipaka ya utendakazi wa wakati mmoja chini ya mzigo

## Uendeshaji wa mara moja: uendeshaji mmoja

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

Sehemu:

| Sehemu | Aina | Inahitajika | Maelezo |
|-------|------|----------|-------------|
| `target_type` | string | ndiyo | `agent` au `phone_number` |
| `target_id` | integer | ndiyo | Kitambulisho cha ejenti (au kitambulisho cha nambari ya simu) |
| `direction` | string | hapana | `outbound` (chaguo-msingi; mpigaji wa majaribio hupiga simu) au `inbound` (mpigaji wa majaribio hujibu) |
| `scenario_prompt` | string | hapana | Huongoza kile ambacho boti ya majaribio husema |
| `language` / `primary_language` | string | hapana | Lugha ya mpigaji wa majaribio; misimbo isiyotumika hukataliwa |
| `simulator_product` | string | hapana | `testing` (chaguo-msingi) au `spark` kwa mpigaji simu aliyeigwa anayefanana zaidi na binadamu, kama majaribio ya mashauriano ya warm-transfer |
| `consent_to_charge` | boolean | **ndiyo** | Lazima iwe `true`. Makadirio hutoza ejenti iliyochaguliwa na mpigaji simu aliyeigwa, pamoja na njia yoyote ya telefoni |
| `target_number` | string | hapana | Ubadilishaji wa E.164 kwa upande wa mbali; vinginevyo nambari ya majaribio ya jukwaa hutumika |

`mode` ni ya kusoma pekee na hutokana na `target_type`: `agent` huzalisha
`mode="bot"`, huku `phone_number` huzalisha `mode="sip"`.

Jibu ni [kitu cha uendeshaji wa uigaji](/api-reference/test-calls#test-call-run-object)
katika `status="queued"`. Kagua mara kwa mara hadi `status` iwe
`completed` au `failed`; pindi `call_id` inapowekwa, pakia nakala ya mazungumzo kupitia
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript).

## Makundi: matukio sambamba

Endesha matukio N kwa wakati mmoja — muhimu kwa mikusanyiko ya majaribio ya regresha ambayo
hushughulikia kila hali ya kipekee inayojulikana kwa sambamba:

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

Jibu lina orodha ya `run_ids` ya vitambulisho vya uendeshaji wa watoto. Leta hali ya kundi:

```bash
curl https://api.thunderphone.com/v1/simulations/batches/{batch_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

`run_count` ina kikomo cha 20; `stagger_seconds` hutenganisha uanzishaji
ili kuepuka kuilemea ejenti (0–60 s).

## Iunganishe kwenye CI

Unda kikundi cha kizuizi cha toleo kwenye ukurasa wa **Uigaji**
(`/dashboard/simulations`) — chagua ejenti, ongeza matukio mwenyewe au
bofya **Tengeneza matukio kwa AI** ili kuyatayarisha kutoka kwenye
prompt ya ejenti (ukiwa na hiari ya kupitia matukio ya kipekee), kisha
yapange katika kikundi. Kikundi hufunga matukio na ejenti wake, pamoja na
kiwango cha chini cha ufaulu na kanuni ya hiari ya kutokuwa na hitilafu
zozote muhimu. Uendeshaji unaofaulu huwa msingi unaokubalika; mabadiliko
ya baadaye kutoka ufaulu→kufeli hurudishwa kama kurudi nyuma.

Tumia [ufunguo wa API wa shirika](/api-reference/developer-api-keys) katika CI.
Hati hii huanzisha kikundi, hufuatilia hadi ukadiriaji na ulinganishaji
vikamilike, na hutoka kwa msimbo usio sifuri isipokuwa uamuzi ni `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` hurejesha `202` pamoja na
kitambulisho cha uendeshaji. `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` hurejesha
`status`, `verdict`, `pass_rate`, `critical_failure_count`, na orodha ya
`regressions` ya msingi. Ncha zote mbili hufunga shirika lililo kwenye URL
kwenye shirika la ufunguo wa API.

## Endesha kikundi kwa ratiba

Fungua kichupo cha **Uigaji** cha ejenti, chagua **Vikundi vya vizuizi vya toleo**, kisha unda au
hariri kikundi. Washa **Endesha kwa ratiba**, chagua **Marudio** na
**Saa za eneo**, kisha weka **Dakika baada ya saa**, **Saa ya eneo**, au **Siku** kama
inavyoonyeshwa. Chagua **Hifadhi kikundi**. Kuondoa uteuzi wa **Endesha kwa ratiba** huondoa
ratiba ya dashibodi.

### Kupitia API

Tumia PATCH kwenye kikundi ili kuongeza au kubadilisha ratiba yake. Tazama [Vikundi (vizuizi vya
toleo)](/api-reference/test-scenarios#suites-release-gates) kwa objekti kamili ya
kikundi na ncha zake.

```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` inaweza kuwa `hourly`, `daily`, au `weekly`. Tumia saa za eneo za IANA.
Ratiba za kila saa hutumia `minute`; ratiba za kila siku hutumia `hour` na `minute`;
ratiba za kila wiki pia hutumia `weekday`, ambapo Jumatatu ni `0` na Jumapili ni `6`.
Jibu la kikundi linajumuisha `next_run_at` na `last_run_at`.

Nyakati hufuata mabadiliko ya saa za majira ya joto ya saa za eneo zilizochaguliwa. Uendeshaji
uliopangwa huonekana katika historia ya uendeshaji ya kikundi na hutumia ejenti, matukio,
vigezo, na msingi wake unaokubalika wa sasa. Kila simu ya jaribio inayotengenezwa hutoa
`test-call.completed`; hakuna webhook ya ukamilishaji ya kiwango cha kikundi. Simu zilizopangwa
hutozwa kwa kiwango kilekile cha uigaji kama uendeshaji wa kikundi wa mkono na hurekodi
`trigger: "schedule"` kwenye uendeshaji wa kikundi.

Ili kusitisha ratiba bila kubadilisha muda wake, tumia PATCH kwenye objekti kamili ya ratiba
iliyopo kwa `"enabled": false`. `frequency` inahitajika; saa za eneo na sehemu za muda
zilizoachwa huwekwa upya kwenye chaguo-msingi, kwa hiyo jumuisha thamani zilizopo.
Tuma `"schedule": null` ili kuondoa ratiba.

## Mifumo

### Hazina ya urejeshi kwa kila prompt

Dumisha faili ya JSON ya tupli za `{name, scenario_prompt, expected_outcome}`. Kila prompt inapobadilishwa, endesha seti nzima kama batch; linganisha transkripti na alama dhidi ya utekelezaji uliopita.

### Jaribio la haraka kwa kila toleo

Batch moja ya hali tano za njia tarajiwa unayoendesha baada ya kila deploy. Inazingatia latency, kwa hivyo weka `stagger_seconds: 0`.

### Upimaji wa latency

Endesha hali zinazofanana dhidi ya viwango tofauti vya bidhaa (`spark`, `bolt`, `storm-base`). Linganisha alama za `call.graded` na `duration_seconds` kutoka kwenye kila kumbukumbu ya simu inayotokana.

---

## Hatua zinazofuata

<CardGroup cols={2}>
  <Card title="Marejeleo ya simu za majaribio" icon="flask" href="/api-reference/test-calls">
    Kila kigezo cha query, msimbo wa hali, na muundo wa batch.
  </Card>
  <Card title="Upangaji alama wa AI" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Toa alama kiotomatiki kwa kila utekelezaji wa jaribio ili kufuatilia ubora kadri muda unavyopita.
  </Card>
  <Card title="Ripoti za hitilafu" icon="triangle-exclamation" href="/api-reference/issue-reports">
    Weka alama kwenye majaribio mahususi kwa ukaguzi wa kibinadamu.
  </Card>
  <Card title="test-call.completed webhook" icon="bolt" href="/sw/webhooks/events">
    Tuma matokeo kwa mtiririko kwenye CI / Slack / PagerDuty yako.
  </Card>
</CardGroup>