Camadas de permissão (stLayer)

O Sequential Thinking reutiliza um único motor; o comportamento visível muda com quem invoca a API. Em termos técnicos, a camada (stLayer) é derivada do contexto de autenticação e identidade (claims do token, resolução de host / domínio, tipo de sessão) — não do texto da instrução. Cada camada define o que pode ser visto, o repertório de ações e como a resposta final é composta.

​

Relação com a API pública

• runWithAgents é o endpoint de produção com ações reais. Exige Authorization: Bearer. Em produção, o hostId vem do header X-Host-Id (injetado pelo KrakenD); o gateway também injeta X-Domain-Id quando aplicável. Em ambiente local, hostId (ou hostSlug) pode ir no body quando os headers do gateway não existem.
• O bloco conversational (com conversationId, avatarId, etc.) controla persistência na conversa e aplicação do prompt_envelop do avatar na resposta. Isto não substitui a definição da camada: um token de gestão (Host / Tenant) pode, em tese, incluir conversational para escrever na conversa, sem ser “Conversational” no sentido de utilizador final.
• listActions e run são públicas e sem autenticação (validação e sandbox). Aí o modelo de confiança e de camada não replica o de runWithAgents em produção; use as páginas desses endpoints para o comportamento concreto.

​

As quatro camadas

Da mais ampla à mais restrita:

Isolamento por desenho: outro gestor não acede aos dados de um host cujo token não lhe dá escopo, mesmo com o mesmo motor de IA.

​

O que varia por camada

​

Escopo de dados

• Admin: todos os dados (uso interno)
• Tenant: apenas dados dos hosts desse tenant
• Host: apenas dados desse host
• Conversational: a conversa em curso, desse utilizador final, nesse host

​

Repertório de ações

No motor, as ações do catálogo estão classificadas com as stLayer em que podem entrar no plano. O GET /listActions expõe a definição do catálogo; a filtragem ao subset permitido na camada corrente ocorre na preparação e no planejamento (pré-filtro de ações, etc.). O integrador não define stLayer no corpo do pedido; isso resulta do contexto de autenticação, não de um parâmetro explícito.

• Admin / Tenant / Host: acesso ao subconjunto adequado a gestão, configuração e operações de dados nesse âmbito (global, domínio ou host).
• Conversational: apenas o subconjunto seguro para conversa; pedidos em linguagem natural a ações administrativas não entram no plano porque a ação não está entre as permitidas nessa camada.

​

Estilo de resposta

• Admin / Tenant / Host: respostas ferramentais, orientadas a tarefa; em geral sem envelope de avatar conversacional.
• Conversational: modo conversacional, com a camada extra de personagem e tom de marca. Na API, o conversational.avatarId no body de runWithAgents aplica o prompt_envelop do avatar na composição da resposta final (ver Executar com agentes).

​

Como a camada é determinada

A camada não é um campo que o integrador preenche no body. É obtida a partir do contexto de autenticação e identidade (e, no gateway, dos headers de âmbito). A instrução em linguagem natural não promove a camada: não dá, por si, acesso de Admin ou de outro host.

Ter conversationId (por exemplo no bloco conversational de runWithAgents) não define sozinho a camada: indica onde escrever e compor, não quem é o chamador (ver Relação com a API pública no início desta página).

​

Garantias de isolamento (resumo)

O documento técnico ST_LAYERS_SURVEY.md descreve as invariantes em pormenor. Abaixo ficam as linhas gerais, alinhadas ao que a documentação de produto costuma resumir:

1. Consultas a dados filtram por host (ou pela lista de hosts do tenant, conforme a credencial); dados de outro cliente não entram no resultado.
2. Identidade do host (e, quando relevante, do domínio) é resolvida antes de planear e executar passos com efeitos; sem isso, o motor não segue com operações que toquem dados.
3. Conversas e leads estão amarrados ao host correto; ações que referenciam uma conversa revalidam que ela pertence ao mesmo âmbito do token / headers.
4. Efeitos colaterais (criar lead, atualizar conversa, campanhas, etc.) só ocorrem com host e conversa coerentes com o contexto de segurança da chamada.
5. O canal de voz segue as mesmas regras de escopo e planejamento que o texto: não é um caminho com menos validação.
6. Áudio e transcrições persistem com o mesmo modelo de escopo que as mensagens de texto, quando a stack os grava.

​

Perguntas frequentes

O utilizador final pode obter dados de outro host só reformulando o pedido?
Não. A camada vem da credencial; ações fora do escopo nem chegam ao planeador.

Um gestor de um host vê outro host no mesmo tenant?
Apenas se a credencial for de Tenant (e o tenant agrupar esses hosts). Um token Host restringe a esse host.

O motor é partilhado; um bug afeta todos?
O mesmo binário reutiliza-se, o que concentra correções de segurança. As regras de escopo aplicam-se em várias fases (credencial, planejamento, execução, persistência), o que reduz o risco de um único ponto falhar em silêncio.

Voz e WhatsApp têm o mesmo isolamento?
Sim. As mesmas regras aplicam-se a texto, voz e WhatsApp.

​

Glossário

• Host — marca, empresa ou unidade (uma “instância” cliente)
• Tenant — agrupamento de hosts sob a mesma operação (ex.: rede com várias marcas)
• Avatar — persona do canal conversacional de um host
• stLayer — camada de privilégio da chamada: Admin, Tenant, Host ou Conversational
• Repertório — conjunto de ações que o motor pode planear e executar naquela camada