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

# Test een agent end-to-end (API)

> Voer vooraf gedefinieerde scenario's uit via je agent met de test-calls-API, zodat regressies worden opgemerkt voordat klanten ze horen.

<Note>
  Geef je de voorkeur aan het dashboard? Dezelfde functionaliteit vind je in **Simulations**
  (`/dashboard/simulations`), inclusief het genereren van AI-scenario's — zie
  [Een oproep simuleren](/nl/guides/simulate-a-call). Deze pagina behandelt de
  programmatische route.
</Note>

Itereren op een AI-agent betekent itereren op de prompt, de tools
en de manier waarop deze randgevallen afhandelt. De **test-calls API** voert echte
(bot-naar-bot- of SIP-loopback-)oproepen uit naar een agent met een scenario-
prompt die je opgeeft — elke uitvoering produceert een echt oproeplogboek met
transcript, beoordeling en facturering, zodat je precies ziet hoe de agent
zich gedraagt en wat dit kost.

Gebruik deze voor:

* Smooktests vóór implementatie na elke promptwijziging
* Regressiesuites gekoppeld aan CI (koppel de webhook `test-call.completed`
  → laat de build mislukken als de score daalt)
* Het stresstesten van gelijktijdigheidslimieten

## Eenmalig: één uitvoering

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

Velden:

| Veld                | Type    | Vereist | Beschrijving                                                |
| ------------------- | ------- | ------- | ----------------------------------------------------------- |
| `target_type`       | string  | ja      | `agent` of `phone_number`                                   |
| `target_id`         | integer | ja      | De agent-id (of telefoonnummer-id)                          |
| `direction`         | string  | ja      | `outbound` (bot plaatst) of `inbound` (bot beantwoordt)     |
| `scenario_prompt`   | string  | nee     | Bepaalt wat de testbot zegt                                 |
| `mode`              | string  | nee     | `bot` (bot-naar-bot, standaard) of `sip` (SIP-loopback)     |
| `consent_to_charge` | boolean | **ja**  | Moet `true` zijn. Testoproepen kosten 2× het normale tarief |
| `target_number`     | string  | nee     | Overschrijving voor de beller-id van de bot (E.164)         |

Het antwoord is een [testoproep-uitvoeringsobject](/api-reference/test-calls#test-call-run-object)
met `status="queued"`. Poll totdat `status` `completed` of
`failed` wordt; zodra `call_id` is ingesteld, laad je het transcript via
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript).

## Batches: parallelle scenario's

Voer N scenario's gelijktijdig uit — handig voor regressiesuites die
elk bekend randgeval parallel testen:

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

Het antwoord bevat een `run_ids`-lijst met id's van onderliggende uitvoeringen. Haal de batch-
status op:

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

`run_count` is beperkt tot 20; `stagger_seconds` spreidt het starten
om te voorkomen dat de agent wordt overbelast (0–60 s).

## Koppel het aan CI

Maak een releasegatesuite op de pagina **Simulaties**
(`/dashboard/simulations`) — kies de agent, voeg scenario's handmatig toe of
klik op **Scenario's genereren met AI** om ze op te stellen vanuit de
prompt van de agent (met een optionele controle op randgevallen), en groepeer ze
in een suite. Een suite legt de scenario's en agent vast, plus een minimale
slagingsratio en een optionele regel voor nul kritieke fouten. Geslaagde runs worden
de geaccepteerde referentie; latere overgangen van geslaagd→mislukt worden als regressies
geretourneerd.

Gebruik een [organisatie-API-sleutel](/api-reference/developer-api-keys) in CI.
Dit script start de suite, pollt totdat beoordeling en vergelijking zijn
voltooid, en sluit af met een niet-nulstatus tenzij het oordeel `pass` is:

```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` retourneert `202` met de
run-ID. `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` retourneert
`status`, `verdict`, `pass_rate`, `critical_failure_count` en de
referentielijst `regressions`. Beide endpoints koppelen de organisatie in de URL
aan de organisatie van de API-sleutel.

## Patronen

### Regressiecorpus per prompt

Beheer een JSON-bestand met tuples van `{name, scenario_prompt, expected_outcome}`.
Voer bij elke promptwijziging de volledige set als batch uit; vergelijk de
transcripties en beoordelingen met de vorige run.

### Smoketest per release

Een enkele batch van vijf scenario's voor het ideale pad die je na elke
implementatie uitvoert. Gevoelig voor latentie, dus houd `stagger_seconds: 0`.

### Latentieb benchmarking

Voer identieke scenario's uit voor verschillende productpakketten (`spark`,
`bolt`, `storm-base`). Vergelijk de scores van `call.graded` en de
`duration_seconds` uit elk resulterend oproeplogboek.

***

## Volgende stappen

<CardGroup cols={2}>
  <Card title="Referentie voor testoproepen" icon="flask" href="/api-reference/test-calls">
    Elke queryparameter, statuscode en batchstructuur.
  </Card>

  <Card title="AI-beoordeling" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Beoordeel elke testrun automatisch om de kwaliteit in de loop van de tijd te volgen.
  </Card>

  <Card title="Probleemmeldingen" icon="triangle-exclamation" href="/api-reference/issue-reports">
    Markeer specifieke tests voor menselijke beoordeling.
  </Card>

  <Card title="test-call.completed-webhook" icon="bolt" href="/nl/webhooks/events">
    Stuur resultaten door naar je CI / Slack / PagerDuty.
  </Card>
</CardGroup>