Prueba un agente de extremo a extremo (API)

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.

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#

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:

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

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:

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:

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 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:

#!/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) para ver el objeto de suite completo y los endpoints.

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#