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

# Tester un agent de bout en bout (API)

> Exécutez des scénarios prédéfinis via votre agent avec l’API de test d’appels afin de détecter les régressions avant que vos clients ne les entendent.

<Note>
  Vous préférez le dashboard ? Cette même fonctionnalité est disponible dans **Simulations**
  (`/dashboard/simulations`), y compris la génération de scénarios par IA — consultez
  [Simuler un appel](/fr/guides/simulate-a-call). Cette page couvre l’approche
  programmatique.
</Note>

Itérer sur un agent IA implique d’itérer sur son prompt, ses outils
et sa façon de gérer les cas limites. L’**API test-calls** exécute de vrais
appels (bot à bot ou boucle SIP) sur un agent à l’aide d’un prompt de scénario
que vous fournissez — chaque exécution génère un véritable journal d’appel avec
transcription, évaluation et facturation, afin de voir précisément comment l’agent
se comporte et ce qu’il coûte.

Utilisez-la pour :

* Des tests de fumée avant le déploiement après chaque modification du prompt
* Des suites de régression intégrées à la CI (branchez le webhook `test-call.completed`
  → faites échouer le build si le score baisse)
* Tester les limites de concurrence sous contrainte

## Exécution unique : un seul test

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

Champs :

| Champ               | Type    | Obligatoire | Description                                                     |
| ------------------- | ------- | ----------- | --------------------------------------------------------------- |
| `target_type`       | string  | oui         | `agent` ou `phone_number`                                       |
| `target_id`         | integer | oui         | L’identifiant de l’agent (ou du numéro de téléphone)            |
| `direction`         | string  | oui         | `outbound` (le bot appelle) ou `inbound` (le bot répond)        |
| `scenario_prompt`   | string  | non         | Définit ce que dit le bot de test                               |
| `mode`              | string  | non         | `bot` (bot à bot, par défaut) ou `sip` (boucle SIP)             |
| `consent_to_charge` | boolean | **oui**     | Doit être `true`. Les appels de test coûtent 2× le tarif normal |
| `target_number`     | string  | non         | Remplacement de l’identifiant de l’appelant du bot (E.164)      |

La réponse est un [objet d’exécution d’appel de test](/api-reference/test-calls#test-call-run-object)
avec `status="queued"`. Interrogez-le jusqu’à ce que `status` devienne `completed` ou
`failed` ; une fois `call_id` défini, récupérez la transcription via
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript).

## Lots : scénarios en parallèle

Exécutez N scénarios simultanément — utile pour les suites de régression qui
couvrent chaque cas limite connu en parallèle :

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

La réponse contient une liste `run_ids` d’identifiants d’exécutions enfants. Récupérez le
statut du lot :

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

`run_count` est limité à 20 ; `stagger_seconds` espace les lancements
pour éviter de surcharger l’agent (0–60 s).

## L’intégrer à la CI

Créez une suite de contrôle de version sur la page **Simulations**
(`/dashboard/simulations`) — sélectionnez l’agent, ajoutez des scénarios manuellement ou
cliquez sur **Générer des scénarios avec l’IA** pour les rédiger à partir du
prompt de l’agent (avec un passage facultatif sur les cas limites), puis regroupez-les dans une suite.
Une suite fige ses scénarios et son agent, ainsi qu’un taux de réussite minimal et une
règle facultative exigeant zéro échec critique. Les exécutions réussies deviennent la référence
acceptée ; les transitions ultérieures de réussite à échec sont renvoyées comme régressions.

Utilisez une [clé API d’organisation](/api-reference/developer-api-keys) dans votre CI.
Ce script déclenche la suite, interroge son état jusqu’à ce que la notation et la comparaison soient
terminées, puis se termine avec un code différent de zéro sauf si le verdict est `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` renvoie `202` avec l’ID
d’exécution. `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` renvoie
`status`, `verdict`, `pass_rate`, `critical_failure_count` et la liste
de référence `regressions`. Les deux endpoints associent l’organisation de l’URL
à l’organisation de la clé API.

## Modèles

### Corpus de régression par prompt

Conservez un fichier JSON de tuples `{name, scenario_prompt, expected_outcome}`.
À chaque modification du prompt, exécutez l’ensemble complet par lot ; comparez les
transcriptions et les notes avec l’exécution précédente.

### Test smoke par version

Un seul lot de cinq scénarios de parcours nominal à exécuter après chaque
déploiement. Sensible à la latence, conservez donc `stagger_seconds: 0`.

### Benchmarking de la latence

Exécutez des scénarios identiques sur différents niveaux de produit (`spark`,
`bolt`, `storm-base`). Comparez les scores `call.graded` et
`duration_seconds` de chaque journal d’appel obtenu.

***

## Étapes suivantes

<CardGroup cols={2}>
  <Card title="Référence des appels de test" icon="flask" href="/api-reference/test-calls">
    Chaque paramètre de requête, code d’état et format de lot.
  </Card>

  <Card title="Notation par IA" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Notez automatiquement chaque exécution de test pour suivre la qualité dans le temps.
  </Card>

  <Card title="Rapports de problème" icon="triangle-exclamation" href="/api-reference/issue-reports">
    Signalez des tests spécifiques pour examen humain.
  </Card>

  <Card title="Webhook test-call.completed" icon="bolt" href="/fr/webhooks/events">
    Transmettez les résultats à votre CI / Slack / PagerDuty.
  </Card>
</CardGroup>