Agent Builder

O estúdio visual onde o fluxo do agente é modelado: canvas, cabeçalho de comando, painéis, grupos de etapas e Copilot.

O Agent Builder é o centro de Orquestração do browserMate: RPA (automação de navegador e desktop), chamadas de API e Agentes de IA convivem no mesmo canvas, como etapas do mesmo fluxo visual, sem trocar de ferramenta para cada tipo de tarefa.

O canvas

O Agent Builder apresenta o processo como um fluxo de cards conectados da esquerda para a direita. Cada card é uma etapa e as linhas tracejadas são as conexões e rotas entre elas.

O cabeçalho de comando

Todo o controle do builder mora no cabeçalho, organizado em duas fileiras. A primeira responde "que agente é este e em que versão estou". A segunda responde "onde ele roda, está pronto e o que posso abrir".

Fileira 1: identidade e versão

Fileira 2: runtime, execução e painéis

Runtime e ambiente

• RUNTIME: escolhe onde o agente executa, entre os runtimes cadastrados e a Sandbox. Lista só runtimes, pelo nome e em ordem alfabética, todos selecionáveis, com a Sandbox no fim. Escolher um runtime sem instalação no ambiente do agente leva o agente junto para um ambiente que o runtime tem, com aviso. Passar o mouse sobre o campo mostra o nome inteiro do runtime escolhido. Com o agente publicado, a troca vale imediatamente, sem versão nova, e a opção Selecione... fica desabilitada (o agente publicado precisa de um runtime). Numa versão em desenvolvimento, a escolha vale para o debug e vai junto na publicação. Fica travado quando outra pessoa está desenvolvendo o processo. Em um agente compartilhado com você, o campo mostra Runtime do dono do agente e a Sandbox, sem os runtimes da sua conta: trocar o runtime e o ambiente de um agente é sempre atribuição do dono dele. Veja O campo RUNTIME.
• Dev, Homolog e Prod: três botões juntos, logo ao lado do campo RUNTIME, que escolhem o ambiente do agente. O botão ativo fica preenchido com a cor do ambiente (azul em Desenvolvimento, âmbar em Homologação, verde em Produção), e a borda de baixo do cabeçalho mostra uma linha fina na mesma cor. O ambiente é do agente inteiro: decide qual instalação do runtime escolhido roda o agente e qual valor do Cofre é usado. O botão de um ambiente em que o runtime escolhido não tem instalação, ou cuja instalação está suspensa pelo plano, fica desabilitado, com o motivo na dica. Uma pequena marca amarela num botão indica que falta credencial do Cofre naquele ambiente. Com o agente publicado, a troca vale imediatamente, sem versão nova; ir para Produção pede confirmação. Os botões ficam desabilitados nas mesmas situações em que o campo RUNTIME trava. Veja Os botões Dev, Homolog e Prod.

Pendências, salvar e desfazer

• Indicador de pendências: mostra quantos itens faltam para o agente estar pronto. Clique para ver a lista (fluxo ainda sem nenhuma etapa, etapas sem configuração, runtime não selecionado, runtime sem instalação no ambiente do agente ou com essa instalação suspensa pelo plano, chave do Cofre sem valor para o ambiente, agendamento ligado apontando para um runtime sem instalação no ambiente do agente, modelo não salvo, mapeamento de webhook em aberto, script com erro de sintaxe). Enquanto ele não fica verde, o botão de publicar não aparece. Detalhes em Versionamento → Pendências.
• ↺ Reorganizar e Desfazer: recarrega a ordem original das etapas antes da última alteração.
• 💾 Salvar: grava as alterações pendentes do canvas.

Execução e depuração

• ▶ Debugar: inicia uma execução de depuração da versão em desenvolvimento. Veja Debug e Depuração.
• ⏸ Pausar: aparece durante a execução e suspende o agente sem encerrá-lo.
• Pausar em falhas: quando ligado, a execução pausa na etapa que falhar, antes de aplicar o tratamento de exceção configurado. Você escolhe continuar (o tratamento configurado segue valendo), corrigir e retomar dali, ou parar.
• 👁 Assistir ao vivo: acompanha a execução em tempo real, inclusive quando o runtime é remoto.
• ▢ Console da última sessão: abre a saída de console da execução mais recente, com cópia por linha.

Painéis e atalhos

Configurações do Agente

O atalho de Configurações do Agente abre o formulário de Configurações Gerais em um painel lateral: descrição, limites de execução, índices de produtividade, navegador, componentes, tempos e comunicação, tudo sem sair do builder.

Modo somente leitura

O botão EDIT do card nunca fica desabilitado. Quando não existe versão em desenvolvimento, o builder abre exibindo a versão publicada, com uma faixa no topo explicando o motivo.

Nesse modo somem da tela: criar, mover e excluir etapas, salvar, reordenar, o Debug, o Copilot e os botões de publicar e cancelar versão. Continuam disponíveis a leitura do fluxo, o campo RUNTIME, os botões de ambiente Dev, Homolog e Prod, a consulta ao Webhook, o botão Desenvolver versão e a consulta à versão publicada no painel da etapa (engrenagem, mapear ou duplo clique no card) e nas Configurações do Agente: os campos aparecem travados e o botão de salvar não existe.

Os estados e o que fazer em cada um estão em Versionamento → O editor em somente leitura.

Barra inferior

Fixa na base do canvas, é a barra de navegação visual do fluxo:

• 🏠 Início e 🏳 Fim: leva o canvas ao começo ou ao final do fluxo.
• ◀ ▶: percorre as etapas uma a uma, com a barra de progresso mostrando onde você está.
• Buscar card: localiza uma etapa pelo nome em fluxos grandes, com contador de ocorrências.
• Zoom: aproxima, afasta e volta a 100%.
• Ajustar: refaz o diagrama do zero, alinhando fileiras, ramos e nós de junção, com espaço confortável entre as etapas e entre os ramos. Cada rota ganha a altura de que precisa, mesmo com decisões dentro de decisões. Descarta os posicionamentos manuais dos cards.

Comportamento durante o Debug

Enquanto uma execução de Debug está rodando, o canvas muda de aparência para refletir o progresso ao vivo:

• Os botões de execução mudam: o ▶ Debugar vira ⏹ Parar e surge o ⏸ Pausar, para interromper ou suspender a execução sem fechar o builder.
• Cards ganham borda colorida por status: verde para etapas já executadas com sucesso, vermelho para a etapa atual quando ela falha (por exemplo, um tempo esgotado aguardando um seletor). Com Pausar em falhas ativado, é exatamente onde a execução pausa: no card vermelho, antes de o tratamento de exceção configurado agir.
• Painel de Log de Execução: abre à direita do canvas com os contadores Executadas / Sucesso / Falhas / Anuladas do ciclo atual e um console rolável com uma linha por evento (sucesso, erro, progresso do loop), em tempo real.
• Aba Variáveis do console: ao lado dos logs, a lista das variáveis que a execução criou, com o valor de cada uma no momento. Ela se preenche conforme as tarefas terminam. Veja A aba Variáveis.

Cards, badges e conexões

Inserindo, movendo e excluindo etapas

Acessar Propriedades e Mapeamentos direto do card

Passe o mouse sobre qualquer card de etapa: a barra de ações que aparece no topo tem atalhos que abrem o painel lateral já na aba Propriedades ou já na aba Mapeamentos daquela etapa, sem precisar abrir o card e navegar pelas abas manualmente. Os outros ícones da mesma barra excluem a etapa, agrupam (veja Grupos de etapas) e, em etapas de Decisão, abrem o menu de rotas.

Inserir uma etapa entre duas já existentes

Para encaixar uma etapa no meio do fluxo sem refazer as conexões manualmente, passe o mouse sobre a linha de conexão entre duas etapas: um botão azul + aparece sobre a linha. Clique nele e escolha no grupo Fluxo do Processo o tipo (Criar Etapa de Execução, Criar Etapa de Decisão de Rota, Criar Etapa de Regra Customizada) ou o Clonar, ou no grupo Orquestração de Agentes uma etapa de agentes (Chamar Agente, Paralelizar Agentes, Aguardar Agentes, Criar Etapa Agêntica). A etapa é inserida ali, com as duas conexões já refeitas automaticamente.

Se a conexão estiver dentro de um ramo de decisão, a etapa nova nasce dentro daquele ramo, e não no fluxo principal.

Inserir uma etapa antes da primeira

A linha que sai do início do fluxo (o ponto verde) até a primeira etapa também tem o +, com o mesmo menu, inclusive o Clonar. A etapa criada por ele entra antes da primeira e passa a ser a primeira do fluxo. As demais etapas andam para a direita no canvas, na mesma ordem entre si.

Clonar uma etapa

Os dois menus do +, o do fim do fluxo e o da linha de conexão, trazem também a opção Clonar. Ela lista as etapas do fluxo; a escolhida é duplicada naquele ponto, com campos, mapeamentos, scripts e variáveis, sob o nome original seguido de "(cópia)". O clone nasce como uma etapa independente, com identidade própria: mexer nele não altera a original, e vice-versa. Se o ponto estiver dentro de um ramo, o clone entra naquele ramo. No + de uma rota nova, Clonar cria a primeira etapa da rota a partir da etapa escolhida.

Não aparecem na lista, porque não se clonam: as etapas ainda sem parametrização (as que mostram a chave de manutenção), as etapas de Decisão de Rota e as etapas de agentes (Chamar Agente, Paralelizar Agentes, Aguardar Agentes e Etapa Agêntica). Se a etapa original encerra o processo em Definir Rotas, o clone nasce sem essa regra: no meio do fluxo ele segue para a próxima etapa, e no fim do fluxo o processo termina ali de qualquer jeito.

Criar ou configurar uma etapa arrastando do painel

Os painéis Conectores e Agentes, na segunda fileira do cabeçalho, listam o que o processo pode usar, e cada item pode ser arrastado para o canvas. O que acontece depende de onde ele é solto: no Processo (em qualquer ponto fora das etapas de agentes) ou sobre o card de uma etapa de agente. As etapas de agentes são Chamar Agente, Paralelizar Agentes, Aguardar Agentes e Etapa Agêntica, as quatro do grupo Orquestração de Agentes do +.

Sobre o card de uma etapa de agente, o arrastar mostra o que vai acontecer: uma pílula acima do card diz a ação, e o card fica vermelho quando recusa o item.

Excluir uma etapa

Passe o mouse sobre o card e clique no ícone de lixeira 🗑, na barra de ações que aparece no topo da etapa. Uma confirmação pergunta se você tem certeza. Ao confirmar, a etapa é removida e o modelo é gravado na hora, sem depender de um clique em Salvar depois.

Para excluir várias de uma vez, selecione as etapas e aperte Delete. Uma única confirmação lista os nomes; ao confirmar, todas saem e o modelo é gravado na hora, como na lixeira. Com uma etapa só selecionada, vale a confirmação da lixeira. O Delete não age enquanto você digita, com uma janela aberta, enquanto o modelo está sendo salvo ou em somente leitura.

Mudar onde uma etapa roda

Arraste a etapa pela alça ⊕ (abaixo do card) e solte em cima de um +. Enquanto você arrasta, os + onde a etapa pode entrar crescem e se acendem, e o mais próximo do cursor fica preenchido. É a mesma regra do clique: clicar no + cria uma etapa ali, e soltar uma etapa em cima dele leva a etapa para ali. A ordem de execução passa a ser a do lugar onde você soltou.

• No fluxo principal ou dentro de uma rota: o + da seta entre duas etapas, o da seta que sai da decisão para a rota (a etapa vira a primeira da rota) ou o da seta que vai da última etapa da rota até a junção.
• Numa rota nova: os quadros tracejados rota A e rota B da decisão que ainda não tem rota, a linha tracejada até a junção quando a decisão tem uma rota só, ou o + tracejado ao lado da decisão, da terceira rota em diante.
• Para fora das rotas: o + logo depois da junção. A etapa passa a rodar depois da decisão, qualquer que seja a rota escolhida. Clicar nele cria uma etapa nova nesse mesmo lugar.
• No começo ou no fim: o + verde antes da primeira etapa, ou o + do fim do fluxo.

Soltar fora de um + só muda o desenho. Uma decisão arrastada leva as rotas junto, e os + de dentro dela não se acendem. Com várias etapas selecionadas (veja abaixo), o grupo vai junto, na ordem em que estava no fluxo. Com o zoom afastado os + somem da tela, mas aparecem durante o arraste. Ao soltar, só o trecho entre a origem e o destino se mexe: no destino o que vem depois anda para abrir a vaga, no lugar de onde a etapa saiu o que vinha depois volta para fechar o buraco, e o resto do desenho, inclusive o que você arrumou à mão, fica onde estava. A mudança fica pendente até você salvar, e o ↺ Reorganizar e Desfazer do cabeçalho volta tudo.

Empurrar o fluxo

Ao passar o mouse sobre um card, as setas ⇤ / ⇥ aparecem nos cantos de baixo. Elas empurram o fluxo: movem a etapa atual e todas as seguintes um passo para a esquerda ou para a direita, abrindo espaço no desenho. A ordem de execução não muda.

Selecionar várias etapas e movê-las juntas

Para reorganizar um trecho do fluxo de uma vez, selecione as etapas e arraste o grupo pela alça ⊕ de qualquer uma delas. Todas andam juntas e mantêm a distância que tinham entre si.

Grupos de etapas

Etapas relacionadas podem ser envolvidas em grupos, molduras nomeadas (ex.: CONTROLE DE PAGAMENTO, GUARDRAIL IA) que documentam visualmente o fluxo. Os grupos são organizacionais e não alteram a ordem de execução, que continua definida pelas conexões e rotas.

Para agrupar, passe o mouse sobre o card da etapa e clique no botão de grupo (ícone de moldura) na barra do card, então escolha um grupo existente ou + Novo grupo:

A mesma opção remove a etapa do grupo. Etapas do mesmo grupo ganham a moldura nomeada no canvas, e a moldura se ajusta automaticamente conforme os cards são movidos.

Copilot

O painel Copilot é o assistente de IA do builder: descreva em linguagem natural o que o agente deve fazer e ele explica, cria e ajusta etapas no fluxo, inclusive ramos de decisão e integrações. Com o runtime local conectado, o gravador de navegação também fica disponível. O detalhe completo de competências, convenções e limites está em Copilot.