Sequential Thinking
Motor genérico que transforma instruções em plano executável, com persistência, retry, auditoria e eventos em tempo real
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, substitua por http://localhost:3000/api/externalAPIs/public/sequentialThinking.
Autenticação
listActionserun: rotas públicas, sem autenticação (testes).runWithAgents: exige token Bearer. O KrakenD injetaX-Host-IdeX-Domain-Idnos headers.
Authorization: Bearer {TOKEN}
Em ambiente local, quando os headers do KrakenD não estão presentes, o hostId pode ser passado no body.
Como ler esta documentação
- Visão geral do motor — o que faz, quando usar e exemplos práticos
- Eventos e WebSocket — envelope, catálogo completo e contrato
/sequential-thinking - Listar ações disponíveis — catálogo de ações e schemas
- Executar com sandbox — teste local com ações simuladas
- Executar com agentes reais — produção com ações reais
Endpoints da API
GET /listActionsPOST /runPOST /runWithAgents
Use /run para validar prompts e comportamento do motor sem efeitos colaterais.
Use /runWithAgents para execução real em produção.
Estruturas de dados
StepResult
| Campo | Tipo | Descrição |
|---|---|---|
stepNumber | number | Posição do step no plano (1-based) |
action | string | Nome da ação executada |
status | string | "completed" | "failed" | "skipped" |
result | object | Dados retornados pela ação |
params | object | Parâmetros capturados pelo LLM |
error | string | Mensagem de erro (quando status é "failed") |
durationMs | number | Tempo de execução em milissegundos |
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)
| Campo | Tipo | Descrição |
|---|---|---|
totalDurationMs | number | Duração total da execução em milissegundos |
totalLlmCalls | number | Total de chamadas ao LLM |
totalTokensUsed | object | { prompt: number, completion: number } |
totalCostInDollars | number | Custo total acumulado em dólares |
stepDurations | object | Duração por step: { [stepNumber]: number } |
FeasibilityAnalysis
| Campo | Tipo | Descrição |
|---|---|---|
feasible | boolean | Se o plano é viável |
issues | string[] | Bloqueadores — execução não deve prosseguir |
warnings | string[] | Alertas — execução pode prosseguir, mas com risco |
recommendations | string[] | Sugestões de melhoria do plano |
Contrato de Retorno (resultado completo)
| Campo | Tipo | Descrição |
|---|---|---|
success | boolean | Se a execução foi bem-sucedida |
intentId | string | UUID persistido — use para retomar execuções |
finalAnswer | object | Sempre presente, mesmo em falhas e cancelamentos |
steps | StepResult[] | Array de resultados por step |
feasibilityAnalysis | FeasibilityAnalysis | Análise de viabilidade do plano |
metrics | object | Métricas de execução (ver tabela acima) |
auditLog | string[] | Log textual da execução |
auditInsight | object | null | Diagnóstico de falha gerado pelo Failure Audit (presente quando auditOnFailure: true e houve falha) |
error | string | null | Mensagem 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.