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 que regressões do agente sejam detectadas antes que os clientes as ouçam.

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

Use-a para:

• Testes de fumaça antes da implantação após cada edição de prompt
• Suites de regressão integradas ao CI (conecte o webhook test-call.completed → falhe a build se a pontuação cair)
• Testar limites de simultaneidade sob estresse

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 deriva 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 for definido, carregue a transcrição por meio de GET /v1/calls/{call_id}/transcript.

Lotes: cenários em paralelo#

Execute N cenários simultaneamente — útil para suites 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 de execuções filhas. Busque o status do lote:

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

run_count é limitado a 20; stagger_seconds espaça as inicializações para evitar sobrecarregar o agente (0–60 s).

Conecte ao CI#

Crie uma suíte de portão 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 criá-los a partir do prompt do agente (com uma etapa opcional para casos extremos) e agrupe-os em uma suíte. Uma suíte fixa seus cenários e agente, além de uma taxa mínima de aprovação e uma regra opcional de nenhuma falha crítica. 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 a suíte, 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.

Execute uma suíte em uma programação#

Abra a aba Simular do agente, selecione Suítes de portão de lançamento e crie ou edite uma suíte. Ative Executar em uma programação, escolha Frequência e Fuso horário e defina Minuto após a hora, Horário local ou Dia, conforme exibido. Selecione Salvar suíte. Desmarcar Executar em uma programação remove a programação do painel.

Via API#

Faça PATCH na suíte para adicionar ou substituir sua programação. Consulte Suítes (portões de lançamento) para ver o objeto completo da suíte e os 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 pode ser hourly, daily ou weekly. Use um fuso horário IANA. Programações por hora usam minute; programações diárias usam hour e minute; programações semanais também usam weekday, em que segunda-feira é 0 e domingo é 6. A resposta da suíte inclui next_run_at e last_run_at.

Os horários seguem as mudanças de horário de verão do fuso horário selecionado. As execuções programadas aparecem no histórico de execuções da suíte e usam seu agente, cenários, critérios e linha de base aceita atuais. Cada chamada de teste gerada emite test-call.completed; não há webhook de conclusão no nível da suíte. As chamadas programadas são cobradas pela mesma tarifa de simulação das execuções manuais da suíte e registram trigger: "schedule" na execução da suíte.

Para pausar uma programação sem alterar seus horários, faça PATCH no objeto completo da programação existente com "enabled": false. frequency é obrigatório; campos de fuso horário e horário omitidos são redefinidos para seus valores padrão, portanto inclua os valores existentes. Envie "schedule": null para remover a programação.

Padrões#

Corpus de regressão por prompt#

Mantenha um arquivo JSON com tuplas de {name, scenario_prompt, expected_outcome}. A cada alteração no 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 feliz executado após cada deploy. Sensível à latência, então mantenha stagger_seconds: 0.

Benchmark de latência#

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

Próximas etapas#