---
title: "Otestujte agenta od začiatku do konca (API)"
description: "Spúšťajte jednorazové simulácie, paralelné dávky scenárov a súpravy kontrol pred vydaním prostredníctvom rozhrania ThunderPhone API, aby sa regresie agenta zachytili skôr, než ich zákazníci začujú."
---

<Note>
  Uprednostňujete ovládací panel? Rovnaká funkcia je k dispozícii v časti **Simulácie**
  (`/dashboard/simulations`) vrátane generovania scenárov pomocou AI — pozrite si
  [Simulovať hovor](/sk/guides/simulate-a-call). Táto stránka opisuje
  programový postup.
</Note>

Iterovanie hlasového agenta AI znamená iterovanie jeho promptu, nástrojov
a spôsobu, akým rieši okrajové prípady. **API simulácií** uskutočňuje skutočné
hovory s agentom pomocou promptu scenára, ktorý zadáte. Cielenie na
agenta vytvorí beh bot–bot; cielenie na telefónne číslo vytvorí
SIP loopback beh. Každý beh vytvorí skutočný záznam hovoru s
prepisom, hodnotením a účtovaním, takže presne vidíte, ako sa agent
správa a koľko stojí.

Použite ho na:

- Smoke testy pred nasadením po každej úprave promptu
- Regresné súpravy prepojené s CI (pripojte webhook `test-call.completed`
  → zlyhanie buildu pri poklese skóre)
- Záťažové testovanie limitov súbežnosti

## Jednorazovo: jeden beh

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

Polia:

| Pole | Typ | Povinné | Popis |
|-------|------|----------|-------------|
| `target_type` | string | áno | `agent` alebo `phone_number` |
| `target_id` | integer | áno | ID agenta (alebo ID telefónneho čísla) |
| `direction` | string | nie | `outbound` (predvolené; testovací volajúci uskutoční hovor) alebo `inbound` (testovací volajúci hovor prijme) |
| `scenario_prompt` | string | nie | Určuje, čo testovací bot povie |
| `language` / `primary_language` | string | nie | Jazyk testovacieho volajúceho; nepodporované kódy budú odmietnuté |
| `simulator_product` | string | nie | `testing` (predvolené) alebo `spark` pre simulovaného volajúceho, ktorý pôsobí ľudskejšie, napríklad pri testoch konzultácie pred teplým prepojením |
| `consent_to_charge` | boolean | **áno** | Musí byť `true`. Účtujú sa odhadované náklady za vybraného agenta aj simulovaného volajúceho spolu s akoukoľvek telekomunikačnou vetvou |
| `target_number` | string | nie | Prepísanie vzdialenej strany vo formáte E.164; inak sa použije testovacie číslo platformy |

`mode` je iba na čítanie a odvodzuje sa z `target_type`: `agent` vytvorí
`mode="bot"`, zatiaľ čo `phone_number` vytvorí `mode="sip"`.

Odpoveď je objekt [behu simulácie](/api-reference/test-calls#test-call-run-object)
so stavom `status="queued"`. Dotazujte sa, kým sa `status` nezmení na
`completed` alebo `failed`; po nastavení `call_id` načítajte prepis cez
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript).

## Dávky: paralelné scenáre

Spustite N scenárov súčasne — užitočné pre regresné súpravy, ktoré
paralelne pokrývajú všetky známe okrajové prípady:

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

Odpoveď obsahuje zoznam `run_ids` s ID podradených behov. Načítajte stav
dávky:

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

Hodnota `run_count` je obmedzená na 20; `stagger_seconds` rozkladá spúšťanie
v čase, aby sa agent nepreťažoval (0–60 s).

## Zapojte ho do CI

Na stránke **Simulácie**
(`/dashboard/simulations`) vytvorte súpravu brány vydania — vyberte agenta, pridajte scenáre ručne alebo
kliknite na **Generovať scenáre pomocou AI**, aby ste ich vytvorili z výzvy
agenta (s voliteľným spracovaním okrajových prípadov), a zoskupte ich do súpravy.
Súprava pevne nastaví scenáre a agenta spolu s minimálnou mierou úspešnosti a
voliteľným pravidlom nulového počtu kritických zlyhaní. Úspešné spustenia sa stanú
schváleným referenčným stavom; neskoršie prechody z úspechu na zlyhanie sa vrátia ako regresie.

V CI použite [organizačný kľúč API](/api-reference/developer-api-keys).
Tento skript spustí súpravu, zisťuje stav, kým sa nedokončí hodnotenie a porovnanie,
a skončí s nenulovým kódom, ak verdikt nie je `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` vráti `202` s identifikátorom
spustenia. `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` vráti
`status`, `verdict`, `pass_rate`, `critical_failure_count` a zoznam referenčných
`regressions`. Oba koncové body viažu organizáciu v URL na organizáciu kľúča API.

## Spúšťanie súpravy podľa plánu

Otvorte kartu **Simulovať** agenta, vyberte **Súpravy brán vydania** a vytvorte
alebo upravte súpravu. Zapnite **Spúšťať podľa plánu**, vyberte **Frekvenciu** a
**Časové pásmo**, potom podľa zobrazenia nastavte **Minútu po celej hodine**,
**Miestny čas** alebo **Deň**. Vyberte **Uložiť súpravu**. Zrušením začiarknutia
možnosti **Spúšťať podľa plánu** odstránite plán v paneli.

### Prostredníctvom API

Pomocou PATCH aktualizujte súpravu tak, aby ste pridali alebo nahradili jej plán. Úplný
objekt súpravy a koncové body nájdete v časti [Súpravy (brány
vydania)](/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` môže byť `hourly`, `daily` alebo `weekly`. Použite časové pásmo IANA.
Hodinové plány používajú `minute`; denné plány používajú `hour` a `minute`;
týždenné plány používajú aj `weekday`, pričom pondelok je `0` a nedeľa je `6`.
Odpoveď súpravy obsahuje `next_run_at` a `last_run_at`.

Časy sa riadia zmenami letného času vo vybranom časovom pásme. Plánované spustenia
sa zobrazia v histórii spustení súpravy a používajú jej aktuálneho agenta, scenáre,
kritériá a schválený referenčný stav. Každý vygenerovaný testovací hovor odošle
`test-call.completed`; webhook dokončenia na úrovni súpravy neexistuje. Plánované
hovory sa účtujú rovnakou sadzbou za simuláciu ako manuálne spustenia súpravy a pri
spustení súpravy zaznamenávajú `trigger: "schedule"`.

Ak chcete plán pozastaviť bez zmeny jeho časovania, pomocou PATCH odošlite úplný
existujúci objekt plánu s `"enabled": false`. Položka `frequency` je povinná;
vynechané časové pásmo a časové polia sa obnovia na predvolené hodnoty, preto
uveďte existujúce hodnoty. Ak chcete plán odstrániť, odošlite `"schedule": null`.

## Vzory

### Regresný korpus pre každý prompt

Udržiavajte súbor JSON s trojicami `{name, scenario_prompt, expected_outcome}`.
Pri každej zmene promptu spustite celú množinu ako dávku; porovnajte
prepisy a hodnotenia s predchádzajúcim spustením.

### Smoke test pre každé vydanie

Jedna dávka piatich scenárov úspešného priebehu, ktorú spustíte po každom
nasadení. Je citlivá na latenciu, preto ponechajte `stagger_seconds: 0`.

### Porovnávanie latencie

Spúšťajte identické scenáre v rôznych produktových úrovniach (`spark`,
`bolt`, `storm-base`). Porovnajte skóre `call.graded` a hodnotu
`duration_seconds` z každého výsledného denníka hovorov.

---

## Ďalšie kroky

<CardGroup cols={2}>
  <Card title="Referenčná dokumentácia testovacích hovorov" icon="flask" href="/api-reference/test-calls">
    Každý parameter dopytu, stavový kód a formát dávky.
  </Card>
  <Card title="Hodnotenie AI" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Automaticky vyhodnoťte každé testovacie spustenie a sledujte kvalitu v čase.
  </Card>
  <Card title="Hlásenia problémov" icon="triangle-exclamation" href="/api-reference/issue-reports">
    Označte konkrétne testy na manuálnu kontrolu.
  </Card>
  <Card title="Webhook test-call.completed" icon="bolt" href="/sk/webhooks/events">
    Odosielajte výsledky do služieb CI / Slack / PagerDuty.
  </Card>
</CardGroup>