Developer cookbook

Test een agent end-to-end (API)

Voer one-shot-simulaties, parallelle scenariobatches en suites voor releasepoorten uit via de ThunderPhone API, zodat regressies in agents worden opgemerkt voordat klanten ze horen.

Itereren op een AI-agent betekent itereren op de prompt, de tools en de manier waarop deze uitzonderingssituaties afhandelt. De simulaties-API voert echte oproepen met een agent uit aan de hand van een scenarioprompt die je opgeeft. Een agent als doel instellen maakt een bot-naar-bot-uitvoering; een telefoonnummer als doel instellen maakt een SIP-loopback-uitvoering. Elke uitvoering levert een echt oproeplogboek op met transcriptie, beoordeling en facturering, zodat je precies ziet hoe de agent zich gedraagt en wat dit kost.

Gebruik dit voor:

• Smoketests vóór implementatie na elke promptwijziging
• Regressiesuites gekoppeld aan CI (koppel de test-call.completed-webhook → laat de build mislukken als de score daalt)
• Stresstests van limieten voor gelijktijdigheid

Eenmalig: enkele uitvoering#

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

Velden:

mode is alleen-lezen en wordt afgeleid van target_type: agent produceert mode="bot", terwijl phone_number mode="sip" produceert.

Het antwoord is een simulatie-uitvoeringsobject met status="queued". Poll totdat status verandert in completed of failed; zodra call_id is ingesteld, laad je de transcriptie via GET /v1/calls/{call_id}/transcript.

Batches: parallelle scenario's#

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

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

Het antwoord bevat een run_ids-lijst met id's van onderliggende uitvoeringen. Vraag de batchstatus op:

curl https://api.thunderphone.com/v1/simulations/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 overbelast raakt (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 op basis van de prompt van de agent (met een optionele controle op randgevallen), en groepeer ze in een suite. Een suite zet de scenario's en agent vast, plus een minimale slagingsgraad en een optionele regel voor nul kritieke fouten. Geslaagde runs worden de geaccepteerde basislijn; latere overgangen van geslaagd→mislukt worden teruggegeven als regressies.

Gebruik een organisatie-API-sleutel in CI. Dit script start de suite, controleert totdat de beoordeling en vergelijking zijn voltooid, en sluit af met een niet-nulstatus tenzij het oordeel pass is:

#!/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 basislijnlijst regressions. Beide endpoints koppelen de organisatie in de URL aan de organisatie van de API-sleutel.

Patronen#

Regressiecorpus per prompt#

Onderhoud een JSON-bestand met tuples van {name, scenario_prompt, expected_outcome}. Voer bij elke promptwijziging de volledige set als batch uit; vergelijk de transcripten 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.

Latentiebenchmarking#

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#