Developer cookbook

Bir yapay zeka ajanını uçtan uca test edin (API)

Ajan regresyonlarını müşteriler duymadan önce yakalamak için ThunderPhone API üzerinden tek seferlik simülasyonlar, paralel senaryo toplu çalıştırmaları ve sürüm kapısı test paketleri çalıştırın.

Bir yapay zeka ajanını iyileştirmek; istemini, araçlarını ve uç durumları ele alma biçimini yinelemeyi gerektirir. Simülasyonlar API'si, sağladığınız bir senaryo istemini kullanarak bir ajana karşı gerçek aramalar gerçekleştirir. Bir ajanı hedeflemek botlar arası bir çalışma oluşturur; bir telefon numarasını hedeflemek ise SIP geri döngü çalışması oluşturur. Her çalışma; transkript, puanlama ve faturalandırma içeren gerçek bir arama günlüğü üretir; böylece ajanın tam olarak nasıl davrandığını ve ne kadara mal olduğunu görebilirsiniz.

Şunlar için kullanın:

• Her istem düzenlemesinden sonra, yayına almadan önce hızlı testler
• CI'a bağlanan regresyon paketleri (test-call.completed webhook'unu bağlayın → puan düşerse derlemeyi başarısız yapın)
• Eşzamanlılık sınırlarını stres testine tabi tutma

Tek seferlik: tek çalışma#

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

Alanlar:

mode salt okunurdur ve target_type değerinden türetilir: agent, mode="bot" üretirken phone_number, mode="sip" üretir.

Yanıt, status="queued" durumunda bir simülasyon çalışma nesnesidir. status, completed veya failed olana kadar sorgulayın; call_id ayarlandığında transkripti GET /v1/calls/{call_id}/transcript aracılığıyla yükleyin.

Toplu işlemler: paralel senaryolar#

N senaryoyu eşzamanlı çalıştırın — bilinen her uç durumu paralel olarak kapsayan regresyon paketleri için kullanışlıdır:

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

Yanıt, alt çalışma kimliklerinden oluşan bir run_ids listesi içerir. Toplu işlem durumunu alın:

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

run_count en fazla 20 olabilir; stagger_seconds, ajanı aşırı yüklememek için başlatmaları aralıklı gerçekleştirir (0–60 sn).

CI sisteminize bağlayın#

Simülasyonlar sayfasında (/dashboard/simulations) bir yayına alma kontrol paketi oluşturun — ajanı seçin, senaryoları elle ekleyin veya ajanın isteminden taslak oluşturmaları için Yapay zeka ile senaryo oluştur seçeneğine tıklayın (isteğe bağlı bir uç durum kontrolüyle) ve bunları bir pakette gruplandırın. Bir paket, senaryolarını ve ajanını; ayrıca minimum başarı oranını ve isteğe bağlı sıfır kritik başarısızlık kuralını sabitler. Başarılı çalıştırmalar kabul edilen referans hâline gelir; daha sonraki başarılı→başarısız geçişleri gerileme olarak döndürülür.

CI sisteminizde bir kuruluş API anahtarı kullanın. Bu betik paketi tetikler, puanlama ve karşılaştırma tamamlanana kadar sorgular ve karar pass olmadığı sürece sıfır olmayan bir kodla çıkar:

#!/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, çalıştırma kimliğiyle birlikte 202 döndürür. GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}, status, verdict, pass_rate, critical_failure_count ve referans regressions listesini döndürür. Her iki uç nokta da URL'deki kuruluşu API anahtarının kuruluşuna bağlar.

Kalıplar#

İstem başına gerileme derlemi#

{name, scenario_prompt, expected_outcome} demetlerinden oluşan bir JSON dosyası tutun. Her istem değişikliğinde tüm kümeyi toplu olarak çalıştırın; transkriptleri ve puanlamaları önceki çalıştırmayla karşılaştırın.

Yayın başına hızlı test#

Her yayına alma sonrasında çalıştırdığınız, sorunsuz akıştan oluşan beş senaryoluk tek bir toplu işlem. Gecikmeye duyarlı olduğundan stagger_seconds: 0 olarak tutun.

Gecikme karşılaştırması#

Aynı senaryoları farklı ürün katmanlarında (spark, bolt, storm-base) çalıştırın. Her sonuç çağrı günlüğündeki call.graded puanlarını ve duration_seconds değerini karşılaştırın.

Sonraki adımlar#