Developer cookbook

Kiểm thử tác nhân AI từ đầu đến cuối (API)

Chạy mô phỏng một lần, lô kịch bản song song và bộ kiểm thử chặn phát hành qua API ThunderPhone để phát hiện lỗi hồi quy của tác nhân AI trước khi khách hàng nghe thấy chúng.

Lặp lại tác nhân AI nghĩa là lặp lại prompt, công cụ của tác nhân, và cách tác nhân xử lý các trường hợp biên. API mô phỏng thực hiện các cuộc gọi thực đến một tác nhân bằng prompt kịch bản do bạn cung cấp. Nhắm đến một tác nhân sẽ tạo lượt chạy bot-với-bot; nhắm đến một số điện thoại sẽ tạo lượt chạy vòng lặp SIP. Mỗi lượt chạy tạo nhật ký cuộc gọi thực với bản chép lời, chấm điểm và tính phí, để bạn thấy chính xác tác nhân hoạt động như thế nào và chi phí là bao nhiêu.

Dùng API này để:

• Kiểm thử nhanh trước khi triển khai sau mỗi lần chỉnh sửa prompt
• Bộ kiểm thử hồi quy tích hợp vào CI (kết nối webhook test-call.completed → làm bản dựng thất bại nếu điểm số giảm)
• Kiểm thử tải giới hạn đồng thời

Một lần chạy: lượt chạy đơn#

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

Trường:

mode chỉ đọc và được suy ra từ target_type: agent tạo mode="bot", trong khi phone_number tạo mode="sip".

Phản hồi là một đối tượng lượt chạy mô phỏng ở status="queued". Thăm dò cho đến khi status trở thành completed hoặc failed; sau khi call_id được đặt, tải bản chép lời qua GET /v1/calls/{call_id}/transcript.

Lô: kịch bản song song#

Chạy đồng thời N kịch bản — hữu ích cho các bộ kiểm thử hồi quy kiểm tra song song mọi trường hợp biên đã biết:

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

Phản hồi chứa danh sách run_ids gồm các mã lượt chạy con. Lấy trạng thái lô:

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

run_count được giới hạn ở 20; stagger_seconds giãn khoảng thời gian khởi chạy để tránh gây tải quá mức cho tác nhân (0–60 giây).

Tích hợp vào CI#

Tạo bộ kiểm thử cổng phát hành trên trang Mô phỏng (/dashboard/simulations) — chọn tác nhân AI, thêm kịch bản thủ công hoặc nhấp Tạo kịch bản bằng AI để phác thảo chúng từ prompt của tác nhân AI (có thể bổ sung bước kiểm tra trường hợp biên), rồi nhóm chúng thành một bộ kiểm thử. Một bộ kiểm thử cố định các kịch bản và tác nhân AI của nó, cùng tỷ lệ đạt tối thiểu và quy tắc tùy chọn không có lỗi nghiêm trọng. Các lần chạy đạt sẽ trở thành đường cơ sở được chấp nhận; các chuyển đổi đạt→không đạt về sau được trả về dưới dạng hồi quy.

Sử dụng khóa API tổ chức trong CI. Script này kích hoạt bộ kiểm thử, thăm dò cho đến khi việc chấm điểm và so sánh hoàn tất, rồi thoát với mã khác 0 trừ khi kết luận là 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 trả về 202 cùng mã lần chạy. GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id} trả về status, verdict, pass_rate, critical_failure_count và danh sách regressions của đường cơ sở. Cả hai endpoint đều liên kết tổ chức trong URL với tổ chức của khóa API.

Mẫu#

Tập dữ liệu hồi quy theo prompt#

Duy trì một tệp JSON gồm các bộ {name, scenario_prompt, expected_outcome}. Mỗi khi prompt thay đổi, chạy toàn bộ tập dưới dạng một lô; so sánh bản chép lời và điểm số với lần chạy trước đó.

Kiểm thử nhanh theo từng bản phát hành#

Một lô gồm năm kịch bản đường dẫn thành công mà bạn chạy sau mỗi lần triển khai. Nhạy cảm với độ trễ, vì vậy hãy giữ stagger_seconds: 0.

Đo điểm chuẩn độ trễ#

Chạy các kịch bản giống hệt nhau trên các cấp sản phẩm khác nhau (spark, bolt, storm-base). So sánh điểm call.graded và duration_seconds từ từng nhật ký cuộc gọi tạo ra.

Bước tiếp theo#