Debug e Depuração

Depure o agente durante o desenvolvimento, direto no Agent Builder: execução em modo debug, acompanhamento visual da ação e técnicas para encontrar a causa dos problemas.

Debug × Trilha de Auditoria

São duas ferramentas diferentes, para momentos diferentes:

Executar em modo Debug

Na segunda fileira do cabeçalho do Agent Builder, use o botão Debugar para disparar uma execução de depuração da versão aberta:

• A execução roda sobre a versão em desenvolvimento, e a versão publicada (release) não é afetada. Veja Versionamento.
• Os logs da execução de debug ficam separados do histórico oficial de produção.
• As evidências geradas em debug podem ser limpas ao final do desenvolvimento, sem poluir o registro das execuções reais.
• Enquanto a execução está rodando, o botão de Debugar vira Parar e surge o Pausar.
• Se alguma etapa tiver script com erro de sintaxe, o Debugar mostra a lista dessas etapas e pergunta se você quer rodar mesmo assim. É só um aviso: o Debug é justamente onde você vê o erro acontecer, e a decisão é sua. Veja Erros de sintaxe.

Pausar manualmente

O botão Pausar (que substitui o Debug enquanto a execução roda) pode ser acionado a qualquer momento, independente de haver falha. Pausa a execução até você clicar em Retomar.

Pausar em falhas (breakpoint)

O botão Pausar em falhas é um interruptor: quando ativo, a falha de uma etapa pede a pausa da execução, e aparece um banner identificando a etapa que falhou. A pausa é aplicada no limite entre etapas, então a Gestão de Erros e Exceções daquela etapa ainda decide o que fazer com o erro: se ela manda tentar de novo, o processo pausa antes da nova tentativa; se ela manda encerrar, o processo encerra e não há o que retomar. O banner traz duas opções:

• ▶ Continuar: retoma a execução normalmente a partir dali, respeitando a Gestão de Erros e Exceções configurada na etapa (Gestão de Erros e Exceções).
• ■ Parar execução: encerra a execução de debug ali mesmo.

Acompanhamento visual da ação

Com a execução em andamento, o próprio canvas do Agent Builder vira o painel de acompanhamento: cada card ganha uma borda colorida conforme seu status, e um painel de Log de Execução abre à direita com contadores e um console rolável com o evento de cada etapa em tempo real:

Copiar uma linha do log

Cada linha do console traz um ícone de cópia no final. Clique nele e a linha inteira vai para a área de transferência, já limpa: sem o próprio ícone e com os espaços normalizados, pronta para colar num chamado, num commit ou numa conversa com quem vai ajudar a investigar.

O ícone vira um ✓ por um instante para confirmar que copiou. É por linha, e não pelo log inteiro, justamente porque o que interessa quase sempre é uma mensagem de erro específica, não o histórico completo.

Assistir ao vivo

O botão Assistir ao vivo abre um modal com uma transmissão ao vivo da tela que o runtime está controlando naquele instante. Não é uma captura periódica, é um streaming contínuo de quadros da página real, enquanto a execução avança:

O indicador no canto muda conforme o estado da transmissão:

• AGUARDANDO...: conectado, esperando o primeiro quadro chegar.
• AO VIVO: recebendo quadros da execução em tempo real.
• SEM SESSÃO: nenhuma execução de debug ativa no momento para assistir.

A aba Variáveis

O console tem duas abas. LOGS é o histórico de eventos que a execução vai escrevendo. VARIÁVEIS mostra o estado do processo: todas as variáveis que a execução criou até ali e o valor que cada uma carrega naquele momento. A lista se preenche sozinha conforme as tarefas terminam, sem precisar clicar em nada.

É a resposta para a pergunta que aparece em todo debug: o que essa etapa colocou de fato na variável? Em vez de caçar a linha certa no log, você abre a aba e lê o valor.

O número ao lado do título conta quantas variáveis existem. Quando algo muda enquanto você está na aba de logs, um ponto azul avisa no título, sem trocar a aba embaixo de você.

O que cada linha mostra

O campo no topo filtra a lista, e procura tanto no nome quanto no valor. Achar em qual variável foi parar um número específico é o caso mais comum: cole o número no filtro e sobra só a linha que o contém.

Variáveis criadas por script

Variável que nasce dentro de um script Python ou Node aparece na aba como qualquer outra, desde que o script a devolva para o fluxo. O que fica só na memória do script, sem ser devolvido, não existe para o processo e por isso não aparece aqui. Não confunda com as listas de variáveis do builder: elas já mostram, antes de qualquer execução, os nomes que o script escreve no bm.done() (veja Manipulação de Variáveis: Script), enquanto esta aba mostra o que foi de fato gravado nesta execução, inclusive os nomes que o script monta em tempo de execução.

Variáveis de sistema

No rodapé da aba fica a gaveta Variáveis de sistema, sempre visível, com o número de chaves ao lado. Clique para abrir. São as variáveis que a plataforma mantém sozinha, como a etapa atual, o contador de etapas executadas e o tempo decorrido. Elas ficam separadas para não competir com as variáveis do seu processo, e o filtro alcança as duas listas: se o termo casar lá dentro, a gaveta abre sozinha e mostra quantas chaves casaram. A lista completa está em Manipulação de Variáveis.

Credenciais do Cofre

Valores grandes

O painel mostra o começo de valores muito grandes e avisa, embaixo da linha, qual é o tamanho total. O retorno inteiro de uma consulta com milhares de registros não cabe na tela nem ajuda a ler, e a forma do dado, que é o que interessa para mapear, já aparece nas primeiras linhas. Para trabalhar com a resposta crua completa, use a técnica de ler a resposta crua na aba de logs.

Quando a etapa falha

A aba também atualiza quando uma tarefa quebra, e a origem da variável aparece marcada em vermelho com a palavra (falhou). Esse é o estado exato do processo no instante do erro, que costuma ser a informação mais útil de todo o debug: dá para ver o que já tinha sido preenchido e o que ainda estava vazio quando a etapa parou.

Ao retomar de uma etapa

Quando você usa Reiniciar daqui, a execução começa com a massa de dados das tarefas anteriores já carregada. Essa massa herdada aparece na aba desde o início, com a origem Estado inicial, para você conferir com o que o processo está entrando na etapa antes mesmo de ela rodar.

Ações de debug em cada etapa

Passe o mouse sobre um card no canvas: acima dele aparece uma barrinha com três ações que existem só para o debug. Elas são o que evita ter que rodar o processo inteiro do zero a cada tentativa.

Cards com alguma dessas marcas mostram um selo permanente: 📌 para fixada e 🚫 para ignorada. Assim você reconhece, de relance, que aquele trecho não está rodando como rodaria em produção.

Reiniciar daqui

Ao fim de cada etapa executada em debug, a plataforma guarda um retrato do estado do processo naquele ponto. É esse retrato que permite retomar do meio.

O botão ▶ de uma etapa só fica ativo quando a etapa anterior já tem esse retrato, ou seja, depois de pelo menos uma execução que tenha chegado até ali. Ao clicar, o debug começa direto na etapa escolhida, com as variáveis já preenchidas como estavam.

Fixar a saída (📌)

Fixar congela o que a etapa produziu, para que as execuções seguintes não precisem refazer o trabalho. Serve para etapas lentas, caras ou instáveis que já estão funcionando e não são o alvo da investigação: uma consulta pesada, uma chamada de IA, um portal externo que responde devagar.

1. Rode o debug uma vez, até a etapa executar. Sem isso não há o que fixar, e a plataforma avisa.
2. Clique no 📌 acima do card. A etapa é fixada e o editor de valores abre.
3. Confira os valores. Cada variável produzida pela etapa aparece numa linha, e você pode editar qualquer uma antes de salvar.

Clicar no 📌 de uma etapa já fixada reabre esse editor a qualquer momento, com Salvar e Desafixar. Valores em texto, número, lista e objeto são aceitos: o campo interpreta o que você digitar e converte quando faz sentido.

Etapas de Decisão não têm o 📌, porque elas não produzem valor próprio, apenas escolhem o caminho.

Ignorar execução (🚫)

Marca a etapa para ser pulada no debug. Diferente de fixar, nada é devolvido no lugar: a etapa simplesmente não acontece. Use para tirar do caminho um trecho que atrapalha o teste, como o envio de um e-mail de verdade, uma escrita em sistema de produção ou uma etapa que você já sabe que falha e não é o foco agora.

Clicar de novo reativa a etapa.

Técnicas de Debug

1. Modo de execução lenta

Nas Configurações Gerais, configure o Atraso na Execução em ~2000 ms e responda "não" em Rodar o navegador em segundo plano (headless)?. Você vê o agente operando em câmera lenta no navegador.

2. Logs granulares

Adicione bm.bmLog() antes e depois de cada operação crítica no código customizado (Logs Customizados). Use os prefixos {application_*} para classificar a severidade de cada mensagem.

3. Evidência em todas as etapas

Temporariamente ative Gerar Evidência? em todas as etapas de navegador para ter um "filme" visual da execução (Screenshot). Desative quando terminar o debug.

4. Ler a resposta crua de uma chamada de API ou de conector

Toda etapa Chamar API Rest despeja no console a resposta completa do serviço, marcada com 📥 e formatada para leitura. Você vê o JSON exatamente como chegou, antes de qualquer mapeamento. O mesmo vale para os conectores: a linha de retorno traz a resposta do serviço, e no caso dos conectores de banco, uma amostra das linhas da consulta em JSON.

É o caminho mais direto para resolver as duas dúvidas mais comuns nessas etapas:

• "O serviço devolveu o que eu esperava?" A resposta está ali, inteira, sem depender de você ter mapeado o campo certo.
• "Por que minha variável veio vazia?" Compare o caminho que você escreveu em Resultados com a estrutura real do JSON. Quase sempre é um nível a mais ou a menos. O console também registra um aviso nomeando o Path que não foi encontrado e listando os campos que a resposta trouxe.

Outros dois avisos aparecem no console dessas etapas sem que você precise procurar:

• Variável que não resolveu. Ela vai literal para a chamada, em vez de virar vazio, e o console diz qual variável faltou e em que seção da etapa, inclusive quando está na URL.
• Erro devolvido pela API. O console mostra o status e o corpo da resposta, que é onde a API costuma explicar o motivo. Em dois casos ele ainda aponta a causa provável: recusa de autenticação quando a etapa não envia nenhum header de credencial, e recusa de formato quando a etapa não declara o tipo do corpo.

Para conferir a chamada antes de rodar o processo, a seção Resultados da etapa tem o botão Testar chamada, que dispara a requisição a partir da tela de configuração.

5. Inspecionar variáveis no código

Para ver o estado das variáveis em um ponto específico:

bm.bmLog('[DEBUG] variáveis: ' + JSON.stringify(bm.globalData, null, 2));

6. Teste com parâmetros específicos

Ao executar manualmente, informe parâmetros de inicialização com dados que você sabe que causam o problema, para reproduzir o bug de forma determinística.

Problemas comuns e soluções