Developer cookbook

Testați un agent end-to-end (API)

Rulați simulări punctuale, loturi de scenarii în paralel și suite de validare a lansării prin API-ul ThunderPhone, astfel încât regresiile agentului să fie detectate înainte ca clienții să le audă.

Iterarea asupra unui agent IA înseamnă iterarea asupra promptului, instrumentelor sale și modului în care gestionează cazurile-limită. API-ul de simulări execută apeluri reale către un agent folosind un prompt de scenariu furnizat de dumneavoastră. Direcționarea către un agent creează o execuție bot-la-bot; direcționarea către un număr de telefon creează o execuție SIP loopback. Fiecare execuție produce un jurnal de apel real cu transcriere, evaluare și facturare, astfel încât vedeți exact cum se comportă agentul și cât costă.

Utilizați-l pentru:

• Teste smoke înainte de implementare, după fiecare modificare a promptului
• Suite de regresie conectate la CI (conectați webhookul test-call.completed → eșuați compilarea dacă scorul scade)
• Testarea la stres a limitelor de concurență

O singură execuție: rulare individuală#

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

Câmpuri:

mode este numai pentru citire și este derivat din target_type: agent produce mode="bot", iar phone_number produce mode="sip".

Răspunsul este un obiect de rulare a simulării cu status="queued". Interogați până când status devine completed sau failed; după ce este setat call_id, încărcați transcrierea prin GET /v1/calls/{call_id}/transcript.

Loturi: scenarii paralele#

Executați N scenarii simultan — util pentru suitele de regresie care acoperă în paralel fiecare caz-limită cunoscut:

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

Răspunsul conține o listă run_ids cu ID-urile rulărilor copil. Preluați starea lotului:

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

run_count este limitat la 20; stagger_seconds spațiază lansările pentru a evita suprasolicitarea agentului (0–60 s).

Integrați-l în CI#

Creați o suită de validare a lansării în pagina Simulări (/dashboard/simulations) — selectați agentul, adăugați scenarii manual sau faceți clic pe Generați scenarii cu AI pentru a le redacta pe baza promptului agentului (cu o etapă opțională pentru cazuri-limită) și grupați-le într-o suită. O suită fixează scenariile și agentul său, precum și o rată minimă de promovare și o regulă opțională fără eșecuri critice. Rulările reușite devin valoarea de referință acceptată; tranzițiile ulterioare de la promovare la eșec sunt returnate drept regresii.

Utilizați o cheie API de organizație în CI. Acest script declanșează suita, interoghează până când evaluarea și comparația sunt finalizate și se încheie cu un cod diferit de zero dacă verdictul nu este 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 returnează 202 cu ID-ul rulării. GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id} returnează status, verdict, pass_rate, critical_failure_count și lista de referință regressions. Ambele endpointuri asociază organizația din URL cu organizația cheii API.

Modele#

Corpus de regresie per prompt#

Mențineți un fișier JSON cu tupluri {name, scenario_prompt, expected_outcome}. La fiecare modificare a promptului, rulați întregul set ca lot; comparați transcrierile și evaluările cu rularea anterioară.

Test rapid per lansare#

Un singur lot de cinci scenarii de tip happy path, pe care îl rulați după fiecare implementare. Sensibil la latență, așadar păstrați stagger_seconds: 0.

Evaluarea comparativă a latenței#

Rulați scenarii identice pentru niveluri diferite de produs (spark, bolt, storm-base). Comparați scorurile call.graded și duration_seconds din fiecare jurnal de apel rezultat.

Pașii următori#