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

# Einen Agenten Ende-zu-Ende testen (API)

> Führen Sie vordefinierte Szenarien mit der Test-Calls-API durch Ihren Agenten aus, damit Regressionen erkannt werden, bevor Kunden sie bemerken.

<Note>
  Bevorzugen Sie das Dashboard? Dieselbe Funktion finden Sie unter **Simulationen**
  (`/dashboard/simulations`), einschließlich KI-Szenariogenerierung — siehe
  [Einen Anruf simulieren](/de/guides/simulate-a-call). Diese Seite beschreibt den
  programmgesteuerten Weg.
</Note>

Die Iteration eines KI-Agenten bedeutet, seinen Prompt, seine Tools
und den Umgang mit Sonderfällen zu iterieren. Die **Testanrufe-API** führt echte
(Bot-zu-Bot- oder SIP-Loopback-)Anrufe mit einem Agenten aus, basierend auf einem von Ihnen bereitgestellten
Szenario-Prompt — jeder Durchlauf erzeugt ein echtes Anrufprotokoll mit
Transkript, Bewertung und Abrechnung, sodass Sie genau sehen, wie sich der Agent
verhält und was er kostet.

Verwenden Sie sie für:

* Smoke-Tests vor dem Deployment nach jeder Prompt-Änderung
* In CI eingebundene Regressionstests (Webhook `test-call.completed`
  einbinden → Build fehlschlagen lassen, wenn die Bewertung sinkt)
* Belastungstests von Parallelitätslimits

## Einmalig: einzelner Durchlauf

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

Felder:

| Feld                | Typ     | Erforderlich | Beschreibung                                                        |
| ------------------- | ------- | ------------ | ------------------------------------------------------------------- |
| `target_type`       | String  | ja           | `agent` oder `phone_number`                                         |
| `target_id`         | Integer | ja           | Die Agent-ID (oder Telefonnummer-ID)                                |
| `direction`         | String  | ja           | `outbound` (Bot ruft an) oder `inbound` (Bot nimmt an)              |
| `scenario_prompt`   | String  | nein         | Legt fest, was der Test-Bot sagt                                    |
| `mode`              | String  | nein         | `bot` (Bot-zu-Bot, Standard) oder `sip` (SIP-Loopback)              |
| `consent_to_charge` | Boolean | **ja**       | Muss `true` sein. Testanrufe kosten das 2-Fache des normalen Tarifs |
| `target_number`     | String  | nein         | Überschreibung für die Anrufer-ID des Bots (E.164)                  |

Die Antwort ist ein [Testanruf-Durchlaufobjekt](/api-reference/test-calls#test-call-run-object)
mit `status="queued"`. Fragen Sie ab, bis `status` zu `completed` oder
`failed` wird; sobald `call_id` gesetzt ist, laden Sie das Transkript über
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript).

## Stapel: parallele Szenarien

Führen Sie N Szenarien gleichzeitig aus — nützlich für Regressionstest-Suites,
die jeden bekannten Sonderfall parallel prüfen:

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

Die Antwort enthält eine `run_ids`-Liste mit IDs untergeordneter Durchläufe. Rufen Sie den
Stapelstatus ab:

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

`run_count` ist auf 20 begrenzt; `stagger_seconds` verteilt die Starts,
um den Agenten nicht zu überlasten (0–60 s).

## In CI einbinden

Erstellen Sie auf der Seite **Simulationen**
(`/dashboard/simulations`) eine Release-Gate-Suite — wählen Sie den Agenten aus, fügen Sie Szenarien manuell hinzu oder
klicken Sie auf **Szenarien mit KI generieren**, um sie anhand des
Prompts des Agenten zu entwerfen (mit optionaler Prüfung auf Grenzfälle), und gruppieren Sie sie in einer Suite.
Eine Suite fixiert ihre Szenarien und den Agenten sowie eine Mindestbestehensquote und eine
optionale Regel ohne kritische Fehler. Erfolgreiche Durchläufe werden zur akzeptierten
Baseline; spätere Übergänge von bestanden zu fehlgeschlagen werden als Regressionen zurückgegeben.

Verwenden Sie einen [Organisations-API-Schlüssel](/api-reference/developer-api-keys) in CI.
Dieses Skript startet die Suite, fragt ab, bis Bewertung und Vergleich
abgeschlossen sind, und beendet sich mit einem von null verschiedenen Status, sofern das Urteil nicht `pass` lautet:

```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` gibt `202` mit der
Durchlauf-ID zurück. `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` gibt
`status`, `verdict`, `pass_rate`, `critical_failure_count` und die
Baseline-Liste `regressions` zurück. Beide Endpunkte ordnen die Organisation in der URL
der Organisation des API-Schlüssels zu.

## Muster

### Regressionskorpus pro Prompt

Pflegen Sie eine JSON-Datei mit Tupeln aus `{name, scenario_prompt, expected_outcome}`.
Führen Sie bei jeder Prompt-Änderung die vollständige Menge als Batch aus; vergleichen Sie die
Transkripte und Bewertungen mit dem vorherigen Durchlauf.

### Smoke-Test pro Release

Ein einzelner Batch mit fünf Happy-Path-Szenarien, den Sie nach jedem
Deployment ausführen. Latenzempfindlich, daher sollte `stagger_seconds: 0` beibehalten werden.

### Latenz-Benchmarking

Führen Sie identische Szenarien für verschiedene Produkttarife (`spark`,
`bolt`, `storm-base`) aus. Vergleichen Sie die Bewertungen `call.graded` und die
`duration_seconds` aus jedem resultierenden Anrufprotokoll.

***

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Referenz für Testanrufe" icon="flask" href="/api-reference/test-calls">
    Alle Abfrageparameter, Statuscodes und Batch-Strukturen.
  </Card>

  <Card title="KI-Bewertung" icon="chart-line" href="/api-reference/calls#ai-call-grading">
    Bewerten Sie jeden Testdurchlauf automatisch, um die Qualität im Zeitverlauf zu verfolgen.
  </Card>

  <Card title="Problemberichte" icon="triangle-exclamation" href="/api-reference/issue-reports">
    Markieren Sie bestimmte Tests zur menschlichen Überprüfung.
  </Card>

  <Card title="Webhook test-call.completed" icon="bolt" href="/de/webhooks/events">
    Leiten Sie Ergebnisse an Ihre CI / Slack / PagerDuty weiter.
  </Card>
</CardGroup>