O Sequential Thinking é o motor de orquestração da plataforma. Recebe uma instrução em linguagem natural (ex: “crie um formulário com nome, e-mail e telefone”), monta um plano de steps e executa cada um com contexto, persistência e controle de falhas. Todos os domínios reutilizam o mesmo motor em vez de reinventar planejamento, execução e retomada.

​
Por que isso importa

  • Evita duplicação de lógica entre produtos e squads
  • Garante padrão único de execução, erros, retries e auditoria
  • Permite pausar, retomar e cancelar fluxos longos com segurança
  • Expõe eventos de progresso para frontend em tempo real
  • Reduz custo quando o fluxo é fixo usando PlanTemplate (sem custo de planejamento)

​
Base URL

{{BASE_URL}}/api/externalAPIs/public/sequentialThinking

Use {{BASE_URL}} nos exemplos. Em ambiente local via gateway/webchat, substitua por http://localhost:3000/api/externalAPIs/public/sequentialThinking. Chamando o backend-service diretamente, use http://localhost:8080/api/externalAPIs/public/sequentialThinking.

​
Autenticação

  • listActions e run: rotas públicas, sem autenticação (testes).
  • runWithAgents, getIntentStatus e getKeeperSnapshot: exigem token Bearer. O KrakenD injeta X-Host-Id e X-Domain-Id nos headers quando aplicável.
Authorization: Bearer {TOKEN}

Em ambiente local, quando os headers do KrakenD não estão presentes, o hostId pode ser passado no body (runWithAgents) ou na query string (getIntentStatus, getKeeperSnapshot).

Os defaults de options documentados em run e runWithAgents refletem o motor quando o cliente omite options. O bloco costControl de GET /listActions usa os mesmos defaults para estimativa de custo.

​
Como ler esta documentação

​
Endpoints da API

  • GET /listActions — lista o catálogo de ações disponíveis no host
  • POST /run — executa em sandbox (sem efeitos colaterais)
  • POST /runWithAgents — executa em produção com agentes reais
  • GET /getIntentStatus — consulta estado de execução assíncrona (polling)
  • GET /getKeeperSnapshot — lê histórico de eventos para diagnóstico

Use /run para validar prompts e comportamento do motor sem efeitos colaterais.
Use /runWithAgents para execução real em produção.
Use /getIntentStatus após runWithAgents com async: true para polling do resultado.
Use /getKeeperSnapshot quando precisar inspecionar o que aconteceu numa execução passada (suporte, troubleshooting, replay).

​
Estruturas de dados

​
StepResult

CampoTipoDescrição
stepNumbernumberPosição do step no plano (1-based)
actionstringNome da ação executada
statusstringEstado do step — ver tabela abaixo
resultobjectDados retornados pela ação
paramsobjectParâmetros capturados pelo LLM
errorstringMensagem de erro (quando status é "failed")
durationMsnumberTempo de execução em milissegundos

Valores possíveis de status:

StatusO que significa
completedO step rodou com sucesso
failedO step falhou após esgotar retries
skippedO step foi pulado (ex.: branch não escolhido, pré-condição não atendida)
interruptedO motor pausou aqui para pedir informação ao usuário; veja Quando o motor pausa para perguntar algo
replan_recommendedO step terminou, mas o motor decidiu replanejar antes de seguir (ajuste de rota interno)

​
Eventos (array events)

Cada item segue o envelope documentado em Eventos e WebSocket: type, intentId, sessionId (quando houver sessão), timestamp, seq, chapterId, chapterKey, payload.

Resumo: use seq para ordenar; chapter_started / chapter_completed delimitam fases (initialization, preparation, planning, feasibility, continuation_planning, execution, containment, recommendation_replan, delivery_comparison, full_retry, audit, compile). O evento final_answer_ready marca a fronteira em que a mensagem final está garantida.

O campo progress em eventos de step é tipicamente:

Math.round((stepNumber / totalSteps) * 100);

Para o catálogo completo (incluindo delivery comparison, full retry, RAG, query DB, cost_reconciled, performance_report, cancelamento e Socket.IO), consulte Eventos e WebSocket.

​
Métricas (objeto metrics)

CampoTipoDescrição
totalDurationMsnumberDuração total da execução em milissegundos
totalLlmCallsnumberTotal de chamadas ao LLM
totalTokensUsedobject{ prompt: number, completion: number }
totalCostInDollarsnumberCusto total acumulado em dólares
stepDurationsobjectDuração por step: { [stepNumber]: number }

​
FeasibilityAnalysis

CampoTipoDescrição
feasiblebooleanSe o plano é viável
issuesstring[]Bloqueadores — execução não deve prosseguir
warningsstring[]Alertas — execução pode prosseguir, mas com risco
recommendationsstring[]Sugestões de melhoria do plano

​
Contrato de Retorno (resultado completo)

CampoTipoDescrição
successbooleanSe a execução foi bem-sucedida
intentIdstringUUID persistido — use para retomar execuções
finalAnswerobjectSempre presente, mesmo em falhas e cancelamentos
stepsStepResult[]Array de resultados por step
feasibilityAnalysisFeasibilityAnalysisAnálise de viabilidade do plano
metricsobjectMétricas de execução (ver tabela acima)
auditLogstring[]Log textual da execução
auditInsightobject | nullDiagnóstico de falha gerado pelo Failure Audit (presente quando auditOnFailure: true e houve falha)
interruptedbooleanQuando true, a execução pausou para input do usuário (não é falha)
interruptionPayloadobjectPergunta e opções quando interrupted: true
continuationDepthnumberQuantas vezes a execução já pausou para continuação
errorstring | nullMensagem de erro quando success é false

O campo finalAnswer é sempre garantido pelo motor — inclusive em falhas, cancelamentos e bloqueios por inviabilidade. Em casos de falha, o motor compõe uma resposta explicativa com message, executionStatus, explanation e retryGuidance.

WebSocketVisão Geral