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 /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.

executeAfterPlan
boolean
default: "false"

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

options
object

​
Exemplo

curl -X POST {BASE_URL}/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": 6,
      "model": "gpt-oss-120b",
      "provider": "cerebras"
    },
    "executeAfterPlan": false
  }'

​
Resposta

{
  "success": true,
  "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
    },
    {
      "stepNumber": 2,
      "action": "createCatalog",
      "generalInstructions": "Criar formulário chamado Pré-vendas com escopo lead",
      "expectedOutcome": "Formulário criado com ID retornado",
      "requiresValidation": true
    }
  ],
  "context": {
    "catalogsCount": 5,
    "variablesCount": 10,
    "responsesCount": 20,
    "valuesCount": 30
  },
  "metadata": {
    "reasoningTime": 1234,
    "model": "gpt-oss-120b",
    "provider": "cerebras",
    "maxSteps": 6
  },
  "executionResults": null,
  "auditLog": [
    "[ReasonFormFlowPlan] Iniciando reasoning...",
    "[ReasonFormFlowPlan] Plano gerado com 2 etapa(s)."
  ]
}

​
Campos da Resposta

success
boolean
Se o planejamento foi concluído com sucesso.
steps
array
context
object
Snapshot de quantos registros existem no host (catálogos, variáveis, respostas, valores).
executionResults
object | null
Preenchido apenas quando executeAfterPlan: true.
auditLog
array
Log de execução do raciocínio.

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
401Token inválido ou ausente
500Erro interno do servidor
Capturar a partir de ConversasRetomar Execução