--- title: "Testa un agente end-to-end (API)" description: "Esegui simulazioni una tantum, batch di scenari in parallelo e suite di controllo del rilascio tramite l'API ThunderPhone, così le regressioni dell'agente vengono rilevate prima che i clienti le sentano." --- Preferisci la dashboard? La stessa funzionalità è disponibile in **Simulazioni** (`/dashboard/simulations`), inclusa la generazione di scenari con l'AI — consulta [Simula una chiamata](/it/guides/simulate-a-call). Questa pagina descrive il percorso programmatico. Iterare su un agente AI significa iterare sul prompt, sugli strumenti e sul modo in cui gestisce i casi limite. L'**API delle simulazioni** esegue chiamate reali verso un agente usando un prompt di scenario fornito da te. Indirizzare un agente crea un'esecuzione bot-to-bot; indirizzare un numero di telefono crea un'esecuzione di loopback SIP. Ogni esecuzione produce un registro chiamata reale con trascrizione, valutazione e fatturazione, così puoi vedere esattamente come si comporta l'agente e quanto costa. Usala per: - Test smoke pre-distribuzione dopo ogni modifica al prompt - Suite di regressione integrate nella CI (collega il webhook `test-call.completed` → fai fallire la build se il punteggio diminuisce) - Test di stress dei limiti di concorrenza ## Esecuzione singola: un solo test ```bash 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 }' ``` Campi: | Campo | Tipo | Obbligatorio | Descrizione | |-------|------|----------|-------------| | `target_type` | stringa | sì | `agent` o `phone_number` | | `target_id` | intero | sì | L'ID dell'agente (o l'ID del numero di telefono) | | `direction` | stringa | no | `outbound` (predefinito; il chiamante di test effettua la chiamata) o `inbound` (il chiamante di test risponde) | | `scenario_prompt` | stringa | no | Determina ciò che dice il bot di test | | `language` / `primary_language` | stringa | no | Lingua per il chiamante di test; i codici non supportati vengono rifiutati | | `simulator_product` | stringa | no | `testing` (predefinito) o `spark` per un chiamante simulato più simile a un essere umano, ad esempio per test di consultazione con trasferimento assistito | | `consent_to_charge` | booleano | **sì** | Deve essere `true`. La stima addebita sia l'agente selezionato sia il chiamante simulato a una tariffa fissa al minuto, più eventuali tratte telefoniche | | `target_number` | stringa | no | Override E.164 per il lato remoto; altrimenti viene utilizzato il numero di test della piattaforma | `mode` è di sola lettura e deriva da `target_type`: `agent` produce `mode="bot"`, mentre `phone_number` produce `mode="sip"`. La risposta è un [oggetto di esecuzione simulazione](/api-reference/test-calls#test-call-run-object) con `status="queued"`. Esegui il polling finché `status` non diventa `completed` o `failed`; una volta impostato `call_id`, carica la trascrizione tramite [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript). ## Batch: scenari in parallelo Esegui N scenari contemporaneamente, utile per suite di regressione che coprono ogni caso limite noto in parallelo: ```bash 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 }' ``` La risposta contiene un elenco `run_ids` di ID delle esecuzioni figlie. Recupera lo stato del batch: ```bash curl https://api.thunderphone.com/v1/simulations/batches/{batch_id} \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` `run_count` è limitato a 20; `stagger_seconds` distanzia l'avvio delle esecuzioni per evitare di sovraccaricare l'agente (0–60 s). ## Integralo nella CI Crea una suite di gate di rilascio nella pagina **Simulazioni** (`/dashboard/simulations`): seleziona l'agente, aggiungi scenari manualmente oppure fai clic su **Genera scenari con l'AI** per crearne una bozza dal prompt dell'agente (con un passaggio facoltativo per i casi limite), quindi raggruppali in una suite. Una suite fissa i propri scenari e l'agente, oltre a una percentuale minima di superamento e a una regola facoltativa di zero errori critici. Le esecuzioni superate diventano la baseline accettata; le successive transizioni da superato a non superato vengono restituite come regressioni. Usa una [chiave API dell'organizzazione](/api-reference/developer-api-keys) nella CI. Questo script avvia la suite, esegue il polling finché la valutazione e il confronto non sono completi, quindi termina con un codice diverso da zero a meno che il verdetto non sia `pass`: ```bash #!/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` restituisce `202` con l'ID dell'esecuzione. `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` restituisce `status`, `verdict`, `pass_rate`, `critical_failure_count` e l'elenco di `regressions` della baseline. Entrambi gli endpoint associano l'organizzazione nell'URL all'organizzazione della chiave API. ## Esegui una suite secondo una pianificazione Apri la scheda **Simula** dell'agente, seleziona **Suite di gate di rilascio** e crea o modifica una suite. Attiva **Esegui secondo una pianificazione**, scegli **Frequenza** e **Fuso orario**, quindi imposta **Minuto dopo l'ora**, **Ora locale** o **Giorno** come mostrato. Seleziona **Salva suite**. Deselezionando **Esegui secondo una pianificazione** rimuovi la pianificazione dal dashboard. ### Tramite API Esegui PATCH sulla suite per aggiungere o sostituire la relativa pianificazione. Consulta [Suite (gate di rilascio)](/api-reference/test-scenarios#suites-release-gates) per l'oggetto suite completo e gli endpoint. ```bash curl -X PATCH https://api.thunderphone.com/v1/suites/{suite_id} \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "schedule": { "enabled": true, "frequency": "daily", "timezone": "America/Chicago", "hour": 6, "minute": 30 } }' ``` `frequency` può essere `hourly`, `daily` o `weekly`. Usa un fuso orario IANA. Le pianificazioni orarie usano `minute`; quelle giornaliere usano `hour` e `minute`; quelle settimanali usano anche `weekday`, dove lunedì è `0` e domenica è `6`. La risposta della suite include `next_run_at` e `last_run_at`. Gli orari seguono i cambiamenti dell'ora legale del fuso orario selezionato. Le esecuzioni pianificate vengono visualizzate nella cronologia delle esecuzioni della suite e usano l'agente, gli scenari, i criteri e la baseline accettata correnti. Ogni chiamata di test generata emette `test-call.completed`; non esiste un webhook di completamento a livello di suite. Le chiamate pianificate vengono fatturate alla stessa tariffa di simulazione delle esecuzioni manuali della suite e registrano `trigger: "schedule"` nell'esecuzione della suite. Per sospendere una pianificazione senza modificarne gli orari, esegui PATCH dell'oggetto di pianificazione completo esistente con `"enabled": false`. `frequency` è obbligatorio; i campi di fuso orario e ora omessi vengono reimpostati ai valori predefiniti, quindi includi i valori esistenti. Invia `"schedule": null` per rimuovere la pianificazione. ## Modelli ### Corpus di regressione per prompt Mantieni un file JSON di tuple `{name, scenario_prompt, expected_outcome}`. A ogni modifica del prompt, esegui l'intero set in batch; confronta le trascrizioni e le valutazioni con l'esecuzione precedente. ### Test smoke per release Un singolo batch di cinque scenari a esito positivo da eseguire dopo ogni deploy. Sensibile alla latenza, quindi mantieni `stagger_seconds: 0`. ### Benchmark della latenza Esegui scenari identici su diversi livelli di prodotto (`spark`, `bolt`, `storm-base`). Confronta i punteggi `call.graded` e il valore `duration_seconds` di ogni log di chiamata risultante. --- ## Passaggi successivi Ogni parametro di query, codice di stato e struttura del batch. Assegna automaticamente un punteggio a ogni esecuzione di test per monitorare la qualità nel tempo. Contrassegna test specifici per la revisione umana. Invia i risultati in streaming al tuo CI / Slack / PagerDuty.