Atualizado em Nov 1, 2026

Testes e Depuração

O que você vai aprender

• Como usar o botão Debug para testar pré-ações
• Como testar seu agente em uma conversa ao vivo
• Como testar um agente pela API e ver todas as mensagens que ele enviou
• Como usar níveis de log e logs para diagnosticar problemas

Antes de conectar seu agente de IA a um canal de produção, é importante testá-lo completamente. O AutoTalk fornece várias ferramentas para testes e depuração de agentes em diferentes níveis.

Depurando pré-ações

Se seu agente LLM usa pré-ações (configuradas na aba Actions), você pode testá-las sem executar uma conversa completa:

1. Abra o agente e vá para a aba Actions.
2. Clique no botão Iniciar Debug (cuja dica de ferramenta diz "Depurar tudo").
3. O AutoTalk executa cada etapa de pré-ação em sequência e mostra o resultado de cada uma, incluindo quaisquer dados produzidos ou erros encontrados.

Isso permite verificar que cada etapa funciona corretamente antes de o agente entrar em operação. Se uma etapa falhar, você pode corrigi-la e clicar em Iniciar Debug novamente imediatamente.

Testando com conversas ao vivo

A maneira mais realista de testar um agente é atribuí-lo a um canal e enviar mensagens como um contato faria:

1. Atribua o agente a um canal de teste (ou um número/conta secundária que você controla).
2. Envie mensagens para aquele canal de um telefone pessoal ou navegador.
3. Observe como o agente responde na caixa de entrada do AutoTalk.
4. Na visualização da conversa, procure o botão de alternância do bot -- ele permite habilitar ou desabilitar o agente por conversa. Use-o para alternar entre respostas automatizadas e manuais durante os testes.

O que testar

• Perguntas comuns: Faça os tipos de perguntas que seus contatos reais fazem com mais frequência.
• Casos extremos: Tente perguntas ambíguas, fora do tópico ou com múltiplas partes para ver como o agente as trata.
• Testes de limites: Pergunte sobre tópicos que o agente deve recusar (para verificar se suas mensagens do sistema definem barreiras adequadas).
• Uso de ferramentas: Se o agente tem ferramentas configuradas, acione cenários que devem causar chamadas de ferramentas e verifique os resultados.
• Conversas longas: Continue uma conversa por muitas trocas para verificar se o contexto é mantido e se o agente não perde o fio.

Testando pela API (talkToAgent)

Para testes automatizados e scripts de avaliação, um agente pode ser acionado sem um canal real. A função talkToAgent envia uma mensagem ao agente, como um contato no canal de API do próprio agente, executa o agente e devolve o que voltou:

POST /v1/dynadata/type/agents/item/{agentId}/executeFunction/talkToAgent

{"type": "text", "body": {"text": "Quero marcar uma consulta"}}

A chave de API precisa do scope automation:admin. type é obrigatório -- envie-o também para uma mensagem de texto: uma requisição sem ele é recusada com 400 e {"error": "missing_fields", "fields": ["type"], "message": "Missing required argument(s): type", …}. Ele aceita um destes valores: text, image, audio, video, document, location, options, option ou contacts; mensagens image, audio, video e document precisam de um body.file. Deixe contactId de fora para começar com um novo contato de API, e passe o data.contactId de uma resposta anterior para continuar a mesma conversa.

A resposta usa o envelope da /v1 -- success e data --, com o que talkToAgent devolveu dentro de data. Uma chamada bem-sucedida responde 200:

{
  "success": true,
  "data": {
    "success": true,
    "contactId": "…",
    "messages": [
      {"role": "assistant", "body": {"controlType": "…"}, "type": "control"},
      {"role": "assistant", "content": "Qual dia fica bom para você?", "type": "text"}
    ],
    "outboundMessages": [
      {"role": "assistant", "messageId": "…", "type": "options", "body": {"…": "…"}},
      {"role": "assistant", "messageId": "…", "type": "text", "content": "Qual dia fica bom para você?"}
    ],
    "logs": [{"level": "info", "message": "talkToAgent started"}, "…"]
  }
}

• data.messages é o buffer de resposta da execução: o que o modelo escreveu, mais entradas internas de type: "control" -- registros de chamadas de ferramenta, por exemplo -- que o contato nunca vê. Ele não inclui o que as ferramentas do agente enviaram. Então, quando uma ferramenta enviou a resposta e o modelo não escreveu mais nada depois -- uma execução que terminou em tool_reply, que é também como uma ferramenta com Encerra o turno a encerra --, messages só tem entradas internas; leia outboundMessages para ver o que o contato recebeu.
• data.outboundMessages é o que o contato de fato recebeu durante a chamada, da mais antiga para a mais recente: mensagens enviadas por ferramentas -- um documento ou um menu de opções de Compor Resposta da Conversa, por exemplo -- e a resposta final, cada uma uma vez. Cada entrada é {role, messageId, type, content?, body?}: content é o texto ou a legenda, e body é mantido para toda mensagem que não é texto, então um documento mantém seu arquivo e um menu suas opções. Mensagens internas de status ficam de fora, e a lista tem no máximo 50 mensagens -- 20 em um caso alternativo descrito abaixo.
• Ela cobre esta conversa apenas. Uma ferramenta que avisou outra pessoa -- alguém da equipe, por exemplo -- enviou essa mensagem para outra conversa, então ela não está na lista.
• outboundMessages: null significa que a lista não pôde ser lida (o motivo está em logs), não que nada foi enviado. Nada enviado é uma lista vazia.
• A lista é lida da conversa por tempo, então qualquer outra coisa que envie para o mesmo contato durante a chamada -- um segundo talkToAgent com o mesmo contactId, ou um workflow reagindo à mensagem -- também aparece.
• Caso alternativo. Quando o buffer de resposta da execução não volta para a chamada, messages é lido da conversa: no máximo 20 mensagens do agente, então ele inclui o que as ferramentas enviaram, e também as entradas internas. Isso acontece quando outra execução já estava respondendo a este contato (a chamada espera as mensagens dessa execução), ou quando nada voltou da execução. No segundo caso, outboundMessages vem dessa mesma leitura, sem as entradas internas, e por isso tem no máximo 20 mensagens em vez de 50. Nos dois casos a chamada para de esperar na primeira leitura que encontra alguma mensagem do agente, então, se a execução ainda estava enviando nesse momento, as duas listas podem ficar incompletas. No primeiro caso, outboundMessages vem de uma segunda leitura da conversa, feita depois dessa, então uma mensagem que a execução enviou entre as duas leituras está em outboundMessages mas não em messages; o que ela enviou depois da última leitura não está em nenhuma delas.

data.success: false significa que a função rodou, mas recusou a mensagem ou falhou: data.error diz o motivo, e data.logs mostra até onde ela chegou. O status HTTP continua 200 e o success de fora continua true -- ele só diz que a função foi chamada --, então confira data.success:

{"success": true, "data": {"success": false, "error": "For text messages, body.text must be a non-empty string.", "logs": []}}

Uma requisição que a API recusa, ou que falha fora do próprio talkToAgent, não tem data: ela responde com um status de erro e um objeto de erro. Uma chave sem automation:admin recebe 403 com {"error": "scope_denied", "code": "scope_denied", "message": "…", "userMessage": "…", "details": {…}}, um id de agente que não existe recebe 400 com {"error": "not_found", …}, e a maioria das falhas inesperadas também recebe 400, com {"error": "dynadata_function_error", "code": "execution_error", "message": "…", "userMessage": "…", "details": null}. Só uma falha fora da própria chamada da função recebe 500, com {"success": false, "errorId": "…", "message": "Internal server error"}.

Usando níveis de log para depuração

Cada agente tem uma configuração de Log Level no seu formulário de configuração. Durante testes e depuração, defina para um nível de verbosidade mais alto para capturar mais detalhes sobre o que o agente está fazendo internamente.

Uma vez que o agente esteja estável e em produção, você pode diminuir o nível de log para reduzir ruído e uso de armazenamento. Veja Visualizando Logs para detalhes sobre onde encontrar e ler os logs.

Problemas comuns e soluções

Problema	Causa possível	Solução
Agente fornece informações imprecisas	Mensagens do sistema são muito vagas ou faltam fatos importantes	Adicione detalhes mais específicos às mensagens do sistema na aba Messages
Agente não usa suas ferramentas	Descrições das ferramentas são pouco claras ou a escolha de ferramenta está mal configurada	Revise as descrições das ferramentas na aba Tools e garanta que a escolha de ferramenta esteja definida como "auto"
Respostas são muito longas ou prolixas	Temperatura está muito alta ou o máximo de tokens não está definido	Diminua a temperatura na aba Advanced e defina um limite de tokens
Agente responde sobre tópicos que deveria evitar	Faltam barreiras nas mensagens do sistema	Adicione instruções explícitas de "não faça" às mensagens do sistema
Pré-ações falham silenciosamente	Uma etapa tem configuração incorreta	Use o botão "Iniciar Debug" (dica de ferramenta "Depurar tudo") na aba Actions para identificar a etapa que falha
Agente não responde de forma alguma	O agente não está atribuído ao canal, ou o botão de alternância do bot está desativado	Verifique a atribuição do canal e confirme que o botão de alternância do bot está habilitado na conversa
Agente envia um menu de opções e depois mais texto abaixo dele	O modelo ganhou outro turno depois da ferramenta do menu	Ative Encerra o turno nessa ferramenta (veja Mensagens do sistema e ferramentas)

Próximos passos

• Visualizando logs
• Mensagens do Sistema e Ferramentas