Developer cookbook

Prueba un agente de extremo a extremo (API)

Ejecuta simulaciones únicas, lotes de escenarios en paralelo y suites de control de versiones mediante la API de ThunderPhone para detectar regresiones del agente antes de que quienes llaman las perciban.

Iterar en un agente de IA implica iterar en su prompt, sus herramientas y la forma en que maneja los 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 telefónico crea una ejecución de loopback SIP. Cada ejecución produce 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 antes del despliegue después de cada edición del prompt
• Conjuntos de regresión conectados a CI (conecta el webhook test-call.completed → haz fallar 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 produce mode="bot", mientras que phone_number produce 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 simultáneamente; resulta útil para conjuntos 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. Consulta 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 espacia la creación de ejecuciones para evitar sobrecargar al agente (0–60 s).

Intégralo en 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 fallas críticas. Las ejecuciones aprobadas se convierten en la referencia aceptada; las transiciones posteriores de aprobado→fallido se devuelven como regresiones.

Usa una clave de API de organización en CI. Este script activa la suite, consulta el estado hasta que la calificación y la comparación estén completas, y finaliza 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 identificador 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 referencia. Ambos endpoints vinculan la organización de la URL con la organización de la clave de API.

Patrones#

Corpus de regresiones por prompt#

Mantén un archivo JSON de tuplas {name, scenario_prompt, expected_outcome}. Con cada cambio de prompt, ejecuta el conjunto completo como un lote; compara las transcripciones y calificaciones con la ejecución anterior.

Prueba de humo por lanzamiento#

Un único 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.

Próximos pasos#