Developer cookbook

Przetestuj agenta kompleksowo (API)

Uruchamiaj jednorazowe symulacje, równoległe partie scenariuszy i zestawy bramek wydania za pośrednictwem API ThunderPhone, aby regresje agenta były wykrywane, zanim usłyszą je klienci.

Iterowanie nad agentem AI oznacza iterowanie nad jego promptem, narzędziami oraz sposobem obsługi przypadków brzegowych. API symulacji wykonuje rzeczywiste połączenia z agentem przy użyciu dostarczonego promptu scenariusza. Wskazanie agenta tworzy uruchomienie bot-bot, a wskazanie numeru telefonu tworzy uruchomienie pętli zwrotnej SIP. Każde uruchomienie generuje rzeczywisty dziennik połączenia z transkrypcją, oceną i rozliczeniem, dzięki czemu dokładnie widać, jak działa agent i ile kosztuje.

Używaj go do:

• Testów smoke przed wdrożeniem po każdej edycji promptu
• Zestawów testów regresji podłączonych do CI (podłącz webhook test-call.completed → zakończ niepowodzeniem kompilację, jeśli wynik spadnie)
• Testowania obciążeniowego limitów współbieżności

Jednorazowo: pojedyncze uruchomienie#

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

Pola:

mode jest tylko do odczytu i wynika z target_type: agent generuje mode="bot", a phone_number generuje mode="sip".

Odpowiedź zawiera obiekt uruchomienia symulacji ze stanem status="queued". Odpytuj, aż status zmieni się na completed lub failed; po ustawieniu call_id pobierz transkrypcję przez GET /v1/calls/{call_id}/transcript.

Partie: scenariusze równoległe#

Uruchom równocześnie N scenariuszy — przydatne w zestawach testów regresji, które równolegle obejmują każdy znany przypadek brzegowy:

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

Odpowiedź zawiera listę run_ids identyfikatorów uruchomień podrzędnych. Pobierz stan partii:

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

run_count jest ograniczone do 20; stagger_seconds rozkłada tworzenie uruchomień w czasie, aby nie przeciążać agenta (0–60 s).

Podłącz do CI#

Utwórz zestaw bramki wydania na stronie Symulacje (/dashboard/simulations) — wybierz agenta, dodaj scenariusze ręcznie lub kliknij Generuj scenariusze za pomocą AI, aby utworzyć ich wersje robocze na podstawie promptu agenta (z opcjonalnym przebiegiem uwzględniającym przypadki brzegowe), a następnie pogrupuj je w zestaw. Zestaw przypisuje scenariusze i agenta, a także minimalny wskaźnik zaliczeń oraz opcjonalną regułę zerowej liczby błędów krytycznych. Zaliczone uruchomienia stają się zaakceptowaną linią bazową; późniejsze przejścia z zaliczenia do niezaliczenia są zwracane jako regresje.

Użyj klucza API organizacji w CI. Ten skrypt uruchamia zestaw, odpytuje go do czasu ukończenia oceny i porównania, a następnie kończy działanie z kodem niezerowym, jeśli wynik nie jest równy pass:

#!/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 zwraca 202 z identyfikatorem uruchomienia. GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id} zwraca status, verdict, pass_rate, critical_failure_count oraz bazową listę regressions. Oba endpointy wiążą organizację w adresie URL z organizacją klucza API.

Wzorce#

Zbiór regresji dla każdego promptu#

Utrzymuj plik JSON z krotkami {name, scenario_prompt, expected_outcome}. Przy każdej zmianie promptu uruchamiaj cały zestaw jako partię; porównuj transkrypcje i oceny z poprzednim uruchomieniem.

Test dymny dla każdego wydania#

Pojedyncza partia pięciu scenariuszy standardowej ścieżki, uruchamiana po każdym wdrożeniu. Są wrażliwe na opóźnienia, dlatego zachowaj stagger_seconds: 0.

Testy wydajności opóźnień#

Uruchamiaj identyczne scenariusze w różnych wersjach produktu (spark, bolt, storm-base). Porównuj wyniki call.graded oraz duration_seconds z każdego wynikowego dziennika połączenia.

Następne kroki#