Developer cookbook

Einen Agenten Ende-zu-Ende testen (API)

Führen Sie Einzelsimulationen, parallele Szenariobatches und Release-Gate-Suites über die ThunderPhone API aus, damit Regressionen bei Agenten erkannt werden, bevor Kunden sie hören.

Die Weiterentwicklung eines KI-Agenten bedeutet, seinen Prompt, seine Tools und seine Behandlung von Sonderfällen weiterzuentwickeln. Die Simulations-API führt mithilfe eines von Ihnen bereitgestellten Szenario-Prompts echte Anrufe mit einem Agenten durch. Die Ausrichtung auf einen Agenten erstellt einen Bot-zu-Bot-Durchlauf; die Ausrichtung auf eine Telefonnummer erstellt einen SIP-Loopback-Durchlauf. Jeder Durchlauf erzeugt ein echtes Anrufprotokoll mit Transkript, Bewertung und Abrechnung, sodass Sie genau sehen, wie sich der Agent verhält und was er kostet.

Verwenden Sie sie für:

• Smoke-Tests vor dem Deployment nach jeder Prompt-Änderung
• In CI eingebundene Regressionstest-Suites (Webhook test-call.completed einbinden → Build fehlschlagen lassen, wenn der Score sinkt)
• Belastungstests von Parallelitätslimits

Einmalig: einzelner Durchlauf#

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

Felder:

mode ist schreibgeschützt und wird aus target_type abgeleitet: agent erzeugt mode="bot", während phone_number mode="sip" erzeugt.

Die Antwort ist ein Simulationsdurchlaufobjekt mit status="queued". Fragen Sie ab, bis status zu completed oder failed wird; sobald call_id gesetzt ist, laden Sie das Transkript über GET /v1/calls/{call_id}/transcript.

Batches: parallele Szenarien#

Führen Sie N Szenarien gleichzeitig aus — nützlich für Regressionstest-Suites, die jeden bekannten Sonderfall parallel abdecken:

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

Die Antwort enthält eine run_ids-Liste mit IDs untergeordneter Durchläufe. Rufen Sie den Batch-Status ab:

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

run_count ist auf 20 begrenzt; stagger_seconds verteilt die Starts, um den Agenten nicht zu überlasten (0–60 s).

In CI einbinden#

Erstellen Sie auf der Seite Simulationen (/dashboard/simulations) eine Release-Gate-Suite — wählen Sie den Agenten aus, fügen Sie Szenarien manuell hinzu oder klicken Sie auf Szenarien mit KI generieren, um sie aus dem Prompt des Agenten zu entwerfen (optional mit einem Durchlauf für Grenzfälle), und gruppieren Sie sie in einer Suite. Eine Suite fixiert ihre Szenarien und ihren Agenten sowie eine Mindestbestehensquote und eine optionale Regel für null kritische Fehler. Bestandene Läufe werden zur akzeptierten Basislinie; spätere Übergänge von bestanden zu nicht bestanden werden als Regressionen zurückgegeben.

Verwenden Sie einen Organisations-API-Schlüssel in CI. Dieses Skript startet die Suite, fragt ab, bis Bewertung und Vergleich abgeschlossen sind, und wird mit einem Fehlercode beendet, sofern das Urteil nicht pass lautet:

#!/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 gibt 202 mit der Lauf-ID zurück. GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id} gibt status, verdict, pass_rate, critical_failure_count und die Basislinienliste regressions zurück. Beide Endpunkte binden die Organisation in der URL an die Organisation des API-Schlüssels.

Muster#

Regressionskorpus pro Prompt#

Pflegen Sie eine JSON-Datei mit Tupeln aus {name, scenario_prompt, expected_outcome}. Führen Sie bei jeder Prompt-Änderung die gesamte Menge als Batch aus; vergleichen Sie die Transkripte und Bewertungen mit dem vorherigen Lauf.

Smoke-Test pro Release#

Ein einzelner Batch mit fünf Happy-Path-Szenarien, den Sie nach jedem Deployment ausführen. Latenzempfindlich, daher stagger_seconds: 0 beibehalten.

Latenz-Benchmarking#

Führen Sie identische Szenarien für verschiedene Produkttarife aus (spark, bolt, storm-base). Vergleichen Sie die call.graded-Bewertungen und die duration_seconds aus jedem resultierenden Anrufprotokoll.

Nächste Schritte#