Modes e performance
Presets de pipeline (mode), otimização (performanceMode) e clusters de ações feature-flagged — ortogonais à camada stLayer
O Sequential Thinking expõe dois eixos ortogonais além da camada de permissão stLayer:
| Eixo | Campo | Controla |
|---|---|---|
| Privilégio | stLayer (derivado do token) | Escopo de dados, catálogo permitido por camada, persona conversacional |
| Pipeline | options.mode ou modeInput | Quais chapters rodam, subset de ações, plano pré-construído, guidance de domínio |
Confundir os dois eixos é erro comum: um token Host pode usar mode: 'lean'; uma sessão Conversational pode usar pipeline completo (sem mode).
stLayer e mode são server-derived nos produtos Tolky (webchat, backoffice). Integradores externos via runWithAgents podem passar modeInput.mode quando o contrato do produto permitir — valores fora da whitelist são ignorados ou rejeitados conforme o caller.
options.mode — presets de pipeline
Um mode restringe ou especializa o motor antes da fase PREPARATION:
- Subset de ações — ex.: copilot de ticket vê só ações de tickets/leads.
- Constraints e guidance — regras SQL, primers de domínio, políticas de área.
- Opções de execução —
maxSteps, timeouts, flags de performance embutidas. - Plano pré-construído —
prebuiltPlandeterminístico (sem Planner LLM).
Modes built-in (referência)
| Mode | Uso típico |
|---|---|
| (ausente) | Pipeline completo — Planner + Executor + DeliveryComparator + Compile |
lean | Resposta rápida em 1 chamada LLM (bypass de Planner/Executor). Webchat anônimo. |
canvas | Integração com UI dinâmica /canvas — ações pushCanvasEntry, mountCanvasFrame, etc. |
workflowBuilder | Edição de grafos de workflow (addWorkflowNode, connectWorkflowNodes, …) |
advisor_decision | Auditoria Advisor V4 com plano fixo de tracers |
Como ativar via API
Passe modeInput no body de runWithAgents (ou screenTags legado):
{
"instructions": "Atualize o ticket 12345678 com prioridade alta",
"modeInput": {
"mode": "copilot_ticket",
"screen": "ticket_detail",
"entityIds": { "ticketId": "uuid-do-ticket" }
}
}
Quando modeInput.mode está presente, o backend resolve bindings de tela (screenBindings) e injeta registry/opções antes do pipeline.
Parâmetros relacionados:
| Campo | Descrição |
|---|---|
modeInput.mode | ID estável do mode (slug) |
modeInput.screen | Tela/contexto de UI para resolução automática quando mode omitido |
modeInput.entityIds | IDs de entidade exigidos pelo mode (ticket, lead, conversa, …) |
canvasSessionId | Sessão de canvas para fan-out de comandos UI (requer coerência com hostId) |
sessionId | Correlação WebSocket / sequentialKeeper |
options.performanceMode — presets de custo/latência
Atalho para ligar/desligar gates LLM caros. Valores: balanced (padrão), fast, turbo. Flags explícitas no mesmo options sempre vencem o preset.
| Preset | Efeito resumido |
|---|---|
balanced | Comportamento padrão do motor |
fast | Desliga DeliveryComparator, PlanReviewer, ResultEvaluator, narração, avatar persona; ativa terseOutput |
turbo | Adiciona desligamento de RAG/Web/prefilters/sessionContext, corta retries, persistenceMode: 'deferred' |
Flags individuais (override fino): skipDeliveryComparator, skipAvatarPersona, skipResultEvaluator, skipNarration, skipActionPrefilter, skipConstraintPrefilter, skipSessionContext, enableRag: false, terseOutput, persistenceMode, avatarPersonaMode (fused | rewrite | off).
O motor expõe result.metrics.perfMode = { preset, resolvedFlags } quando um preset foi aplicado.
Clusters feature-flagged no catálogo
Além das ~60 ações base, o GET /listActions pode incluir clusters conforme variáveis de ambiente:
| Cluster | Flag (opt-out) | Ações (exemplos) |
|---|---|---|
| Advisor V4 | ADVISOR_V4_ENABLED=false | resolveAdvisorScope, compileAdvisorReportV4, verifyIssueV4, … (~37) |
| Canvas / side-track | CANVAS_DYNAMIC_CONTENT_ENABLED=false | pushCanvasEntry, mountCanvasFrame, sideTrackAgent, … (~10) |
| Decision Assistant | ST_DECISION_ASSISTANT_ENABLED=false | askDecisionChain, createDecisionChain, editDecisionChain, … (4) |
Workflow builder (addWorkflowNode, importN8nWorkflow, …) não entra no catálogo padrão de listActions — só no mode workflowBuilder.
SecOps crypto (encryptJson, hashFromText, …) e tracers investigateV3 (toolCallTracer, timelineReverseTrace, …) fazem parte do catálogo base quando registrados no deploy.
Relação com stLayer
| Pergunta | Resposta |
|---|---|
conversationId define a camada? | Não — indica onde persistir; stLayer vem do token. |
Mode restringe ações além do stLayer? | Sim — intersecta com o catálogo permitido na camada. |
Integrador define stLayer no body? | Não — derivado do contexto de autenticação. |
Integrador define mode? | Depende do produto — via modeInput quando o caller Tolky expõe. |
Para isolamento por tenant/host, veja Camadas de permissão.