Developer cookbook

Uji agen secara menyeluruh (API)

Jalankan simulasi sekali jalan, batch skenario paralel, dan rangkaian gerbang rilis melalui API ThunderPhone agar regresi agen terdeteksi sebelum pelanggan mengalaminya.

Melakukan iterasi pada agen AI berarti melakukan iterasi pada Prompt, alatnya, dan cara agen menangani kasus tepi. API simulasi menjalankan panggilan nyata terhadap agen menggunakan Prompt skenario yang Anda berikan. Menargetkan agen membuat eksekusi bot-ke-bot; menargetkan nomor telepon membuat eksekusi loopback SIP. Setiap eksekusi menghasilkan log panggilan nyata dengan transkrip, penilaian, dan penagihan, sehingga Anda dapat melihat secara tepat cara agen berperilaku dan biayanya.

Gunakan untuk:

• Pengujian smoke sebelum deployment setelah setiap pengeditan Prompt
• Rangkaian regresi yang terhubung ke CI (hubungkan webhook test-call.completed → gagalkan build jika skor turun)
• Pengujian stres batas konkurensi

Sekali jalan: satu eksekusi#

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

Kolom:

mode bersifat baca-saja dan diturunkan dari target_type: agent menghasilkan mode="bot", sedangkan phone_number menghasilkan mode="sip".

Responsnya adalah objek eksekusi simulasi dengan status="queued". Lakukan polling hingga status menjadi completed atau failed; setelah call_id ditetapkan, muat transkrip melalui GET /v1/calls/{call_id}/transcript.

Batch: skenario paralel#

Jalankan N skenario secara bersamaan — berguna untuk rangkaian regresi yang menjalankan setiap kasus tepi yang diketahui secara paralel:

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

Respons memuat daftar run_ids berisi ID eksekusi anak. Ambil status batch:

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

run_count dibatasi hingga 20; stagger_seconds memberi jeda pada peluncuran eksekusi agar tidak membebani agen secara berlebihan (0–60 dtk).

Hubungkan ke CI#

Buat rangkaian gerbang rilis di halaman Simulasi (/dashboard/simulations) — pilih agen, tambahkan skenario secara manual atau klik Buat skenario dengan AI untuk menyusunnya dari Prompt agen (dengan peninjauan kasus tepi opsional), lalu kelompokkan ke dalam rangkaian. Sebuah rangkaian mengunci skenario dan agennya, serta tingkat kelulusan minimum dan aturan opsional tanpa kegagalan kritis. Proses yang lulus menjadi baseline yang diterima; transisi lulus→gagal berikutnya dikembalikan sebagai regresi.

Gunakan kunci API organisasi di CI. Skrip ini memicu rangkaian, melakukan polling hingga penilaian dan perbandingan selesai, lalu keluar dengan nilai bukan nol kecuali putusannya adalah 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 mengembalikan 202 dengan ID proses. GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id} mengembalikan status, verdict, pass_rate, critical_failure_count, dan daftar baseline regressions. Kedua endpoint mengikat organisasi dalam URL ke organisasi kunci API.

Pola#

Korpus regresi per Prompt#

Pertahankan file JSON berisi tuple {name, scenario_prompt, expected_outcome}. Pada setiap perubahan Prompt, jalankan seluruh set sebagai batch; bandingkan transkrip dan nilai dengan proses sebelumnya.

Uji smoke per rilis#

Satu batch berisi lima skenario alur normal yang dijalankan setelah setiap deploy. Sensitif terhadap latensi, jadi pertahankan stagger_seconds: 0.

Benchmarking latensi#

Jalankan skenario yang identik terhadap tingkatan produk yang berbeda (spark, bolt, storm-base). Bandingkan skor call.graded dan duration_seconds dari setiap log panggilan yang dihasilkan.

Langkah berikutnya#