Testar a ação: conversando como um cliente ou preenchendo os parâmetros

Uma ação pode estar perfeita e nunca ser usada. O endereço responde, os parâmetros estão certos, e mesmo assim o agente não a chama, porque ele escolhe pelas instruções e não pelo endereço. São dois defeitos diferentes, e por isso existem dois testes: um mostra se o seu sistema responde, o outro mostra se o agente escolhe aquela ação. Este artigo cobre os dois, mais o teste da API inteira.

Testar a API inteira

Na tela da API, o botão Testar abre uma conversa com um agente que tem todas as ações daquela API na mesa, e mais nada. É o teste de escolha: você pergunta como um cliente perguntaria e vê qual das suas ações ele chama.

É o mais próximo do atendimento real, e o melhor de fazer depois de cadastrar duas ou três ações parecidas, quando o risco deixa de ser "não responde" e passa a ser "responde com a ação errada".

O botão fica desativado enquanto a API não tem nenhuma ação: sem ação não há o que testar. E se a API precisa saber quem está perguntando, o teste pede esses dados antes de rodar, em vez de chamar como anônimo e mostrar uma resposta que não é a que o cliente veria.

Testar uma ação

Na tela da ação, o botão Testar pergunta primeiro qual dos dois testes você quer.

Conversando, como um cliente

Você escreve em português, como quem está sendo atendido, e o agente decide. Aqui a mesa tem uma ferramenta só, esta ação, então o que o teste responde é: as minhas instruções fazem ele escolher esta ação, e ele monta os parâmetros sozinho a partir da frase?

É o defeito mais comum e o mais invisível, porque não aparece em erro nenhum: a chamada simplesmente não acontece. Escreva o que um cliente diria, não o que você diria. "Meu boleto de janeiro venceu?" ensina mais que "consultar título por período".

Preenchendo os parâmetros

Você monta a chamada e dispara, sem IA no meio. Responde a outra pergunta: o endereço está de pé e devolve o que eu espero com estes valores?

A gaveta mostra um campo para cada parâmetro, com asterisco nos obrigatórios, e o botão Executar. Três coisas ajudam mais do que parecem:

  • Token do usuário: aparece quando a API usa credencial dinâmica. Sem ele a chamada é recusada, exatamente como seria no atendimento.
  • Configurações avançadas: abre o JSON da requisição, espelhando os campos em tempo real. Dá para editar à mão quando você quer testar um caso que o formulário não monta. Campo vazio não é enviado.
  • A resposta inteira aparece embaixo, do jeito que o seu sistema devolveu. É dela que sai a árvore de "campos a manter" na etapa de resposta: você testa uma vez e escolhe o recorte clicando, em vez de decorar o formato.

Os valores digitados voltam na próxima abertura. Testar é ajustar, testar de novo e ajustar outra vez, e redigitar os mesmos parâmetros a cada rodada era o custo disso.

Quando ele não escolhe a sua ação

Se a conversa não chama a ação, o problema quase nunca é o endereço. Nesta ordem:

  1. As instruções falam a língua do cliente? "Use quando pedirem a situação de um cadastro" funciona melhor que "retorna o registro pelo id".
  2. Existe outra ação parecida? Diga nas instruções quando não usar esta e qual usar no lugar. É a parte que quase todo mundo pula e a que mais evita resposta errada.
  3. Os parâmetros estão descritos? Sem saber o formato esperado, o agente inventa um e a chamada volta erro.

No campo de instruções há o botão Melhorar com IA: ele reescreve o que você escreveu no formato que o agente lê melhor, mantendo o sentido. Serve como ponto de partida quando as instruções estão curtas demais, e você ajusta depois.

Uma ordem que economiza tempo

  1. Cadastre a ação e teste preenchendo os parâmetros: garante que o endereço e a credencial funcionam.
  2. Escolha os campos a manter usando a resposta que acabou de voltar.
  3. Teste conversando: garante que as instruções fazem o agente escolher.
  4. Com duas ou três ações irmãs, teste a API inteira: garante que ele escolhe a certa entre elas.