Arquitetura em camadas

O desenho em uma frase

O painel roda como aplicação web publicada na nuvem; o estado (organizações, agentes, conversas, permissões) vive num banco de dados gerenciado; e o agente não roda no servidor do painel — roda dentro de um ambiente isolado por conversa, criado sob demanda, que fala com o painel por uma chamada autenticada.

Essa separação é a decisão estruturante do sistema: o código do produto e o código que o agente executa nunca compartilham processo.

As camadas

Fronteiras de confiança

1. Navegador → painel. Sessão do usuário, com a organização atual identificada e validada do lado do servidor a cada requisição.
2. Painel → banco. Todo dado pertence a uma organização, e a regra de acesso é aplicada no próprio banco — a autorização real não depende da tela.
3. Painel → ambiente de execução. O painel cria e conecta o ambiente isolado da conversa, escreve a configuração da execução e dispara o agente.
4. Ambiente de execução → painel. O caminho de volta é autenticado por um token de curta validade, gerado para aquela execução específica. O ambiente precisa de um endereço público do painel para conseguir chamar de volta.
5. Agente → terceiros. Nunca com credencial em texto: integração por conexão autorizada (OAuth) ou por cofre com referência opaca — o agente nunca vê o segredo em si.

O que roda onde

No servidor do painel: telas, rotas de API, as rotinas agendadas, a montagem do que o agente recebe para trabalhar (instruções, ferramentas, conhecimento, memória), a persistência do que o agente produz e as regras de acesso.

Dentro do ambiente de execução: o executor do agente, o navegador real que ele opera, as skills e as bases de conhecimento materializadas como arquivos, o repositório de trabalho quando existe, e a área de trabalho persistente da conversa.

Fora dos dois: o armazenamento de arquivos. A área de trabalho de uma conversa não é disco do ambiente de execução — é um espaço de armazenamento montado, isolado por organização e por conversa. Por isso o que o agente escreve lá sobrevive ao fim daquele ambiente; e por isso a escrita tem um pequeno atraso até ficar visível de volta.

Fluxo de dados de uma mensagem

1. Chega pelo canal de entrada (painel web, API, webhook, Telegram, WhatsApp ou gatilho agendado).
2. O conector normaliza a mensagem e entrega na conversa.
3. Uma guarda de concorrência evita processamento duplicado da mesma conversa.
4. O host monta a execução: instruções, ferramentas, skills, conhecimento e memória disponíveis.
5. O ambiente isolado (reconectado ou recém-criado) executa.
6. O fluxo de eventos volta ao host.
7. O host persiste mensagens e métricas; a tela recebe a atualização em tempo real.

Multi-tenancy em uma linha

A organização é a fronteira: todo recurso pertence a uma, e a regra de acesso do banco é quem decide o que cada pessoa vê.

Limites e modos de falha conhecidos

• O ambiente de execução tem um tempo de ociosidade limitado (padrão 30 minutos, configurável). Perdida a janela, a próxima execução começa do zero e o início fica mais lento.
• Se o endereço público de retorno estiver errado, a execução falha em silêncio do lado do ambiente isolado — as ferramentas não conseguem chamar o painel de volta.
• Mudança nas ferramentas embarcadas exige atualizar a imagem base do ambiente; sem isso o ambiente roda com uma versão antiga delas.
• O cache da área de trabalho montada é agressivo por design (12h de cache de diretório): escrita feita por fora dessa conversa não aparece dentro do ambiente na mesma janela.