Developer cookbook

Teste um agente de ponta a ponta (API)

Execute simulações únicas, lotes paralelos de cenários e suítes de validação de lançamento pela API do ThunderPhone para detectar regressões do agente antes que os clientes as percebam.

Iterar em um agente de IA significa iterar no prompt, nas ferramentas e na forma como ele lida com casos extremos. A API de simulações executa chamadas reais contra um agente usando um prompt de cenário fornecido por você. Direcionar para um agente cria uma execução de bot para bot; direcionar para um número de telefone cria uma execução de loopback SIP. Cada execução produz um registro de chamada real com transcrição, avaliação e cobrança, para que você veja exatamente como o agente se comporta e quanto ele custa.

Use-a para:

• Testes de fumaça antes da implantação após cada edição do prompt
• Suítes de regressão integradas ao CI (conecte o webhook test-call.completed → faça a compilação falhar se a pontuação cair)
• Testar sob estresse os limites de simultaneidade

Execução única: uma chamada#

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 é somente leitura e é derivado de target_type: agent produz mode="bot", enquanto phone_number produz mode="sip".

A resposta é um objeto de execução de simulação com status="queued". Consulte até que status se torne completed ou failed; quando call_id estiver definido, carregue a transcrição por meio de GET /v1/calls/{call_id}/transcript.

Lotes: cenários paralelos#

Execute N cenários simultaneamente — útil para suítes de regressão que atingem todos os casos extremos conhecidos em 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
  }'

A resposta contém uma lista run_ids com IDs das execuções filhas. Obtenha o status do lote:

curl https://api.thunderphone.com/v1/simulations/batches/{batch_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

run_count tem limite de 20; stagger_seconds espaça as criações para evitar sobrecarregar o agente (0–60 s).

Conecte ao CI#

Crie um conjunto de gates de lançamento na página Simulações (/dashboard/simulations) — escolha o agente, adicione cenários manualmente ou clique em Gerar cenários com IA para elaborá-los a partir do prompt do agente (com uma etapa opcional de casos extremos) e agrupe-os em um conjunto. Um conjunto fixa seus cenários e agente, além de uma taxa mínima de aprovação e uma regra opcional de zero falhas críticas. Execuções aprovadas se tornam a linha de base aceita; transições posteriores de aprovação→falha são retornadas como regressões.

Use uma chave de API da organização no CI. Este script aciona o conjunto, consulta até que a avaliação e a comparação sejam concluídas e encerra com código diferente de zero, a menos que o veredito seja 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 retorna 202 com o ID da execução. GET /v1/orgs/{org_id}/suites/{suite_id}/runs/{run_id} retorna status, verdict, pass_rate, critical_failure_count e a lista de regressions da linha de base. Ambos os endpoints vinculam a organização da URL à organização da chave de API.

Padrões#

Corpus de regressão por prompt#

Mantenha um arquivo JSON de tuplas {name, scenario_prompt, expected_outcome}. A cada alteração de prompt, execute o conjunto completo em lote; compare as transcrições e avaliações com a execução anterior.

Teste de fumaça por lançamento#

Um único lote de cinco cenários de caminho ideal executado após cada implantação. Sensível à latência, portanto mantenha stagger_seconds: 0.

Benchmarking de latência#

Execute cenários idênticos em diferentes níveis de produto (spark, bolt, storm-base). Compare as pontuações call.graded e duration_seconds de cada registro de chamada resultante.

Próximas etapas#