Developer cookbook

Tester un agent de bout en bout (API)

Exécutez des simulations ponctuelles, des lots de scénarios parallèles et des suites de validation de version via l’API ThunderPhone afin de détecter les régressions des agents avant que les clients ne les entendent.

Itérer sur un agent IA implique d'itérer sur son prompt, ses outils et sa gestion des cas limites. L'API de simulations exécute de vrais appels vers un agent à l'aide d'un prompt de scénario que vous fournissez. Cibler un agent crée une exécution bot à bot ; cibler un numéro de téléphone crée une exécution en boucle SIP. Chaque exécution produit un journal d'appel réel avec transcription, évaluation et facturation, afin que vous puissiez voir exactement comment l'agent se comporte et ce qu'il coûte.

Utilisez-la pour :

• Des tests de bon fonctionnement avant le déploiement après chaque modification de prompt
• Des suites de régression intégrées à la CI (connectez le webhook test-call.completed → faites échouer le build si le score baisse)
• Tester les limites de concurrence sous contrainte

Exécution unique : un seul scénario#

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

Champs :

mode est en lecture seule et dérivé de target_type : agent produit mode="bot", tandis que phone_number produit mode="sip".

La réponse est un objet d'exécution de simulation avec status="queued". Interrogez-le jusqu'à ce que status devienne completed ou failed ; une fois call_id défini, chargez la transcription via GET /v1/calls/{call_id}/transcript.

Lots : scénarios parallèles#

Exécutez N scénarios simultanément — utile pour les suites de régression qui traitent tous les cas limites connus en parallèle :

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

La réponse contient une liste run_ids d'identifiants d'exécutions enfants. Récupérez le statut du lot :

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

run_count est limité à 20 ; stagger_seconds espace les lancements pour éviter de surcharger l'agent (0–60 s).

L’intégrer à CI#

Créez une suite de validation des releases sur la page Simulations (/dashboard/simulations) — sélectionnez l’agent, ajoutez des scénarios manuellement ou cliquez sur Générer des scénarios avec l’IA pour les rédiger à partir du prompt de l’agent (avec une passe facultative sur les cas limites), puis regroupez-les dans une suite. Une suite fige ses scénarios et son agent, ainsi qu’un taux de réussite minimal et une règle facultative d’absence d’échecs critiques. Les exécutions réussies deviennent la référence acceptée ; les transitions ultérieures de réussite à échec sont renvoyées comme régressions.

Utilisez une clé API d’organisation dans CI. Ce script déclenche la suite, interroge son état jusqu’à la fin de l’évaluation et de la comparaison, puis retourne un code différent de zéro sauf si le verdict est 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 renvoie 202 avec l’ID d’exécution. GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id} renvoie status, verdict, pass_rate, critical_failure_count et la liste de référence regressions. Les deux endpoints associent l’organisation dans l’URL à l’organisation de la clé API.

Modèles#

Corpus de régression par prompt#

Conservez un fichier JSON de tuples {name, scenario_prompt, expected_outcome}. À chaque modification du prompt, exécutez l’ensemble complet par lot ; comparez les transcriptions et les évaluations avec l’exécution précédente.

Test smoke par release#

Un seul lot de cinq scénarios sur le parcours nominal, exécuté après chaque déploiement. Sensible à la latence, conservez donc stagger_seconds: 0.

Analyse comparative de la latence#

Exécutez des scénarios identiques sur différents niveaux de produit (spark, bolt, storm-base). Comparez les scores call.graded et duration_seconds de chaque journal d’appel obtenu.

Étapes suivantes#