Visão Geral

O Sequential Thinking transforma uma instrução em linguagem natural em execução orientada por steps. Você diz o que quer; o motor organiza a sequência e executa com segurança.

​

O que ele faz

• Interpreta instruções em linguagem natural
• Quebra a tarefa em steps executáveis
• Executa cada step na ordem correta, respeitando dependências
• Suporta steps condicionais com branches resolvidos por LLM
• Executa grupos de steps independentes em paralelo
• Reage a falhas com retry, skip ou replan automático (contenção)
• Revisa o plano gerado com um segundo modelo de raciocínio (reviewPlan)
• Mantém histórico e estado para retomada via intentId
• Emite eventos de progresso para o frontend (transport-agnostic)
• Retorna métricas de execução, custo e diagnóstico de falha

​

Quando usar

Use quando você precisa automatizar um fluxo com múltiplas etapas, especialmente se:

• A tarefa depende de passos encadeados
• Você precisa rastrear progresso em tempo real
• É importante retomar em caso de falha/interrupção
• O fluxo pode variar conforme o pedido do usuário

​

Quando não usar

Não use para operações de 1 passo, sem necessidade de contexto, retomada ou observabilidade.

​

Capacidades principais

​

1) Execução com ações reais

Use POST /runWithAgents para rodar com ações de produção.

Exemplo:

curl -X POST "{{BASE_URL}}/runWithAgents" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Busque informações sobre planos e responda de forma objetiva."
  }'

​

2) Teste seguro em sandbox

Use POST /run para validar comportamento sem efeitos colaterais externos.

Exemplo:

curl -X POST "{{BASE_URL}}/run" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Converta o texto para maiúsculas e retorne o resultado."
  }'

​

3) Descoberta de capacidades disponíveis

Use GET /listActions para listar ações e parâmetros esperados.

curl -X GET "{{BASE_URL}}/listActions"

​

Exemplo de retorno (resumido)

{
  "data": {
    "result": {
      "success": true,
      "intentId": "uuid-da-execucao",
      "steps": [
        {
          "stepNumber": 1,
          "action": "ragSearch",
          "status": "completed"
        },
        {
          "stepNumber": 2,
          "action": "respondToUser",
          "status": "completed"
        }
      ],
      "metrics": {
        "totalDurationMs": 4500,
        "totalLlmCalls": 3
      },
      "error": null
    },
    "events": [
      { "type": "plan_ready" },
      { "type": "step_started" },
      { "type": "step_completed" },
      { "type": "execution_completed" }
    ]
  }
}

​

Eventos que você pode consumir no frontend

Todos os eventos seguem o mesmo envelope: type, intentId, sessionId (opcional), timestamp, seq, chapterId, chapterKey, payload. O seq ordena a sequência; chapterKey identifica a fase entre initialization, preparation, planning, feasibility, continuation_planning, execution, containment, recommendation_replan, delivery_comparison, full_retry, audit e compile.

Em alto nível: lifecycle de capítulo (chapter_*), preparação e planejamento, viabilidade, execução de steps (incluindo paralelos e branches), contenção, comparação de entrega, full retry, auditoria, compilação da resposta, métricas (token_usage_updated, cost_reconciled, performance_report) e o evento de fronteira final_answer_ready.

Para streaming em tempo real, o motor expõe onEvent (transport-agnostic). O namespace WebSocket é /sequential-thinking (sessão, intent e host). Lista completa de tipos, payloads e contrato Socket.IO: Eventos e WebSocket.

​

Controle de execução disponível

O motor oferece:

• Limite de steps por execução (maxSteps)
• Timeout por step (stepTimeoutMs)
• Política de retry por ação
• Cancelamento via AbortSignal
• Retomada de execução via intentId
• Modo de validação sem execução real (dryRun)
• Revisão do plano com modelo de raciocínio (reviewPlan)
• Enriquecimento das instruções com busca web (enableWebContext)
• Replan automático em falha de step (maxContainmentRetries)
• Replanning automático quando o plano é inviável (maxFeasibilityRetries) — o motor gera uma instrução corretiva e re-executa PREPARATION → PLANNING; padrão 1, use 0 para desabilitar
• Auditoria de falha com diagnóstico por LLM (auditOnFailure)

​

Boas práticas de uso

• Escreva instruções claras, com objetivo e resultado esperado
• Consulte listActions antes para entender limitações
• Use run no desenvolvimento e runWithAgents em produção
• No cliente, sempre cheque result.success antes de usar a resposta final

​

Casos de uso comuns

• Buscar informação e responder ao usuário com contexto
• Encadear ações que dependem da saída anterior
• Automatizar fluxos de suporte, atendimento ou operação
• Executar processos longos com feedback em tempo real

​

Resumo rápido

Você entrega uma instrução; o motor entrega execução estruturada, observável e resiliente.

​

Quando usar cada endpoint