Recebe uma instrução em linguagem natural (ex: “Crie um formulário de pré-vendas com email e telefone”) e devolve um plano com etapas ordenadas. Com executeAfterPlan: true, executa o plano em seguida.

​
Endpoint

POST /api/externalAPIs/public/formFlow/reasonFormFlowPlan

​
Parâmetros

instructions
string
required

Instrução em linguagem natural descrevendo o que deve ser feito.

hostId
string (UUID)

ID do host. Se omitido, é derivado do token.

avatarId
string (UUID)

ID do avatar para enriquecer o contexto do planejamento.

retryFromIntentId
string (UUID)

ID de um intent anterior para replanejamento. Quando fornecido, o reasoning injeta o feedback da execução anterior (warnings, issues, etapas com falha) no prompt para gerar um plano corrigido.

executeAfterPlan
boolean
default: "false"

Se true, executa os steps gerados imediatamente após o planejamento.

enrichUnderstanding
boolean
default: "false"

Enriquece o entendimento das instruções com busca externa e reasoning criativo. Pode ser enviado no nível raiz ou dentro de options.

globalData
object

GlobalData helper. Se omitido, será criado automaticamente.

options
object

​
Exemplo

curl -X POST {{BASE_URL}}/api/externalAPIs/public/formFlow/reasonFormFlowPlan \
  -H "Authorization: Bearer {{TOKEN}}" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Crie um formulário de pré-vendas para leads com as variáveis email e telefone já existentes",
    "options": {
      "maxSteps": 15,
      "model": "gpt-oss-120b",
      "provider": "cerebras"
    },
    "executeAfterPlan": false
  }'

​
Resposta

{
  "success": true,
  "intentId": "880e8400-e29b-41d4-a716-446655440003",
  "requestControlId": "990e8400-e29b-41d4-a716-446655440004",
  "steps": [
    {
      "stepNumber": 1,
      "action": "queryFormVariables",
      "generalInstructions": "Buscar as variáveis email e telefone que já existem no sistema",
      "expectedOutcome": "Lista de variáveis com seus IDs",
      "requiresValidation": false,
      "validationQuestion": null,
      "validationInstructions": null
    },
    {
      "stepNumber": 2,
      "action": "createCatalog",
      "generalInstructions": "Criar formulário chamado Pré-vendas com escopo lead",
      "expectedOutcome": "Formulário criado com ID retornado",
      "requiresValidation": true,
      "validationQuestion": "Deseja confirmar a criação do formulário?",
      "validationInstructions": "Verifique os campos antes de confirmar."
    }
  ],
  "context": {
    "catalogsCount": 5,
    "variablesCount": 10,
    "responsesCount": 20,
    "valuesCount": 30
  },
  "variablesAnalysis": {
    "mentionedCount": 3,
    "existingCount": 2,
    "toCreateCount": 1,
    "toUpdateCount": 0
  },
  "metadata": {
    "reasoningTime": 1234,
    "model": "gpt-oss-120b",
    "provider": "cerebras",
    "maxSteps": 15
  },
  "executionResults": null,
  "executionError": null,
  "executionFeasibilityAnalysis": null,
  "planningFeedback": null,
  "auditLog": [
    "[ReasonFormFlowPlan] Iniciando reasoning...",
    "[ReasonFormFlowPlan] Buscando dados do banco para contexto...",
    "[ReasonFormFlowPlan] Plano gerado com 2 etapa(s)."
  ]
}

​
Campos da Resposta

success
boolean
Se o planejamento foi concluído com sucesso.
intentId
string | null
ID do intent criado em form_sequential_thinking. Disponível quando o requestControl foi criado com sucesso.
requestControlId
string | null
ID do request_control criado para rastreabilidade.
steps
array
context
object

Snapshot de quantos registros existem no host usados como contexto.

variablesAnalysis
object

Resumo da análise de variáveis mencionadas nas instruções.

metadata
object

Metadados sobre a execução do reasoning.

executionResults
array | null

Resultados da execução dos steps. Preenchido apenas quando executeAfterPlan: true.

executionError
string | null
Erro ocorrido durante a execução dos steps, se houver.
executionFeasibilityAnalysis
object | null
Análise de viabilidade gerada após a execução. Disponível apenas quando executeAfterPlan: true.
planningFeedback
object | null
Feedback estruturado sobre o plano gerado, produzido ao final da execução. Contém warnings, issues e etapas com falha que podem ser usados em um replanejamento via retryFromIntentId.
auditLog
array
Log de execução do raciocínio.
error
string | null
Mensagem de erro, se houver.

Para acompanhar execuções em andamento, combine este endpoint com os eventos WebSocket form_flow_step_executed e form_flow_plan_generated.

​
Erros

CódigoDescrição
400instructions ausente, hostId não encontrado ou maxSteps inválido
401Token inválido ou ausente
500Erro interno do servidor ou timeout
Doc Analyzer - buildInstructionFromNaturalRetomar Execução