Módulo Studio

Nesta funcionalidade é possível desenhar, depurar e publicar Robôs (a automação que uma Máquina executa) e Orquestrações (o encadeamento de Robôs já publicados) em uma interface visual.

A funcionalidade pode ser acessada através de: Aplicativo CITSmart X Studio. Para abrir o aplicativo a partir do código-fonte, execute npm run studio.

Tela do CITSmart X Studio com um Robô aberto

Vocabulário da tela

Na tela	O que é
Robô	A automação desenhada como uma árvore de passos. É o que se publica e versiona.
Orquestração	O grafo que encadeia Robôs publicados, com dependência, prazo e recurso.
Máquina	O computador em que um Robô executa, com o agente instalado.

O seletor Robô / Orquestração, na barra superior, alterna entre os dois editores.

Mapa da tela (modo Robô)

Área	Posição	Para que serve
Barra superior	Topo	Novo, Abrir, Desfazer, Refazer, nome e versão, Salvar, Depurar, Executar, Gravar web, Gravar desktop e Publicar.
Paleta Atividades	Esquerda	Lista as atividades por categoria, com busca.
Canvas	Centro	Árvore de passos do Robô.
Propriedades	Direita, primeira aba	Campos do passo selecionado.
Variaveis	Direita, segunda aba	Argumentos e variáveis do Robô.
Assistente	Direita, terceira aba	Pertence ao módulo de IA. Consulte IA.
Saida e Diagnosticos	Inferior	Log de execução e problemas encontrados no desenho.

Nota: A tela exibe alguns rótulos sem acento, como Variaveis, Saida e Diagnosticos. Esta documentação usa os rótulos exatamente como aparecem na tela.

As duas colunas laterais podem ser redimensionadas arrastando o divisor e recolhidas pelo botão de recolher (⟨ na paleta, ⟩ no painel direito). Recolhidas, aparecem como uma faixa vertical que, ao ser clicada, reabre a coluna.

Páginas

Entrar no Studio

Editor de Robôs

Paleta de atividades

Propriedades de um passo

Variáveis e expressões

Seletores e Element Spy

Gravador

Depurar e executar

Publicar um Robô

Editor de Orquestrações

Catálogo de atividades

Runner e linha de comando

Outros módulos

Painel de operação (servidor, filas, cofre e Máquinas): Orquestrador.

Assistente, provedores de IA e MCP: IA.

Importante: O Studio grava e publica no Orchestrator. Sem o servidor no ar, o desenho continua possível, mas salvar, abrir rascunhos, publicar e carregar o catálogo de atividades dependem dele.

Entrar no Studio

Nesta funcionalidade é possível identificar-se no Orchestrator antes de usar o Studio. A identidade é usada ao salvar rascunhos, publicar e ler o catálogo de atividades.

A funcionalidade pode ser acessada através de: Tela de entrada, exibida sempre que o Studio abre.

Tela de entrada do CITSmart X Studio

A tela exibe os campos conforme a configuração da instalação:

Elemento	Quando aparece
Orchestrator	Sempre. Endereço do servidor.
Botão de entrada pela conta da empresa	Quando a instalação tem provedor de identidade. O rótulo do botão é definido pela instalação.
Token de identidade e Entrar com token	Somente quando a instalação não tem provedor de identidade.
Aviso de instalação aberta e botão Continuar sem entrar	Quando a instalação não tem token nem identidade cadastrada.

Para entrar pela conta da empresa é necessário:

Conferir o endereço no campo Orchestrator.

Clicar no botão de entrada. Uma janela do servidor é aberta.

Autenticar-se na janela. Ao fechá-la sem entrar, nada é alterado.

Para entrar com token é necessário:

Conferir o endereço no campo Orchestrator.

Preencher Token de identidade. Se o ambiente já informou um token, o campo vem preenchido e o botão passa a se chamar Entrar com o token configurado.

Clicar em Entrar com token ou pressionar Enter.

Depois de entrar, a barra superior exibe o nome de quem entrou, o papel e o link sair.

Nota: O botão sair encerra a sessão no servidor, e não apenas no Studio.

Importante: Quando a instalação está aberta, qualquer pessoa com acesso à rede usa a API sem credencial. Configure identidades antes de usar a instalação em produção. A administração de identidades está em Orquestrador.

Editor de Robôs

Nesta funcionalidade é possível desenhar um Robô como uma árvore de passos. Cada passo é uma atividade; atividades de controle (como Se / Senao, Para cada item e Tentar / Capturar) contêm outros passos em blocos nomeados, como ENTAO e SENAO.

A funcionalidade pode ser acessada através de: Barra superior > Robô.

Canvas do editor de Robôs com um Robô aberto

A árvore de fluxo

O Robô não é um grafo de caixas ligadas por setas. É uma árvore: o passo raiz (normalmente Sequencia) contém os passos em ordem, de cima para baixo, e os blocos aninhados mostram o que acontece dentro de uma condição ou de um laço. A ordem visual é a ordem de execução.

Cada passo exibe o rótulo, o identificador da atividade (por exemplo core.if) e um resumo dos campos preenchidos. Durante a execução, o passo ganha estado, tempo gasto e, em caso de falha, o motivo.

Barra superior

Controle	Função
Robô / Orquestração	Alterna entre os editores. Consulte Editor de Orquestrações.
Novo	Cria um Robô vazio. Se houver alterações não salvas, pede confirmação.
Abrir…	Lista Rascunhos salvos e Robôs Publicados.
↶ / ↷	Desfazer e refazer.
Campo de nome	Nome do Robô.
Campo de versão	Versão do Robô, por exemplo 1.0.0.
Salvar	Grava o rascunho no servidor.
Identificador	Exibe rsc_... após salvar, ou não salvo. Clique para copiar. Um ponto (•) indica alterações pendentes.
Depurar, Executar	Consulte Depurar e executar.
Gravar web, Gravar desktop	Consulte Gravador.
Publicar	Consulte Publicar um Robô.

Para criar um Robô é necessário:

Clicar em Novo.

Preencher o nome e a versão nos campos da barra superior.

Arrastar atividades da paleta Atividades para o canvas. Consulte Paleta de atividades.

Clicar em um passo e preencher os campos na aba Propriedades. Consulte Propriedades de um passo.

Clicar em Salvar.

Para inserir um passo em um bloco é necessário:

Arrastar a atividade da paleta até a zona de soltura desejada. O bloco vazio exibe "arraste uma atividade aqui".

Soltar quando a zona estiver destacada. A posição entre dois passos também é uma zona de soltura.

Para reordenar passos é necessário:

Arrastar o passo para outra zona de soltura, inclusive para dentro de outro bloco; ou

Selecionar o passo e usar os botões ▲ e ▼ do cabeçalho, ou Alt+↑ e Alt+↓.

Ações em um passo

Os botões à direita do cabeçalho do passo são:

Botão	Ação
⬤	Adiciona ou remove breakpoint.
◉ / ○	Desativa ou ativa o passo. Um passo desativado permanece no desenho, mas não executa.
▲ / ▼	Move o passo dentro do bloco.
⧉	Duplica o passo.
✕	Exclui o passo.

O botão ▾ à esquerda do título recolhe o bloco. Recolhido, o bloco informa quantos passos escondeu e se há falha dentro.

Selos de aviso no passo

Selo	Significado
desconhecida	A atividade não está registrada neste Studio.
precisa de capacidade	A Máquina atual não tem a capacidade exigida (por exemplo, browser). É um aviso: publicado, o passo roda em uma Máquina que a tenha.
erro	O passo falhou na última execução. O motivo aparece abaixo do passo.
●	Breakpoint ativo.

Atalhos

Atalho	Ação
Ctrl+S	Salvar. Ctrl+Shift+S salva como um rascunho novo.
Ctrl+O	Foca a lista Abrir….
Ctrl+Z / Ctrl+Y	Desfazer e refazer.
F5	Executar. Shift+F5 depura.
Delete	Remove o passo selecionado.
Alt+↑ / Alt+↓	Move o passo selecionado.

Nota: Salvar grava no servidor, e não em arquivo. O rascunho recebe um identificador (rsc_...) que pode ser aberto de qualquer computador. Salvar não publica: a publicação é um ato separado.

Nota: Se o servidor estiver fora, o Studio guarda uma cópia local de recuperação. Ao reabrir, uma faixa Há trabalho não salvo oferece os botões Recuperar e Descartar. A cópia nunca é restaurada sozinha e sai quando o rascunho é salvo ou descartado.

Importante: Os grupos de Abrir… são diferentes. Abrir um Rascunho continua o trabalho; abrir um Publicado traz de volta algo que já está em uso. Confira o grupo antes de abrir.

Paleta de atividades

Nesta funcionalidade é possível localizar uma atividade e arrastá-la para o canvas, adicionando um passo ao Robô.

A funcionalidade pode ser acessada através de: Paleta à esquerda > Atividades.

Paleta de atividades com a categoria Controle expandida

O cabeçalho Atividades mostra a quantidade total de atividades disponíveis. Abaixo, a lista é agrupada por categoria; Controle vem sempre primeiro e as demais seguem em ordem alfabética. Cada categoria mostra a quantidade de atividades que contém, mesmo recolhida.

Para adicionar um passo é necessário:

Clicar no nome da categoria para expandi-la.

Arrastar a atividade até uma zona de soltura do canvas.

Soltar. O passo é criado e pode ser editado em Propriedades.

Para buscar uma atividade é necessário:

Digitar no campo Buscar atividade.... A busca ignora acentos e maiúsculas e considera nome, identificador, categoria e descrição.

Arrastar a atividade encontrada. Durante a busca, todas as categorias com resultado ficam expandidas.

Cada atividade exibe uma cor, o nome e, quando houver, selos:

Selo	Significado
priv	Atividade privilegiada. Exige allowlist na configuração do Robô (Máquina).
Nome de capacidade (por exemplo browser)	A Máquina precisa declarar essa capacidade para receber o Robô.

Passar o mouse sobre uma atividade mostra o identificador (por exemplo web.click) e a descrição.

Nota: O catálogo vem do Orchestrator. Se o servidor estiver fora, a paleta pode ficar sem atividades. Consulte Catálogo de atividades para uma visão por categoria.

Nota: Para ganhar espaço, recolha a paleta pelo botão ⟨. A faixa vertical ATIVIDADES reabre a coluna.

Propriedades de um passo

Nesta funcionalidade é possível configurar o passo selecionado no canvas: preencher os campos da atividade, escolher em quais variáveis gravar o resultado e definir o que fazer em caso de falha.

A funcionalidade pode ser acessada através de: Painel direito > Propriedades.

Painel Propriedades com um passo selecionado

Sem passo selecionado, o painel pede para selecionar um passo no fluxo. Se a atividade do passo não está registrada neste Studio, o painel avisa que o pacote correspondente precisa ser instalado.

Para editar um passo é necessário:

Clicar no cabeçalho do passo no canvas.

Preencher os campos na aba Propriedades.

Conferir a aba Diagnosticos do painel inferior para ver se algum campo foi recusado.

Seções do painel

Seção	Conteúdo
Componente	Nome da atividade, identificador (por exemplo web.click), categoria e descrição. Não é editável.
Rotulo no fluxo	Como o passo aparece no desenho. Vazio usa o nome da atividade.
Campos da atividade	Um campo por entrada da atividade. Campos obrigatórios têm asterisco (*).
Saidas	Para cada saída, o nome da variável que a recebe, em "gravar em qual variavel...".
Tratadores	Aparece apenas em atividades idempotentes. Campo Notificar quando este passo mudar.
Tratamento de erro	Se este passo falhar.
Anotacao	Texto livre: por que o passo existe e o que verificar quando falhar.
Identificador	Chave estável do passo, somente leitura. Aparece no log.

Marcas nos campos

Marca	Significado
fx	O campo inteiro é uma expressão, sem necessidade de {{ }}.
literal	O conteúdo chega intocado, sem interpolação.
segredo	Valor sensível, ocultado no log.

Conforme a atividade, o campo é uma caixa de texto, número, caixa de seleção, lista de opções, texto longo ou código, seletor de arquivo (botão ...) ou editor de seletor. Consulte Seletores e Element Spy.

Tratamento de erro

Em Se este passo falhar, escolha:

Opção	Efeito
Interromper o processo	Padrão. A falha interrompe o Robô.
Registrar e continuar	Registra a falha e segue. O campo Guardar a mensagem em recebe o nome de uma variável para guardar a mensagem de erro.
Tentar novamente	Repete o passo. Os campos Tentativas (padrão 3) e Espera inicial (ms) (padrão 1000) controlam a repetição; o intervalo dobra a cada tentativa.

Para tratar uma falha com mais controle, use as atividades de Controle Tentar / Capturar e Tentar novamente. Consulte Catálogo de atividades.

Nota: Campos de caminho têm o botão ... para escolher um arquivo. O campo também aceita expressão, como {{ pasta }}/arquivo.csv.

Importante: Campos obrigatórios vazios, valores fora das opções e expressões inválidas aparecem em Diagnosticos e impedem Executar e Publicar.

Variáveis e expressões

Nesta funcionalidade é possível declarar os argumentos (contrato de entrada e saída) e as variáveis do Robô, e usar seus valores nos campos dos passos por meio de expressões entre chaves duplas, como {{ total * 1.1 }}.

A funcionalidade pode ser acessada através de: Painel direito > Variaveis.

Aba Variaveis com argumentos e variáveis declarados

Argumentos e variáveis

A aba Variaveis tem duas seções.

Argumentos é o contrato do Robô com quem o chama. Cada linha tem nome, direção e tipo:

Direção	Significado
entrada	O valor chega de fora ao iniciar o Robô.
saida	O valor é devolvido a quem chamou.
ambos	Entra e sai.

Variaveis guarda valores de trabalho. Cada linha tem nome, tipo e valor inicial. Os tipos são string, number, boolean, date, array, object e any. Em array e object, o valor inicial é escrito como JSON.

Para declarar uma variável é necessário:

Abrir a aba Variaveis.

Clicar em + variavel.

Preencher o nome, escolher o tipo e informar o valor inicial.

Para declarar um argumento é necessário:

Abrir a aba Variaveis.

Clicar em + argumento.

Preencher o nome e escolher a direção e o tipo.

Para remover, clique em ✕ na linha. Durante a execução, cada variável declarada mostra o valor corrente abaixo da linha (a seta →).

Nota: Os nomes aceitam letras, dígitos e _, e não podem começar por dígito. Nomes repetidos entre argumentos e variáveis são erro. Nomes iguais aos de funções internas (como text, date, list) geram aviso, porque escondem a função.

Escopo

Argumentos e variáveis declarados na aba Variaveis valem para o Robô inteiro.

Se um passo grava uma saída em uma variável que não foi declarada, ela passa a existir apenas no bloco atual. O Studio avisa em Diagnosticos: declare a variável em Variaveis para usá-la depois.

Algumas atividades criam variáveis visíveis só dentro do seu bloco: Para cada item expõe item e index (os nomes são configuráveis), e Tentar / Capturar expõe error no bloco Capturar.

Um passo de dentro de um bloco enxerga as variáveis dos blocos de fora. Se houver nomes iguais, vale o mais interno.

Expressões

Qualquer campo de texto aceita expressões entre {{ e }}. Campos marcados com fx são inteiramente uma expressão e dispensam as chaves.

Exemplo	Resultado
Olá {{ cliente.nome }}	Texto com o valor interpolado.
{{ itens }}	Quando o campo é só uma expressão, o valor mantém o tipo (lista continua lista).
{{ total > 1000 ? 'Gerencial' : 'Automático' }}	Condicional.
{{ pedido?.cliente ?? 'sem cliente' }}	Encadeamento opcional e valor padrão.

Para escrever {{ literalmente, use \{{. Campos marcados com literal não passam por interpolação.

O que a linguagem aceita: números, textos, true, false, null; acesso a.b e a[0]; operadores + - * / % **, == != === !==, < > <= >=, && || ?? (também escritos and, or, not), !, in e o ternário ? :; listas [1, 2] e objetos { a: 1 }.

Não é aceito: atribuição, function, new, this e spread. Um passo não altera variáveis dentro de uma expressão; use a atividade Atribuir (core.assign).

Funções internas

Grupo	Funções
Raiz	len, isEmpty, isBlank, coalesce, toString, toNumber, toBoolean, isValidCPF, isValidCNPJ
text	upper, lower, trim, deaccent, digits, padLeft, padRight, split, replace, contains, startsWith, endsWith, slice, match, matchAll, test
num	parse (aceita 1.234,56 e 1,234.56), round, floor, ceil, abs, min, max, format, currency
date	now, today, parse (aceita dd/MM/yyyy), format, addDays, addMonths, diffDays, year, month, day, weekday, isBusinessDay
list	length, first, last, join, sum, avg, count, unique, sort, reverse, slice, where, pluck
obj	keys, values, has, get, merge
json	parse, stringify

Exemplos: {{ text.upper(nome) }}, {{ date.format(date.today(), 'dd/MM/yyyy') }}, {{ list.sum(list.pluck(itens, 'valor')) }}, {{ num.currency(total) }}.

Também estão disponíveis alguns métodos de texto, lista e número, como toUpperCase(), includes(), join() e toFixed().

Nota: Uma expressão com erro de sintaxe, função inexistente ou chamada a algo que não é função é erro em Diagnosticos e bloqueia Executar e Publicar. Uma variável não declarada é aviso, e o Studio sugere o nome mais parecido.

Importante: Segredos não devem ser digitados em campos nem em variáveis. Campos marcados com segredo são ocultados no log. Para credenciais, use o cofre, descrito em Orquestrador.

Seletores e Element Spy

Nesta funcionalidade é possível apontar para um elemento de uma página web ou de um aplicativo Windows e gerar o seletor que o Robô usará para encontrá-lo. O seletor não é um texto único: é uma lista ordenada de candidatos, e o Robô tenta um a um até um casar. O Element Spy é a captura feita pelo botão ⌖ Capturar.

A funcionalidade pode ser acessada através de: Painel direito > Propriedades > campo de seletor (por exemplo, Elemento) de uma atividade das categorias Web ou Desktop.

Partes do campo de seletor

Elemento	Função
Saúde (Forte, Razoavel, Fragil, Vazio)	Avaliação de robustez do seletor, com uma frase de orientação abaixo.
N candidatos	Quantidade de candidatos do seletor.
⌖ Capturar	Inicia o Element Spy.
▶ Testar	Valida o seletor contra a tela ao vivo.
URL para abrir ao capturar	Somente web. Endereço aberto no navegador de captura.
Candidatos, na ordem em que o robo tenta	Lista expansível dos candidatos.

Cada candidato mostra uma barra de confiança, a estratégia (css, xpath, text, role, testid ou uia para desktop) e o valor. Elementos dentro de um iframe exibem a linha "dentro de" com o caminho dos quadros.

Capturar na web

Para capturar um elemento web é necessário:

Adicionar uma atividade de Web, como Clicar em elemento.

No campo de seletor, preencher a URL e clicar em ⌖ Capturar. Um navegador é aberto.

Passar o mouse: o elemento sob o cursor é destacado.

Clicar no elemento para capturar. ESC cancela.

Expandir Candidatos, na ordem em que o robo tenta para conferir a lista.

Capturar no desktop

Para capturar um elemento de aplicativo Windows é necessário:

Abrir o aplicativo alvo.

Adicionar uma atividade de Desktop, como Clicar em elemento.

Clicar em ⌖ Capturar. O Studio é minimizado.

Clicar no elemento no aplicativo. ESC cancela.

O Studio volta com os candidatos gerados pela árvore de acessibilidade (UI Automation), como automationId, name, class e tipo de controle.

Nota: A captura e a gravação no desktop só funcionam no Windows.

Testar e ajustar

Para testar um seletor é necessário:

Clicar em ▶ Testar.

Ler o resultado: "Casou pelo candidato #N" ou "Nenhum candidato casou", com a lista dos tentados. Na lista, cada candidato recebe casou ou falhou.

Para ajustar os candidatos é necessário:

Expandir a lista de candidatos.

Usar ↑ e ↓ para reordenar e ✕ para remover.

Também é possível digitar um seletor manualmente (css, //xpath, text=..., role=...) no campo "Capture o elemento ou escreva um seletor".

Como o Studio ordena os candidatos

A confiança de cada candidato mede quanto ele sobrevive a mudanças no sistema alvo. Em ordem decrescente, na web: data-testid, id estável, papel com nome acessível, name de formulário, aria-label, placeholder, texto visível, classe semântica, caminho CSS e XPath absoluto. Identificadores que parecem gerados automaticamente (como :r1: ou sequências longas de dígitos) recebem confiança baixa. Candidatos que casam com mais de um elemento no momento da captura não entram.

Nota: Se o primeiro candidato falha e o segundo casa, o Studio sugere remover os anteriores, para o Robô não perder tempo tentando-os.

Importante: Um seletor com saúde Fragil costuma ser o primeiro a quebrar quando o sistema alvo muda. Prefira capturar novamente um elemento com identificador estável ou ajustar a ordem dos candidatos.

Gravador

Nesta funcionalidade é possível operar um sistema normalmente e transformar cliques, digitação e navegação em passos do Robô. Existem dois gravadores: Gravar web, que abre um navegador, e Gravar desktop, que acompanha um aplicativo Windows já aberto.

A funcionalidade pode ser acessada através de: Barra superior > Gravar web ou Barra superior > Gravar desktop.

Barra superior com os botões de gravação

Os botões ficam desabilitados enquanto um Robô está em execução.

Gravar web

Para gravar uma navegação web é necessário:

Clicar em Gravar web. A janela Gravar processo web é aberta.

Informar o Endereco inicial, por exemplo https://sistema.empresa.com.br. O endereço precisa começar com http.

Clicar em ● Iniciar gravacao. O navegador abre no endereço.

Operar o sistema normalmente. A janela do Studio mostra a lista de ações registradas, com o tipo e o rótulo de cada uma.

Voltar ao Studio e clicar em ■ Parar e inserir.

Gravar desktop

Para gravar a operação de um aplicativo Windows é necessário:

Deixar aberto o aplicativo que será operado.

Clicar em Gravar desktop. A janela Gravar processo no desktop é aberta.

Clicar em ● Iniciar gravacao. O Studio é minimizado.

Operar o aplicativo. Cada clique, campo preenchido e Enter ou tecla de função vira um passo.

Voltar ao Studio pela barra de tarefas ou por Alt+Tab e clicar em ■ Parar e inserir.

Resultado

Os passos entram no fim do bloco principal do Robô como rascunho, com rótulos legíveis e seletores com candidatos de reserva. Renomeie, parametrize e agrupe os passos antes de publicar.

Para descartar a gravação, clique em Descartar (durante a gravação) ou Fechar (antes de iniciar).

Nota: Campos de senha não são gravados. O gravador cria um passo de leitura do cofre no lugar do valor digitado. No desktop, o gravador lê o conteúdo do campo pela árvore de acessibilidade depois de você sair dele, e não registra as teclas digitadas.

Nota: Marcar uma caixa de seleção vira um passo, e não dois. No desktop, trocar de janela vira um passo Anexar a janela.

Nota: Se o Chromium empacotado não subir na máquina, o gravador web usa o Google Chrome ou o Microsoft Edge instalado e avisa na janela.

Importante: A gravação desktop só funciona no Windows. A gravação continua enquanto a janela de gravação estiver aberta.

Depurar e executar

Nesta funcionalidade é possível executar o Robô desenhado a partir do próprio Studio, pausar em breakpoints, avançar passo a passo, acompanhar o valor das variáveis e ler o log e os problemas do desenho.

A funcionalidade pode ser acessada através de: Barra superior > Executar ou Barra superior > Depurar, e Painel inferior > Saida / Diagnosticos.

Painel inferior com as abas Saida e Diagnosticos

Executar

Para executar um Robô é necessário:

Conferir que a aba Diagnosticos não tem erros. Com erro, o botão Executar fica desabilitado e a dica mostra a quantidade de erros.

Clicar em ▶ Executar ou pressionar F5.

Se o Robô tem argumento de entrada obrigatório sem valor inicial, informar o valor na janela exibida.

Acompanhar a execução no canvas e na aba Saida.

Durante a execução, o botão ▶ Executar é substituído por ■ Parar. Cada passo mostra seu estado: em execução, concluído, com falha (selo erro e o motivo abaixo do passo) ou desativado. Passos com mais de 10 ms mostram o tempo gasto.

Nota: O Studio executa o Robô na máquina em que está instalado. Atividades que dependem de capacidades que esta máquina não tem (por exemplo, browser ou windows) recebem o selo precisa de e, publicadas, rodam em uma Máquina que as tenha.

Depurar

Para depurar um Robô é necessário:

Clicar no botão ⬤ de um passo para adicionar um breakpoint. O passo exibe o marcador ●. Clicar novamente remove.

Clicar em ⏵ Depurar ou pressionar Shift+F5.

Quando a execução chegar ao breakpoint, ela pausa e a barra superior mostra ▶ Continuar e ⤼ Passo.

Consultar os valores das variáveis na aba Variaveis.

Clicar em ⤼ Passo para executar o passo seguinte e pausar de novo, ou em ▶ Continuar para seguir até o próximo breakpoint ou o fim.

Clicar em ■ Parar para encerrar.

Nota: Breakpoints só têm efeito com Depurar. Com Executar, eles são ignorados.

Saida

A aba Saida lista as mensagens da execução, cada uma com horário, nível (info, warn, error e outros) e texto. Clicar em uma linha seleciona o passo correspondente no canvas. O número ao lado do nome da aba é a quantidade de linhas, em vermelho quando há erro.

Controle	Função
⌫ (Limpar)	Apaga as linhas.
▼ / ▲	Recolhe ou expande o painel.
executando…	Indica que há uma execução em andamento.

O painel se expande sozinho ao iniciar uma execução. Se um passo falhou sem registrar nada no log, a aba informa que o motivo está escrito no próprio passo.

Diagnosticos

A aba Diagnosticos lista os problemas encontrados no desenho, atualizados enquanto você edita. Cada item mostra um ícone, a mensagem e o código, com o identificador do passo quando houver. Clicar no item seleciona o passo.

Ícone	Gravidade	Efeito
✕	Erro	Bloqueia Executar e Publicar.
!	Aviso	Não bloqueia. Exemplo: variável não declarada, ou capacidade ausente nesta máquina.
i	Informação	Não bloqueia. Exemplo: variável declarada e nunca utilizada.

Exemplos de erro: atividade que não existe, campo obrigatório vazio, valor fora das opções, expressão com sintaxe inválida, bloco obrigatório vazio, Interromper laco fora de um laço, identificadores duplicados.

Nota: Um Robô sem nenhum passo gera o aviso ROBO_VAZIO: publicado assim, ele roda, reporta sucesso e não faz nada.

Importante: O mesmo motor executa o Robô no Studio, na linha de comando e na Máquina. Consulte Runner e linha de comando. O acompanhamento das execuções em produção está em Orquestrador.

Publicar um Robô

Nesta funcionalidade é possível publicar o Robô no Orchestrator. A publicação cria uma versão imutável (identificador proc_...), que é o que as Máquinas executam. O rascunho continua editável e fica ligado às publicações feitas a partir dele.

A funcionalidade pode ser acessada através de: Barra superior > Publicar.

Janela Publicar no Orchestrator

O botão ⇧ Publicar fica desabilitado enquanto houver erro em Diagnosticos.

Para publicar um Robô é necessário:

Corrigir os erros da aba Diagnosticos.

Conferir o nome e a versão nos campos da barra superior. Para uma nova publicação, incremente a versão.

Clicar em Salvar, para que a publicação fique ligada ao rascunho.

Clicar em ⇧ Publicar. A janela Publicar no Orchestrator é aberta.

Conferir a linha de status. Conectado — N robo(s) disponivel(is) indica que o servidor respondeu. Se aparecer "Nao foi possivel falar com o Orchestrator neste endereco", o botão Publicar permanece desabilitado.

Conferir o endereço em Orchestrator (somente leitura) e o nome e a versão em Sera publicado.

Clicar em Publicar.

Ler o resultado: Publicado, com nome, versão, id e o início do hash; ou Falhou, com o motivo.

Nota: O endereço é o do servidor em que você entrou e não pode ser editado na janela. A sessão só vale para esse servidor.

Nota: Abrir um Robô na lista Abrir… > Publicados traz de volta uma versão já publicada, com seu nome e versão (por exemplo, Nota fiscal · v1.0.0).

Importante: Publicar duas vezes a mesma versão é recusado. Incremente a versão antes de publicar novamente.

Importante: A publicação recusa um Robô sem passos, porque ele rodaria, reportaria sucesso e não faria nada.

Depois de publicado, o Robô pode ser usado em uma Orquestração, disparado e agendado pelo painel descrito em Orquestrador.

Editor de Orquestrações

Nesta funcionalidade é possível encadear Robôs já publicados em um grafo: cada nó roda um Robô, e as ligações entre nós dizem quando cada um começa (depois de quem, e em que condição). Também é possível incluir aprovações humanas, marcos, prazo final e recursos compartilhados.

A funcionalidade pode ser acessada através de: Barra superior > Orquestração.

Editor de Orquestrações com a lista de Robôs publicados e o Inspetor

Diferentemente do Robô (uma árvore de passos), a Orquestração é um grafo. Cada nó é uma unidade que roda sozinha em uma Máquina; o desenho define a ordem e a paralelização.

Áreas da tela

Área	Função
Barra superior	Novo, Abrir…, Salvar, Duplicar salvo, desfazer, inclusão de nós, arranjo, zoom e Publicar.
Lista de Robôs (esquerda)	Robôs publicados, com campo de filtro. Arraste para a tela ou dê duplo clique para criar um nó.
Tela (centro)	O grafo, com minimapa.
Inspetor (direita)	Propriedades do nó selecionado ou da Orquestração. A aba Assistente pertence ao módulo de IA: consulte IA.
Rodapé da tela	Quantidade de nós e dependências, identificador do rascunho e dicas de navegação.
N ponto(s) a resolver	Lista, na coluna esquerda, de pendências do desenho. Clicar em um item seleciona o nó.

Barra superior

Botão	Função
Novo	Cria uma Orquestração vazia.
Abrir…	Lista Rascunhos e Orquestrações Publicadas.
Salvar	Grava o rascunho no servidor.
Duplicar salvo	Salva como um rascunho novo, com outro identificador.
↶ / ↷	Desfazer e refazer.
+ Nó	Adiciona um nó vazio do tipo Robô.
+ Aprovação	Adiciona um nó que para e espera uma pessoa decidir.
+ Marco	Adiciona um nó que não roda nada: junta caminhos e dá nome à etapa.
Duplicar / Remover	Atuam nos nós selecionados.
Arrumar	Refaz o arranjo automático.
Enquadrar	Ajusta o zoom para mostrar a Orquestração inteira.
− / +	Zoom.
Botão de conexão	Mostra quantos Robôs foram carregados, ou sem catálogo. Clique para ver e editar o endereço do Orchestrator e o Token, e use Reconectar.
Publicar	Publica a Orquestração.

Criar uma Orquestração

Para criar uma Orquestração é necessário:

Clicar em Orquestração no seletor da barra superior e em Novo.

Arrastar um Robô da lista da esquerda para a tela, ou dar duplo clique nele. Repetir para cada Robô.

Ligar os nós: puxar a alça da base de um nó até outro nó. O Studio apaga durante o arrasto os destinos inválidos (por exemplo, os que criariam um ciclo).

Selecionar cada nó e configurar o Inspetor.

Na aba Orquestração do Inspetor, informar o nome, a versão, a descrição e o prazo.

Conferir a lista N ponto(s) a resolver.

Clicar em Salvar e depois em Publicar.

Para navegar na tela: a roda do mouse rola, Ctrl+roda dá zoom, Espaço+arrastar (ou botão do meio) move a tela e arrastar o fundo seleciona vários nós. As setas movem os nós selecionados (Shift multiplica o passo). Ctrl+A seleciona todos, Ctrl+D duplica, Delete remove e Esc limpa a seleção.

Tipos de nó

Tipo	Uso
Robô	Roda um Robô publicado em uma Máquina.
Aprovação	Para e espera a decisão de uma pessoa.
Sub-orquestração	Roda outra Orquestração e espera o desfecho.
Marco	Não roda nada: junta caminhos e dá nome à etapa.

Inspetor, aba Nó

Seção	Campos
O que é	Nome na tela, Identificador (somente leitura), Tipo e, conforme o tipo, o Robô ou a Orquestração a rodar.
Argumentos	Valor de cada argumento declarado pelo Robô. Aceita expressões como {{ particao }} e a saída de um nó anterior, no formato {{ nos.<id do nó>.saida.campo }}.
Quando roda	Dependências do nó (uma por nó anterior), cada uma com uma condição: quando terminar bem, quando falhar, de qualquer jeito ou por código de saída (informe os códigos, como 0, 2, 3). Com mais de uma dependência, Combinação define se o nó espera TODAS (E) ou se basta UMA (OU).
Dependências externas	Espera um dado (dataset) com Partição, ou Espera outra orquestração com Vale execução de até (horas).
Recursos	O que o nó precisa deter para rodar (licença, trava, janela de sistema). Cada recurso tem quantidade e modo compartilhado ou exclusivo. Botão + recurso.
Comportamento	A falha deste nó não reprova a orquestração (nó acessório); Prioridade; Onde roda.

Sem dependências, o nó começa junto com a Orquestração. Para remover uma dependência, use remover na linha dela, ou remova a aresta na tela.

Onde roda

Opção	Efeito
Qualquer máquina	Qualquer Máquina da frota.
Um grupo de máquinas	Máquinas dos grupos informados em Grupos (por exemplo, financeiro, sp).
Uma máquina específica	A Máquina escolhida em Máquina.
A mesma máquina de outro nó	Herda a Máquina de um nó anterior (apenas nós dos quais este depende). Útil quando o passo depende de arquivos deixados no disco.
A máquina de uma pessoa (Client)	Execução atendida na Máquina de quem autorizar.

Quando o nó fixa a Máquina, aparecem Esperar no máximo (min) e Se ela não aparecer (Falhar o nó ou Cair para o grupo).

Nota: Cair para o grupo serve para trabalho que roda em qualquer lugar. Para trabalho preso a uma tela, ele poderia terminar com sucesso na Máquina errada.

Nó de Aprovação

Campo	Função
O que a pessoa vê	Título da tarefa.
Instruções	Texto de apoio.
Prazo (minutos)	Vencido o prazo, o nó falha em vez de esperar para sempre.
Respostas possíveis	Cada resposta tem um rótulo e um desfecho: segue o caminho de sucesso ou segue o caminho de falha. Botão + resposta.

Inspetor, aba Orquestração

Seção	Campos
A orquestração	Nome, Versão e Descrição.
Prazo	Precisa terminar até (horário) e, preenchido, Avisar com quantos minutos de folga.
Resumo	Quantidade de nós, dependências e nós sem dependência.

Pendências do desenho

A lista N ponto(s) a resolver aponta, entre outros: nó Robô sem Robô escolhido, Robô que não está publicado, Sub-orquestração sem alvo, aprovação sem título ou sem respostas possíveis, recurso sem nome (graves) e nó sem ligação com os demais, quando a Orquestração tem mais de dois nós (aviso).

Nota: O catálogo de Robôs, recursos, datasets e Máquinas vem do Orchestrator. Sem ele é possível desenhar, mas publicar e abrir do servidor dependem do catálogo.

Nota: Como no editor de Robôs, se o servidor estiver fora o Studio guarda uma cópia local de recuperação e oferece Recuperar ou Descartar na próxima abertura.

Importante: Publicar uma Orquestração cria uma versão para o Orchestrator. Se a publicação devolver avisos, eles aparecem na mensagem após o clique em Publicar. A operação das Orquestrações (execução, gatilhos, agenda e falhas) está em Orquestrador.

Catálogo de atividades

Nesta funcionalidade é possível conhecer as categorias de atividades disponíveis para montar um Robô e saber onde consultar os campos, as saídas e os blocos de cada uma.

A funcionalidade pode ser acessada através de: Paleta à esquerda > Atividades.

Paleta de atividades com as categorias

O catálogo de referência é o arquivo docs/ACTIVITIES.md, gerado automaticamente a partir do esquema das atividades (o mesmo que alimenta a paleta). Ele lista cada atividade com identificador, descrição, entradas, saídas e blocos. Na versão atual, são 201 atividades em 28 categorias. Para regenerá-lo, execute npm run catalog.

Nota: O número exibido no cabeçalho Atividades da paleta é o total de atividades registradas no ambiente e pode diferir do arquivo gerado se houver pacotes adicionais instalados.

Categorias

Grupo	Categorias (quantidade de atividades)	Para que servem
Fluxo	Controle (19)	Estrutura do Robô: Sequencia, Se / Senao, Escolha (Switch), Para cada item, Enquanto, Repetir ate, Em paralelo, Tentar / Capturar, Tentar novamente, Atribuir, Registrar mensagem, Aguardar, Chamar processo, Encerrar processo, Lancar erro, entre outras.
Fluxo	Script (3), Orquestracao (5), Humano (1)	Código embutido (Python, PowerShell, JavaScript); filas e assets do Orchestrator; pedido de decisão a uma pessoa.
Interface	Web (14)	Navegador: abrir, navegar, clicar, digitar, ler texto, extrair tabela, capturar tela.
Interface	Desktop (14)	Aplicativos Windows: abrir, anexar janela, clicar, preencher, ler, achar imagem na tela. Só no Windows.
Interface	Terminal 3270 (9)	Mainframe: conectar, ler tela e região, digitar em campo, enviar tecla, aguardar texto.
Dados e arquivos	Arquivos (12), Dados (8), Texto (7), Banco de dados (3)	Operações com arquivos e transferência (SFTP), leitura e gravação de CSV e Excel, tratamento de texto, consultas e cargas em banco.
Dados e arquivos	Documentos (9), HTTP (2), E-mail (2)	Leitura, OCR, classificação e extração de campos de documentos; chamadas e downloads HTTP; envio e leitura de e-mails.
IA	IA (4)	Perguntas a modelos e chamadas de ferramentas MCP. Consulte IA.
Nuvem	AWS (8), Azure (8), Google Cloud (8), OCI (8)	Armazenamento, segredos, chamadas de API e controle de máquinas virtuais em cada nuvem.
Infraestrutura e TI	Infraestrutura de TI (12), Active Directory (8), Keycloak (10), Kubernetes (8), Zabbix (11), ServiceNow (3)	Automação de servidores e contas, identidade, clusters, monitoramento e ITSM.
Sistemas corporativos	SAP (2), Salesforce (2), Protheus (1)	Conectores para sistemas corporativos.

Como ler uma atividade

Em docs/ACTIVITIES.md, cada atividade traz as mesmas marcas exibidas no painel Propriedades:

Marca	Significado
*	Campo obrigatório.
fx	O campo inteiro é uma expressão.
literal	O conteúdo chega sem interpolação.
segredo	Valor sensível, ocultado no log.
privilegiada	Sujeita a allowlist na configuração da Máquina.
requer	Capacidade que a Máquina precisa declarar para receber o Robô (por exemplo, browser).

Atividades com Blocos (como then e else em Se / Senao) abrem zonas de soltura dentro do passo no canvas.

Nota: Para listar as atividades no terminal, use npm run runner -- atividades, com --categoria <nome> para filtrar. Consulte Runner e linha de comando.

Importante: Atividades marcadas como privilegiada só funcionam em uma Máquina cuja configuração as permita. Atividades que exigem capacidade (por exemplo, navegador ou interface Windows) só rodam em Máquinas que a declarem.

Runner e linha de comando

Nesta funcionalidade é possível executar e validar um Robô sem abrir o Studio, usando o Runner, o motor de execução. O Studio, a linha de comando e a Máquina usam o mesmo motor, então um Robô se comporta igual nos três.

A funcionalidade pode ser acessada através de: Terminal, na pasta do projeto: npm run runner -- <comando>.

Os Robôs são arquivos .nexo.json, e os exemplos do projeto ficam em examples/.

Executar um Robô

Para executar um Robô pelo terminal é necessário:

Abrir um terminal na pasta do projeto.

Executar, por exemplo: npm run runner -- executar examples/01-hello-world.nexo.json --arg nome=Maria

Acompanhar a árvore de execução, o log ao vivo e o resultado final (Successful ou o erro, com o código).

Opções do comando executar:

Opção	Efeito
--arg nome=valor	Argumento de entrada. Pode ser repetida e aceita JSON (por exemplo, --arg itens='[1,2,3]').
--conferir	Calcula o que mudaria e não aplica. Para atividades de infraestrutura.
--depurar	Ativa breakpoints e passo a passo.
--json	Emite os eventos como JSON em linhas.
--log <nivel>	trace, debug, info, warn ou error.
--saida <arquivo>	Grava o resultado do job em JSON.
--pasta <pasta>	Pasta de artefatos do job.
--orquestrador <url> e --token <token>	Usa o Orchestrator para assets e filas.

O código de saída é 0 quando o Robô termina com sucesso, 1 quando falha e 2 quando o comando é usado incorretamente. Ctrl+C pede a parada do job; pressionar de novo força o encerramento.

Validar sem executar

Para validar um Robô é necessário:

Executar npm run runner -- validar examples/03-fila-notas-fiscais.nexo.json.

Ler o resumo (quantidade de passos e profundidade) e a lista de problemas, os mesmos exibidos em Diagnosticos no Studio.

Conferir a última linha: Documento valido. ou a quantidade de erros que impedem a execução.

Listar atividades

Execute npm run runner -- atividades para listar as atividades por categoria, ou npm run runner -- atividades --categoria Terminal para filtrar. A opção --json emite o esquema completo.

Outros comandos

Comando	Para que serve
fila adicionar <fila> '<json>'	Enfileira um item de trabalho. Opções --ref (chave de negócio) e --prioridade.
chaves nova e assinar <arquivo>	Gera uma chave e assina um pacote de Robô para publicação por script.
orquestracao <sub>	Orquestração como código: validar, comparar, aplicar e puxar.
maquina	Registro e execução do agente em uma Máquina. Consulte Orquestrador.
ajuda	Mostra todos os comandos.

Nota: Os nomes antigos dos comandos (por exemplo, run, validate, agent e plan) continuam aceitos, para não quebrar tarefas agendadas e scripts existentes.

Nota: Sem --orquestrador, filas e assets usam o armazenamento local do Runner (pasta .nexo-data). Apagar a pasta zera esse estado.

Importante: Atividades que dependem de capacidades que o computador não tem (por exemplo, browser ou windows) falham na execução local. Para esses casos, publique o Robô e execute em uma Máquina que as declare. Consulte Publicar um Robô.