> ## 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.

# Testați un agent de la un capăt la altul (API)

> Rulați scenarii predefinite prin agentul dumneavoastră cu API-ul pentru apeluri de test, astfel încât regresiile să fie detectate înainte ca clienții să le audă.

<Note>
  Preferați tabloul de bord? Aceeași funcționalitate este disponibilă în **Simulări**
  (`/dashboard/simulations`), inclusiv generarea de scenarii cu AI — consultați
  [Simulați un apel](/ro/guides/simulate-a-call). Această pagină acoperă
  metoda programatică.
</Note>

Iterarea asupra unui agent AI înseamnă iterarea asupra promptului său, a instrumentelor sale
și a modului în care gestionează cazurile-limită. **API-ul pentru apeluri de test** efectuează apeluri reale
(bot-la-bot sau cu buclă SIP) către un agent folosind un prompt de scenariu
furnizat de dumneavoastră — fiecare execuție produce un jurnal de apel real cu
transcriere, evaluare și facturare, astfel încât să vedeți exact cum se comportă agentul
și cât costă.

Utilizați-l pentru:

* Teste smoke înainte de implementare, după fiecare modificare a promptului
* Suite de regresie integrate în CI (conectați webhookul `test-call.completed`
  → eșuați buildul dacă scorul scade)
* Testarea la stres a limitelor de simultaneitate

## O singură execuție

```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âmpuri:

| Câmp                | Tip     | Obligatoriu | Descriere                                                           |
| ------------------- | ------- | ----------- | ------------------------------------------------------------------- |
| `target_type`       | șir     | da          | `agent` sau `phone_number`                                          |
| `target_id`         | întreg  | da          | ID-ul agentului (sau ID-ul numărului de telefon)                    |
| `direction`         | șir     | da          | `outbound` (botul inițiază) sau `inbound` (botul răspunde)          |
| `scenario_prompt`   | șir     | nu          | Determină ce spune botul de test                                    |
| `mode`              | șir     | nu          | `bot` (bot-la-bot, implicit) sau `sip` (buclă SIP)                  |
| `consent_to_charge` | boolean | **da**      | Trebuie să fie `true`. Apelurile de test costă de 2× tariful normal |
| `target_number`     | șir     | nu          | Suprascriere pentru ID-ul apelantului botului (E.164)               |

Răspunsul este un [obiect de execuție a unui apel de test](/api-reference/test-calls#test-call-run-object)
cu `status="queued"`. Interogați periodic până când `status` devine `completed` sau
`failed`; după setarea lui `call_id`, încărcați transcrierea prin
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript).

## Loturi: scenarii paralele

Rulați N scenarii simultan — util pentru suite de regresie care
acoperă în paralel fiecare caz-limită cunoscut:

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

Răspunsul conține o listă `run_ids` cu ID-urile execuțiilor copil. Preluați starea
lotului:

```bash theme={null}
curl https://api.thunderphone.com/v1/test-call-batches/{batch_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"
```

`run_count` este limitat la 20; `stagger_seconds` distanțează lansările
pentru a evita suprasolicitarea agentului (0–60 s).

## Integrați-l în CI

Creați o suită de validare a lansării în pagina **Simulări**
(`/dashboard/simulations`) — alegeți agentul, adăugați scenarii manual sau
faceți clic pe **Generați scenarii cu AI** pentru a le redacta din
promptul agentului (cu o parcurgere opțională pentru cazuri-limită) și
grupați-le într-o suită. O suită fixează scenariile și agentul, precum și
o rată minimă de reușită și o regulă opțională de zero eșecuri critice.
Rulările reușite devin baza de referință acceptată; tranzițiile ulterioare
de la reușită la eșec sunt returnate ca regresii.

Utilizați o [cheie API de organizație](/api-reference/developer-api-keys) în CI.
Acest script declanșează suita, interoghează până când evaluarea și comparația
sunt finalizate și se încheie cu un cod diferit de zero dacă verdictul nu este `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` returnează `202` cu ID-ul
rulării. `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` returnează
`status`, `verdict`, `pass_rate`, `critical_failure_count` și lista de
referință `regressions`. Ambele endpointuri leagă organizația din URL
de organizația cheii API.

## Modele

### Corpus de regresie per prompt

Mențineți un fișier JSON cu tupluri `{name, scenario_prompt, expected_outcome}`.
La fiecare modificare a promptului, rulați întregul set ca lot; comparați
transcrierile și evaluările cu rularea anterioară.

### Test smoke per lansare

Un singur lot de cinci scenarii pe parcursul fericit, pe care îl rulați după
fiecare implementare. Sensibil la latență, deci păstrați `stagger_seconds: 0`.

### Evaluarea comparativă a latenței

Rulați scenarii identice pentru diferite niveluri de produs (`spark`,
`bolt`, `storm-base`). Comparați scorurile `call.graded` și
`duration_seconds` din fiecare jurnal de apel rezultat.

***

## Pașii următori

<CardGroup cols={2}>
  <Card title="Referință pentru apeluri de test" icon="flask" href="/api-reference/test-calls">
    Fiecare parametru de interogare, cod de stare și structură de lot.
  </Card>

  <Card title="Evaluare cu AI" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Evaluați automat fiecare rulare de test pentru a urmări calitatea în timp.
  </Card>

  <Card title="Rapoarte de probleme" icon="triangle-exclamation" href="/api-reference/issue-reports">
    Marcați teste specifice pentru revizuire umană.
  </Card>

  <Card title="Webhook test-call.completed" icon="bolt" href="/ro/webhooks/events">
    Transmiteți rezultatele către CI / Slack / PagerDuty.
  </Card>
</CardGroup>