--- title: "Teste um agente de ponta a ponta (API)" description: "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." --- Prefere o dashboard? A mesma funcionalidade está em **Simulações** (`/dashboard/simulations`), incluindo geração de cenários por IA — veja [Simular uma chamada](/pt/guides/simulate-a-call). Esta página aborda o caminho programático. 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 ```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 | Obrigatório | Descrição | |-------|------|-------------|-----------| | `target_type` | string | sim | `agent` ou `phone_number` | | `target_id` | integer | sim | O ID do agente (ou ID do número de telefone) | | `direction` | string | não | `outbound` (padrão; quem liga para teste faz a chamada) ou `inbound` (quem liga para teste atende) | | `scenario_prompt` | string | não | Define o que o bot de teste diz | | `language` / `primary_language` | string | não | Idioma de quem liga para teste; códigos não compatíveis são rejeitados | | `simulator_product` | string | não | `testing` (padrão) ou `spark` para quem liga simulado mais semelhante a um humano, como em testes de consulta de transferência assistida | | `consent_to_charge` | boolean | **sim** | Deve ser `true`. A estimativa cobra tanto o agente selecionado quanto quem liga simulado a uma taxa fixa por minuto, além de qualquer trecho de telefonia | | `target_number` | string | não | Substituição E.164 para o lado remoto; caso contrário, é usado o número de teste da plataforma | `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](/api-reference/test-calls#test-call-run-object) 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`](/api-reference/calls#get-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: ```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 }' ``` A resposta contém uma lista `run_ids` com IDs de execuções filhas. Busque o status do lote: ```bash 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](/api-reference/developer-api-keys) 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`: ```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` 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)](/api-reference/test-scenarios#suites-release-gates) para ver o objeto completo da suíte e os 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` 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 Todos os parâmetros de consulta, códigos de status e formatos de lote. Pontue automaticamente cada execução de teste para acompanhar a qualidade ao longo do tempo. Sinalize testes específicos para revisão humana. Envie resultados para seu CI / Slack / PagerDuty.