> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Chạy các kịch bản có sẵn qua tác nhân AI của bạn bằng API test-calls để phát hiện lỗi hồi quy trước khi khách hàng gặp phải.

<Note>
  Bạn thích dùng dashboard hơn? Khả năng tương tự có trong **Simulations**
  (`/dashboard/simulations`), bao gồm tạo kịch bản bằng AI — xem
  [Mô phỏng cuộc gọi](/vi/guides/simulate-a-call). Trang này trình bày
  cách thực hiện bằng lập trình.
</Note>

Lặp lại cải tiến một tác nhân AI đồng nghĩa với lặp lại cải tiến prompt, công cụ
và cách tác nhân xử lý các trường hợp biên. **API test-calls** thực hiện các
cuộc gọi thực (bot với bot hoặc vòng lặp SIP) đến một tác nhân bằng prompt kịch bản
do bạn cung cấp — mỗi lần chạy tạo ra nhật ký cuộc gọi thực kèm
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ử smoke 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ới CI (kết nối webhook `test-call.completed`
  → làm hỏng bản dựng nếu điểm số giảm)
* Kiểm tra áp lực giới hạn đồng thời

## Một lần chạy: một lượt duy nhất

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/test-calls \
  -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
  }'
```

Các trường:

| Trường              | Kiểu    | Bắt buộc | Mô tả                                                                |
| ------------------- | ------- | -------- | -------------------------------------------------------------------- |
| `target_type`       | string  | có       | `agent` hoặc `phone_number`                                          |
| `target_id`         | integer | có       | ID tác nhân (hoặc ID số điện thoại)                                  |
| `direction`         | string  | có       | `outbound` (bot gọi đi) hoặc `inbound` (bot trả lời)                 |
| `scenario_prompt`   | string  | không    | Xác định nội dung bot kiểm thử nói                                   |
| `mode`              | string  | không    | `bot` (bot với bot, mặc định) hoặc `sip` (vòng lặp SIP)              |
| `consent_to_charge` | boolean | **có**   | Phải là `true`. Cuộc gọi kiểm thử có giá gấp 2× mức giá thông thường |
| `target_number`     | string  | không    | Ghi đè ID người gọi của bot (E.164)                                  |

Phản hồi là một [đối tượng lượt chạy cuộc gọi kiểm thử](/api-reference/test-calls#test-call-run-object)
ở `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`](/api-reference/calls#get-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:

```bash theme={null}
curl -X POST https://api.thunderphone.com/v1/test-call-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 ID các lượt chạy con. Lấy
trạng thái lô:

```bash theme={null}
curl https://api.thunderphone.com/v1/test-call-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 tạo lượt chạy
để tránh gây quá tải cho tác nhân (0–60 giây).

## Tích hợp vào CI

Tạo một bộ kiểm thử chặn 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** để soạn thảo từ prompt của tác nhân AI
(với tùy chọn 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 không có lỗi nghiêm trọng tùy chọn. Các lần chạy đạt trở thành
đường cơ sở được chấp nhận; các chuyển đổi đạt→không đạt sau đó được trả về dưới dạng hồi quy.

Dùng [khóa API tổ chức](/api-reference/developer-api-keys) trong CI.
Script này kích hoạt bộ kiểm thử, thăm dò cho đến khi 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`:

```bash theme={null}
#!/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 với
ID 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

### Kho hồi quy theo từng 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 hợp dưới dạng một lô; so sánh
bản chép lời và điểm đánh giá với lần chạy trước.

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

Một lô duy nhất gồm năm kịch bản luồng 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`.

### Đánh giá độ trễ

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

***

## Bước tiếp theo

<CardGroup cols={2}>
  <Card title="Tài liệu tham khảo về cuộc gọi kiểm thử" icon="flask" href="/api-reference/test-calls">
    Mọi tham số truy vấn, mã trạng thái và cấu trúc lô.
  </Card>

  <Card title="Chấm điểm AI" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Tự động chấm điểm mọi lần chạy kiểm thử để theo dõi chất lượng theo thời gian.
  </Card>

  <Card title="Báo cáo sự cố" icon="triangle-exclamation" href="/api-reference/issue-reports">
    Đánh dấu các kiểm thử cụ thể để con người xem xét.
  </Card>

  <Card title="Webhook test-call.completed" icon="bolt" href="/vi/webhooks/events">
    Truyền kết quả vào CI / Slack / PagerDuty của bạn.
  </Card>
</CardGroup>