> ## 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.

# Testaa agentti alusta loppuun (API)

> Aja valmiita skenaarioita agentillasi test-calls-rajapinnan avulla, jotta regressiot havaitaan ennen kuin asiakkaat kuulevat ne.

<Note>
  Käytätkö mieluummin hallintapaneelia? Sama toiminto löytyy kohdasta **Simulaatiot**
  (`/dashboard/simulations`), mukaan lukien tekoälyn skenaarioiden luonti — katso
  [Simuloi puhelu](/fi/guides/simulate-a-call). Tämä sivu käsittelee
  ohjelmallista tapaa.
</Note>

Tekoälyagentin iterointi tarkoittaa sen kehotteen, työkalujen ja
reunatapausten käsittelytavan iterointia. **test-calls API** suorittaa oikeita
(botti-botille- tai SIP-takaisinkytkentä-) puheluita agenttia vastaan antamasi
skenaariokehotteen avulla — jokainen suoritus tuottaa oikean puhelulokin,
jossa on transkriptio, arviointi ja laskutus, joten näet tarkalleen, miten
agentti toimii ja mitä se maksaa.

Käytä sitä seuraaviin:

* Julkaisua edeltäviin smoke-testeihin jokaisen kehoteen muokkauksen jälkeen
* CI:hin kytkettyihin regressiotestisarjoihin (liitä `test-call.completed`-webhook
  → epäonnistuta koonti, jos pisteet laskevat)
* Samanaikaisuusrajojen kuormitustestaukseen

## Kertaluonteinen: yksi suoritus

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

Kentät:

| Kenttä              | Tyyppi       | Pakollinen | Kuvaus                                                         |
| ------------------- | ------------ | ---------- | -------------------------------------------------------------- |
| `target_type`       | merkkijono   | kyllä      | `agent` tai `phone_number`                                     |
| `target_id`         | kokonaisluku | kyllä      | Agentin tunnus (tai puhelinnumeron tunnus)                     |
| `direction`         | merkkijono   | kyllä      | `outbound` (botti soittaa) tai `inbound` (botti vastaa)        |
| `scenario_prompt`   | merkkijono   | ei         | Ohjaa, mitä testibotti sanoo                                   |
| `mode`              | merkkijono   | ei         | `bot` (botti-botille, oletus) tai `sip` (SIP-takaisinkytkentä) |
| `consent_to_charge` | totuusarvo   | **kyllä**  | On oltava `true`. Testipuhelut maksavat 2× normaalin hinnan    |
| `target_number`     | merkkijono   | ei         | Ohita botin soittajan tunnus (E.164)                           |

Vastaus on [testipuhelusuoritusobjekti](/api-reference/test-calls#test-call-run-object)
tilassa `status="queued"`. Kysy tilaa, kunnes `status` muuttuu arvoksi `completed` tai
`failed`; kun `call_id` on asetettu, lataa transkriptio osoitteesta
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript).

## Erät: rinnakkaiset skenaariot

Suorita N skenaariota samanaikaisesti — hyödyllistä regressiotestisarjoille,
jotka testaavat kaikki tunnetut reunatapaukset rinnakkain:

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

Vastaus sisältää alisuoritusten tunnusten `run_ids`-luettelon. Hae erän
tila:

```bash theme={null}
curl https://api.thunderphone.com/v1/test-call-batches/{batch_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

`run_count` on rajoitettu arvoon 20; `stagger_seconds` porrastaa suoritusten
käynnistämistä, jotta agenttia ei kuormiteta liikaa (0–60 s).

## Ota käyttöön CI:ssä

Luo julkaisun hyväksyntätestisarja **Simulaatiot**-sivulla
(`/dashboard/simulations`) — valitse agentti, lisää skenaarioita käsin tai
luo niitä agentin kehotteen pohjalta napsauttamalla **Luo skenaarioita tekoälyn avulla**
(valinnaisella reunatapaustarkistuksella) ja ryhmittele ne testisarjaksi.
Testisarja lukitsee skenaariot ja agentin sekä vähimmäisläpäisyasteen ja
valinnaisen säännön, jonka mukaan kriittisiä epäonnistumisia ei saa olla. Hyväksytysti läpäisseistä ajoista tulee hyväksytty vertailutaso; myöhemmät läpäisystä epäonnistumiseen -siirtymät palautetaan regressioina.

Käytä CI:ssä [organisaation API-avainta](/api-reference/developer-api-keys).
Tämä komentosarja käynnistää testisarjan, kyselee tilaa, kunnes arviointi ja vertailu ovat
valmiit, ja palauttaa muun kuin nolla-arvon, ellei päätös ole `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` palauttaa `202`-vastauksen, jossa on
ajon tunnus. `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` palauttaa
kentät `status`, `verdict`, `pass_rate`, `critical_failure_count` ja
vertailutason `regressions`-luettelon. Molemmat päätepisteet sitovat URL-osoitteen organisaation
API-avaimen organisaatioon.

## Mallit

### Kehotekohtainen regressiokorpus

Ylläpidä JSON-tiedostoa, joka sisältää `{name, scenario_prompt, expected_outcome}`
-monikoita. Suorita jokaisen kehotemuutoksen yhteydessä koko joukko eränä; vertaa
transkriptit ja arvosanat edelliseen ajoon.

### Julkaisukohtainen smoke-testi

Yksi erä, jossa on viisi onnistuneen peruspolun skenaariota ja jonka ajat jokaisen
julkaisun jälkeen. Viiveherkkä, joten pidä `stagger_seconds: 0`.

### Viiveen vertailumittaus

Aja samat skenaariot eri tuotetasoja vasten (`spark`,
`bolt`, `storm-base`). Vertaa `call.graded`-pisteitä ja
`duration_seconds`-arvoa jokaisesta tuloksena syntyvästä puhelulokista.

***

## Seuraavat vaiheet

<CardGroup cols={2}>
  <Card title="Testipuheluiden viite" icon="flask" href="/api-reference/test-calls">
    Kaikki kyselyparametrit, tilakoodit ja erien muodot.
  </Card>

  <Card title="Tekoälyarviointi" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Pisteytä jokainen testiajo automaattisesti, jotta voit seurata laatua ajan mittaan.
  </Card>

  <Card title="Ongelmaraportit" icon="triangle-exclamation" href="/api-reference/issue-reports">
    Merkitse tietyt testit ihmisen tarkistettaviksi.
  </Card>

  <Card title="test-call.completed-webhook" icon="bolt" href="/fi/webhooks/events">
    Siirrä tulokset CI:hin / Slackiin / PagerDutyyn.
  </Card>
</CardGroup>