--- title: "Prueba un agente de extremo a extremo (API)" description: "Ejecuta simulaciones únicas, lotes de escenarios en paralelo y suites de validación de lanzamientos mediante la API de ThunderPhone para detectar regresiones del agente antes de que los clientes las escuchen." --- ¿Prefieres el dashboard? La misma funcionalidad está en **Simulaciones** (`/dashboard/simulations`), incluida la generación de escenarios con IA; consulta [Simular una llamada](/es/guides/simulate-a-call). Esta página explica la ruta programática. Iterar sobre un agente de IA implica iterar sobre su prompt, sus herramientas y la forma en que maneja casos límite. La **API de simulaciones** ejecuta llamadas reales contra un agente usando un prompt de escenario que proporcionas. Dirigirse a un agente crea una ejecución de bot a bot; dirigirse a un número de teléfono crea una ejecución de loopback SIP. Cada ejecución genera un registro de llamada real con transcripción, evaluación y facturación, para que veas exactamente cómo se comporta el agente y cuánto cuesta. Úsala para: - Pruebas de humo previas al despliegue después de cada edición del prompt - Suites de regresión conectadas a CI (conecta el webhook `test-call.completed` → falla la compilación si baja la puntuación) - Pruebas de estrés de los límites de concurrencia ## Ejecución única: una sola ejecución ```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 }' ``` Campos: | Campo | Tipo | Obligatorio | Descripción | |-------|------|----------|-------------| | `target_type` | cadena | sí | `agent` o `phone_number` | | `target_id` | entero | sí | El ID del agente (o el ID del número de teléfono) | | `direction` | cadena | no | `outbound` (predeterminado; quien llama de prueba realiza la llamada) o `inbound` (quien llama de prueba responde) | | `scenario_prompt` | cadena | no | Determina lo que dice el bot de prueba | | `language` / `primary_language` | cadena | no | Idioma para quien llama de prueba; los códigos no compatibles se rechazan | | `simulator_product` | cadena | no | `testing` (predeterminado) o `spark` para quien llama simulado más parecido a una persona, como en pruebas de consulta de transferencia asistida | | `consent_to_charge` | booleano | **sí** | Debe ser `true`. La estimación cobra tanto al agente seleccionado como a quien llama simulado con una tarifa fija por minuto, más cualquier tramo de telefonía | | `target_number` | cadena | no | Anulación E.164 para el lado remoto; de lo contrario, se usa el número de prueba de la plataforma | `mode` es de solo lectura y se deriva de `target_type`: `agent` genera `mode="bot"`, mientras que `phone_number` genera `mode="sip"`. La respuesta es un [objeto de ejecución de simulación](/api-reference/test-calls#test-call-run-object) con `status="queued"`. Consulta periódicamente hasta que `status` sea `completed` o `failed`; una vez que se establezca `call_id`, carga la transcripción mediante [`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript). ## Lotes: escenarios en paralelo Ejecuta N escenarios de forma simultánea; es útil para suites de regresión que cubren cada caso límite conocido en paralelo: ```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 respuesta contiene una lista `run_ids` con los ID de las ejecuciones secundarias. Obtén el estado del lote: ```bash curl https://api.thunderphone.com/v1/simulations/batches/{batch_id} \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" ``` `run_count` tiene un límite de 20; `stagger_seconds` separa la creación de las ejecuciones para evitar sobrecargar al agente (0–60 s). ## Conéctalo a CI Crea una suite de control de lanzamiento en la página **Simulaciones** (`/dashboard/simulations`): elige el agente, agrega escenarios manualmente o haz clic en **Generar escenarios con IA** para redactarlos a partir del prompt del agente (con una revisión opcional de casos límite) y agrúpalos en una suite. Una suite fija sus escenarios y agente, además de una tasa mínima de aprobación y una regla opcional de cero fallos críticos. Las ejecuciones aprobadas se convierten en la base de referencia aceptada; las transiciones posteriores de aprobado a fallido se devuelven como regresiones. Usa una [clave API de organización](/api-reference/developer-api-keys) en CI. Este script activa la suite, consulta hasta que la calificación y la comparación se completen, y sale con un código distinto de cero a menos que el veredicto sea `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` devuelve `202` con el ID de ejecución. `GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id}` devuelve `status`, `verdict`, `pass_rate`, `critical_failure_count` y la lista de `regressions` de la base de referencia. Ambos endpoints vinculan la organización de la URL con la organización de la clave API. ## Ejecuta una suite según una programación Abre la pestaña **Simular** del agente, selecciona **Suites de control de lanzamiento** y crea o edita una suite. Activa **Ejecutar según una programación**, elige **Frecuencia** y **Zona horaria**, y luego configura **Minuto después de la hora**, **Hora local** o **Día**, según se muestra. Selecciona **Guardar suite**. Al desmarcar **Ejecutar según una programación** se elimina la programación del dashboard. ### Mediante la API Envía un PATCH a la suite para agregar o reemplazar su programación. Consulta [Suites (controles de lanzamiento)](/api-reference/test-scenarios#suites-release-gates) para ver el objeto de suite completo y los endpoints. ```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` puede ser `hourly`, `daily` o `weekly`. Usa una zona horaria IANA. Las programaciones por hora usan `minute`; las programaciones diarias usan `hour` y `minute`; las programaciones semanales también usan `weekday`, donde el lunes es `0` y el domingo es `6`. La respuesta de la suite incluye `next_run_at` y `last_run_at`. Las horas siguen los cambios de horario de verano de la zona horaria seleccionada. Las ejecuciones programadas aparecen en el historial de ejecuciones de la suite y usan su agente, escenarios, criterios y base de referencia aceptada actuales. Cada llamada de prueba generada emite `test-call.completed`; no existe un webhook de finalización a nivel de suite. Las llamadas programadas se facturan con la misma tarifa de simulación que las ejecuciones manuales de la suite y registran `trigger: "schedule"` en la ejecución de la suite. Para pausar una programación sin cambiar su horario, envía un PATCH del objeto de programación existente completo con `"enabled": false`. `frequency` es obligatorio; los campos de zona horaria y hora omitidos se restablecen a sus valores predeterminados, así que incluye los valores existentes. Envía `"schedule": null` para eliminar la programación. ## Patrones ### Corpus de regresión por prompt Mantén un archivo JSON de tuplas `{name, scenario_prompt, expected_outcome}`. Con cada cambio en el prompt, ejecuta el conjunto completo como un lote; compara las transcripciones y calificaciones con la ejecución anterior. ### Prueba de humo por versión Un solo lote de cinco escenarios de ruta exitosa que ejecutas después de cada despliegue. Es sensible a la latencia, así que mantén `stagger_seconds: 0`. ### Evaluación comparativa de latencia Ejecuta escenarios idénticos en diferentes niveles de producto (`spark`, `bolt`, `storm-base`). Compara las puntuaciones de `call.graded` y `duration_seconds` de cada registro de llamada resultante. --- ## Siguientes pasos Cada parámetro de consulta, código de estado y estructura de lote. Califica automáticamente cada ejecución de prueba para seguir la calidad a lo largo del tiempo. Marca pruebas específicas para revisión humana. Envía resultados en tiempo real a tu CI / Slack / PagerDuty.