Ambiente Sandbox
Ambiente de teste compartilhado, mantido pela plataforma e disponível para todas as contas. Permite executar o Debug de um agente sem baixar, instalar ou configurar nada.
O que é o Ambiente Sandbox
A Sandbox é um ambiente de execução mantido pela plataforma e compartilhado por todas as contas. Ela existe para que você consiga rodar o Debug de um agente imediatamente, sem precisar cadastrar um ambiente, baixar o pacote do runtime, editar arquivo de configuração ou dispor de uma máquina ligada.
A Sandbox não substitui o seu Ambiente Runtime. Ela executa apenas Debug, com um conjunto reduzido de recursos, e nunca executa produção. Para colocar um agente em operação você continua precisando de um runtime próprio, conforme descrito em Ambientes Runtime.
Quando usar
A Sandbox atende bem os seguintes casos:
- Conhecer a plataforma e executar um primeiro agente antes de preparar qualquer máquina
- Validar a navegação de um agente, os seletores mapeados e a sequência de etapas
- Testar a chegada de um webhook e ver o agente rodar com o payload recebido
- Reproduzir um comportamento rapidamente quando o seu runtime está indisponível
- Testar um agente compartilhado com você, cujo ambiente pertence ao dono e não é seu para trocar
Não atende os seguintes casos, que exigem runtime próprio:
- Agentes que usam credenciais do Cofre de Senhas
- Agentes que dependem de projeto de script enviado
- Agentes que acessam sistemas em rede interna da empresa
- Qualquer execução de produção, agendada ou disparada por API
Como selecionar
No Agent Builder, abra o campo AMBIENTE, na segunda fileira do cabeçalho. A Sandbox fica no fim da lista, num grupo separado dos ambientes cadastrados na sua conta e identificado pelo aviso "Este ambiente é limitado e para testes".
A seleção da Sandbox tem um comportamento diferente da seleção de um ambiente próprio:
| Comportamento | Ambiente próprio | Sandbox |
|---|---|---|
| É gravado no cadastro do agente | Sim, passa a valer imediatamente para produção | Não. A escolha vale apenas para os Debugs desta aba do navegador |
| Afeta agendamentos e API | Sim | Não |
| Sobrevive ao fechamento da aba | Sim | Não. Ao reabrir o agente, o campo volta ao ambiente cadastrado |
O que a Sandbox não comporta
A Sandbox é compartilhada entre contas diferentes. Por esse motivo, recursos que envolvem credenciais ou acesso privilegiado ficam restritos. A lista a seguir é completa.
Há dois níveis. Indisponível impede a execução de começar, porque o resultado seria errado ou a etapa quebraria. Não executa deixa a execução seguir normalmente: apenas aquele recurso não acontece.
| Recurso | Situação | Motivo |
|---|---|---|
| Cofre de Senhas | Indisponível | Credenciais decifradas nunca são enviadas para uma máquina compartilhada. Vale para as duas formas de pedir uma credencial: {vault.CHAVE} em qualquer campo e bm.secret() dentro de um script |
| Conectores com credencial | Indisponível | Qualquer conector que armazene senha, token ou chave é recusado. Conectores que não guardam credencial continuam funcionando |
| Conectores Google | Indisponível | Planilhas, Drive, Gmail, Agenda, BigQuery e Analytics usam a identidade de serviço da plataforma, que não é cedida ao ambiente compartilhado |
| Resolução de Captcha | Não executa | Serviço externo cobrado por resolução. A execução continua, e só falha se o agente realmente encontrar um captcha na página |
| Projeto de script enviado | Indisponível | Projetos Node.js e Python enviados pela tela de código não são distribuídos para o ambiente compartilhado. Código escrito direto na etapa continua funcionando, conforme a seção Execução de scripts |
| Notificações automáticas | Não executa | O envio configurado no cadastro do agente não sai da Sandbox. A execução continua normalmente sem ele |
| OCR e ICR | Indisponível | Depende da identidade de serviço da plataforma |
| Download de arquivo | Indisponível | A Sandbox é ambiente efêmero e compartilhado entre contas diferentes; o arquivo baixado não deve virar resultado de teste. Etapa Preencher com Esse mapeamento dispara download? ligado é recusada. Veja Download |
| Navegador customizado | Indisponível | Os modos que apontam para um executável próprio na máquina não são aceitos. Use o navegador nativo, que é o padrão. Um caminho antigo que tenha sobrado no cadastro não atrapalha, porque no modo nativo ele é ignorado |
| Automação de desktop | Indisponível | Depende de execução de código e de acesso à área de trabalho da máquina |
| Rede interna | Indisponível | A Sandbox alcança apenas a internet pública. Sistemas acessíveis somente pela rede da sua empresa não respondem |
| Leitura de arquivo local | Indisponível | Um caminho de arquivo digitado no agente (ex.: Objeto de Tela Upload de Arquivo) aponta para a máquina de quem desenhou o processo, que não existe dentro da Sandbox. Caminhos fixos configurados no agente não são respeitados |
Como o bloqueio é comunicado
Antes de abrir o navegador, a plataforma verifica o agente e identifica quais recursos restritos ele utiliza. Quando encontra algum indisponível, a execução é interrompida e o console de Debug recebe uma única mensagem informando todos eles de uma vez:
🚨 O ambiente Sandbox não comporta: Cofre de Senhas, Resolução de Captcha.
Quando encontra apenas recursos do tipo não executa, a execução começa normalmente e o console recebe um aviso listando o que não vai acontecer.
A verificação acontece no início, de modo que você não perde tempo esperando o agente falhar em uma etapa avançada. Se algum recurso indisponível escapar dessa verificação inicial, a etapa que tentar usar o recurso falha com a mesma mensagem, indicando qual recurso estava envolvido.
Execução de scripts
Código Node.js e Python escrito direto na etapa executa normalmente na Sandbox, incluindo scripts de sessão. Bibliotecas externas declaradas no código são instaladas sob demanda.
O script roda em um ambiente restrito. As permissões concedidas a ele são as seguintes:
| Recurso | Permissão |
|---|---|
| Diretório temporário da própria execução | Leitura e escrita |
| Arquivos de outras execuções em andamento | Sem acesso |
| Arquivos e configurações da máquina | Sem acesso |
| Processos de outras execuções | Sem acesso |
| Internet pública | Liberada, inclusive para instalar bibliotecas |
| Rede interna de qualquer empresa | Sem acesso |
Uma tentativa de acessar algo fora dessas permissões resulta em erro do sistema operacional, que aparece no console como falha da etapa. O ambiente inteiro é descartado ao fim da execução, então nada escrito pelo script permanece.
Publicação bloqueada
Não é possível publicar uma versão tendo apenas a Sandbox. A publicação exige que o agente tenha um Ambiente Runtime cadastrado no campo AMBIENTE, e a Sandbox não ocupa esse campo.
Na prática, o agente que só usou a Sandbox permanece com a pendência de ambiente em aberto. O ícone de pendências continua sinalizado e o botão de publicar não é oferecido. Ao abrir o painel de pendências, o item de ambiente informa que a Sandbox não publica.
Para publicar, cadastre um Ambiente Runtime em Meus Ambientes, escolha esse ambiente no campo AMBIENTE do agente e conclua as demais pendências.
Onde a Sandbox não aparece
A Sandbox é ofertada apenas no Debug do Agent Builder. Ela não é oferecida como opção nos seguintes lugares:
| Local | Comportamento |
|---|---|
| Agendamento | O seletor de runtime do agendamento lista apenas ambientes próprios e ambientes públicos da empresa |
| Rotas de API | A Sandbox não possui identificador de ambiente e não pode ser informada como destino de execução |
| Webhook de produção | Roda sempre no ambiente cadastrado do agente |
| Meus Ambientes | A Sandbox não é um ambiente da sua conta e não aparece na listagem nem conta no limite de ambientes do plano |
| Agente sem versão em desenvolvimento | Quando o agente está fechado, o editor abre em modo de leitura sobre a versão publicada. Nesse estado o campo AMBIENTE altera diretamente o ambiente de produção, então a opção Sandbox não é exibida |
Limites de uso
A capacidade da Sandbox é compartilhada por toda a base de usuários. Para manter o ambiente disponível para todos, valem os seguintes limites:
| Limite | Comportamento |
|---|---|
| Execuções simultâneas na plataforma | Há um número máximo de Debugs rodando ao mesmo tempo. Quando todas as vagas estão ocupadas, a execução é recusada com aviso na tela e você pode tentar novamente em seguida |
| Execuções simultâneas por usuário | Um Debug por vez. Encerre o Debug em andamento para iniciar outro |
| Duração máxima | Execuções longas são encerradas automaticamente. O console recebe uma mensagem informando o motivo |
| Sessão ociosa | Um Debug que fica muito tempo sem registrar atividade é encerrado para liberar a vaga |
| Timeouts do agente | O limite de duração da Sandbox prevalece sobre os timeouts configurados no agente, inclusive sobre o valor zero, que no seu runtime significa sem limite |
Logs, evidências e histórico
O comportamento do console de Debug na Sandbox é idêntico ao do seu runtime:
- As linhas do console e as imagens da tela chegam em tempo real enquanto a execução acontece
- O log de Debug não é armazenado. Ele existe na tela durante a sessão e é apagado quando um novo Debug começa
- Recarregar a página durante o Debug limpa o console. A execução continua, mas as linhas já exibidas não são recuperadas
- Evidências em PDF capturadas durante o Debug ficam disponíveis normalmente e são substituídas a cada nova execução
- O Dado sensível segue as mesmas regras do seu runtime: valores marcados aparecem como
«•••»no console e nenhuma imagem da tela é gerada enquanto houver dado sensível em uso - Execuções de Debug não aparecem na Trilha de Auditoria nem nos Dashboards, que registram apenas produção
Teste de webhook
O teste de webhook em desenvolvimento funciona normalmente com a Sandbox selecionada.
O sistema externo chama a URL de desenvolvimento, a plataforma captura o conteúdo recebido e exibe no painel de webhook do agente. Ao confirmar Iniciar debug com esta captura, o agente roda na Sandbox já com as variáveis preenchidas pelo mapeamento. Nenhuma configuração adicional é necessária.
Sandbox e Ambiente Runtime
| Característica | Sandbox | Ambiente Runtime |
|---|---|---|
| Instalação | Nenhuma | Baixar o pacote e configurar a chave de ativação |
| Disponibilidade | Todos os planos | Limitado pelo plano contratado |
| Debug | Sim, com restrições | Sim, completo |
| Produção | Não | Sim |
| Agendamento e API | Não | Sim |
| Publicar versão | Não | Sim |
| Cofre e conectores com credencial | Não | Sim |
| Código Python e Node.js na etapa | Sim, em ambiente restrito | Sim, sem restrição |
| Projeto de script enviado | Não | Sim |
| Rede interna da empresa | Não | Sim |
| Execuções simultâneas | Uma por usuário, sujeita a fila | Conforme a capacidade da sua máquina |
| Máquina | Compartilhada entre contas | Exclusiva da sua empresa |
Boas práticas
- Use a Sandbox para validar navegação. Ela é adequada para conferir seletores, sequência de etapas e comportamento das rotas
- Monte o agente em duas fases. Valide a navegação na Sandbox e deixe as etapas que dependem de credencial para o momento em que o runtime próprio estiver disponível
- Encerre o Debug ao terminar. A vaga é liberada imediatamente e fica disponível para outros usuários
- Cadastre o runtime antes de precisar publicar. A publicação depende dele, e deixar isso para o final atrasa a entrada em produção
- Não use a Sandbox para medir desempenho. A capacidade é compartilhada, então tempos de execução não representam o que o agente fará no seu ambiente